tidy-html5/man/tidy1.xsl.in

495 lines
15 KiB
XML
Raw Normal View History

2015-05-19 14:51:15 +00:00
<?xml version="1.0"?>
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
For generating the `tidy.1` man page from the
output of `tidy -xml-help` and `tidy -xml-config`
2015-05-19 14:51:15 +00:00
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
(c) 2005-2017 (W3C) MIT, ERCIM, Keio University
See tidy.h for the copyright notice.
2015-05-19 14:51:15 +00:00
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Written by Jelks Cabaniss and Arnaud Desitter
2015-05-19 14:51:15 +00:00
-->
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:strip-space elements="description" />
<xsl:output method="text" />
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
The default template match is to the document passed on the
command line to the XSLT processor, currently "tidy-help.xml".
For the detailed config options section however, the template
match is to the file "tidy-config.xml". This is captured in
the $CONFIG variable, declared here. CMAKE configure will
substitute TIDYCONFIG during the build. Shell scripts will
have to do the same.
2015-05-19 14:51:15 +00:00
-->
<xsl:variable name="CONFIG" select="document('@TIDYCONFIG@')"/>
2015-05-19 14:51:15 +00:00
<!-- Main Template: -->
<xsl:template match="/">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:call-template name="header-section" />
<xsl:call-template name="cmdline-section" />
<xsl:call-template name="manpage-see-also-section" />
2015-05-19 14:51:15 +00:00
</xsl:template>
<!-- Named Templates: -->
<xsl:template name="header-section">
<xsl:text/>.\" tidy man page for the HTML Tidy
.TH TIDY 1 "<xsl:value-of select="cmdline/@version" />" "HTML Tidy" "<xsl:value-of select="cmdline/@version" />"
</xsl:template>
<xsl:template name="cmdline-section">
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
\fBtidy\fR - check, correct, and pretty-print HTML(5) files
.SH SYNOPSIS
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fBtidy\fR [\fIoptions\fR] [\fIfile\fR ...] [\fIoptions\fR] [\fIfile\fR ...] ...
2015-05-19 14:51:15 +00:00
.SH DESCRIPTION
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Tidy reads HTML, XHTML, and XML files and writes cleaned-up markup.
For HTML variants, it detects, reports, and corrects many common coding errors
and strives to produce visually equivalent markup that is both conformant
to the HTML specifications and that works in most browsers.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
A common use of Tidy is to convert plain HTML to XHTML.
For generic XML files, Tidy is limited to correcting basic well-formedness
errors and pretty printing.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
If no input file is specified, Tidy reads the standard input.
If no output file is specified, Tidy writes the tidied markup to the
standard output. If no error file is specified, Tidy writes messages
to the standard error.
2015-05-19 14:51:15 +00:00
.SH OPTIONS
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Tidy supports two different kinds of options.
Purely \fIcommand-line\fR options, starting with a single dash '\fB-\fR',
can only be used on the command-line, not in configuration files.
They are listed in the first part of this section.
\fIConfiguration\fR options, on the other hand, can either be passed
on the command line, starting with two dashes \fB--\fR,
or specified in a configuration file,
using the option name without the starting dashes.
They are listed in the second part of this section.
.LP
For \fIcommand-line\fR options that expect a numerical argument,
a default is assumed if no meaningful value can be found.
On the other hand, \fIconfiguration\fR options cannot be used
without a value; a \fIconfiguration\fR option without a value
is simply discarded and reported as an error.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Using a \fIcommand-line\fR option is sometimes equivalent to setting
the value of a \fIconfiguration\fR option. The equivalent option
and value are shown in parentheses in the list below, as they would
appear in a configuration file. For example,
\fB-quiet, -q\fR (\fIquiet: yes\fR) means that using the
\fIcommand-line\fR option \fB-quiet\fR or \fB-q\fR
is equivalent to setting the \fIconfiguration\fR option
\fIquiet\fR to \fIyes\fR.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Single-letter \fIcommand-line\fR options without an associated value
can be combined; for example '\fB-i\fR', '\fB-m\fR' and '\fB-u\fR'
may be combined as '\fB-imu\fR'.<xsl:text/>
<xsl:call-template name="show-cmdline-options" />
.LP
\fIConfiguration\fR options can be specified
by preceding each option with \fB--\fR at the command line,
followed by its desired value,
OR by placing the options and values in a configuration file,
and telling tidy to read that file with the \fB-config\fR option:
2015-05-19 14:51:15 +00:00
.LP
.in 1i
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fBtidy --\fR\fIoption1 \fRvalue1 \fB--\fIoption2 \fRvalue2 ...
2015-05-19 14:51:15 +00:00
.br
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fBtidy -config \fIconfig-file \fR ...
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fIConfiguration\fR options can be conveniently grouped
in a single config file.
2015-05-19 14:51:15 +00:00
A Tidy configuration file is simply a text file, where each option
is listed on a separate line in the form
.LP
.in 1i
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fIoption1\fR: \fIvalue1\fR
2015-05-19 14:51:15 +00:00
.br
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fIoption2\fR: \fIvalue2\fR
2015-05-19 14:51:15 +00:00
.br
etc.
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
The permissible values for a given option depend on the option's Type.
There are five Types: \fIBoolean\fR, \fIAutoBool\fR, \fIDocType\fR,
\fIEnum\fR, and \fIString\fR.
\fIBoolean\fR Types allow any of \fByes/no, y/n, true/false, t/f, 1/0\fR.
\fIAutoBool\fRs allow \fBauto\fR in addition to the values allowed
by \fIBooleans\fR.
\fIInteger\fR Types take non-negative integers.
\fIString\fR Types generally have no defaults, and you should provide them in
non-quoted form (unless you wish the output to contain the literal quotes).
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fIEnum\fR, \fIEncoding\fR, and \fIDocType\fR Types have a fixed repertoire
of items, which are listed in the \fISupported values\fR sections below.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
You only need to provide options and values for those whose defaults you wish
to override, although you may wish to include some already-defaulted options
and values for the sake of documentation and explicitness.
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Here is a sample config file, with at least one example of each of
the five Types:
2015-05-19 14:51:15 +00:00
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fI// sample Tidy configuration options
2015-05-19 14:51:15 +00:00
output-xhtml: yes
add-xml-decl: no
doctype: strict
char-encoding: ascii
indent: auto
wrap: 76
repeated-attributes: keep-last
error-file: errs.txt
\fR
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Below is a summary and brief description of each of the options.
They are listed alphabetically within each category.<xsl:text/>
2015-05-19 14:51:15 +00:00
<xsl:call-template name="show-config-options" />
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SH ENVIRONMENT
.TP
.B HTML_TIDY
Name of the default configuration file. This should be an absolute path,
since you will probably invoke \fBtidy\fR from different directories.
The value of HTML_TIDY will be parsed after the compiled-in default
(defined with -DTIDY_CONFIG_FILE), but before any of the files specified
using \fB-config\fR.
.TP
.B RUNTIME CONFIGURATION FILES
In general, Unix-like systems support runtime configuration files. Use
\fBtidy -help-env\fR to see if your version of \fBtidy\fR supports them, and
where they are expected to be on your system.
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SH "EXIT STATUS"
.IP 0
All input files were processed successfully.
.IP 1
There were warnings.
.IP 2
There were errors.
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template name="show-cmdline-options">
.SS File manipulation
<xsl:call-template name="cmdline-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">file-manip</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
.SS Processing directives
<xsl:call-template name="cmdline-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">process-directives</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
.SS Character encodings
<xsl:call-template name="cmdline-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">char-encoding</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
.SS Miscellaneous
<xsl:call-template name="cmdline-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">misc</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
.SS XML
<xsl:call-template name="cmdline-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">xml</xsl:with-param>
</xsl:call-template>
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template name="cmdline-detail">
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
For each option in one of the categories/classes, provide its
2015-05-19 14:51:15 +00:00
1. names
2. description
3. equivalent configuration option
-->
<xsl:param name="category" />
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:for-each select='/cmdline/option[@class=$category]'>
2015-05-19 14:51:15 +00:00
<xsl:text>
.TP
</xsl:text>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:call-template name="process-names" />
<xsl:call-template name="process-eqconfig" />
<xsl:text>
2015-05-19 14:51:15 +00:00
</xsl:text>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:apply-templates select="description" />
</xsl:for-each>
2015-05-19 14:51:15 +00:00
</xsl:template>
<!-- Used only in the cmdline section -->
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:template name="process-names">
2015-05-19 14:51:15 +00:00
<xsl:for-each select="name">
<xsl:text />\fB<xsl:value-of select="." />\fR<xsl:text />
<xsl:if test="position() != last()">
<xsl:text>, </xsl:text>
</xsl:if>
</xsl:for-each>
</xsl:template>
<!-- Used only in the cmdline section -->
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:template name="process-eqconfig">
2015-05-19 14:51:15 +00:00
<xsl:if test="string-length(eqconfig) &gt; 0">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:for-each select="eqconfig">
<xsl:text> (\fI</xsl:text>
<xsl:value-of select="." />
<xsl:text>\fR)</xsl:text>
</xsl:for-each>
2015-05-19 14:51:15 +00:00
</xsl:if>
</xsl:template>
<xsl:template name="show-config-options">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SS HTML, XHTML, XML options<xsl:text/>
2015-05-19 14:51:15 +00:00
<xsl:call-template name="config-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">markup</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SS Diagnostics options
2015-05-19 14:51:15 +00:00
<xsl:call-template name="config-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">diagnostics</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SS Pretty Print options
2015-05-19 14:51:15 +00:00
<xsl:call-template name="config-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">print</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SS Character Encoding options
2015-05-19 14:51:15 +00:00
<xsl:call-template name="config-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">encoding</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.SS Miscellaneous options
2015-05-19 14:51:15 +00:00
<xsl:call-template name="config-detail">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:with-param name="category">misc</xsl:with-param>
2015-05-19 14:51:15 +00:00
</xsl:call-template>
</xsl:template>
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Note that any templates called implicitly or explicitly
from the "config-detail" template below will match on
the document referred to by the $CONFIG variable, i.e.,
the file "tidy-config.xml", created by running
2015-05-19 14:51:15 +00:00
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
tidy -xml-config > tidy-config.xml
2015-05-19 14:51:15 +00:00
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
The $CONFIG variable is set at the top level of this
stylesheet.
2015-05-19 14:51:15 +00:00
-->
<xsl:template name="config-detail">
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
For each option in one of the 5 categories/classes, provide its
2015-05-19 14:51:15 +00:00
1. name
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
2. Type
2015-05-19 14:51:15 +00:00
3. default (if any)
4. example (if any)
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
5. description
6. seealso (if any)
2015-05-19 14:51:15 +00:00
-->
<xsl:param name="category" />
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
.rs<xsl:text/>
<xsl:for-each select='$CONFIG/config/option[@class=$category]'>
<xsl:sort select="name" order="ascending" />
2015-05-19 14:51:15 +00:00
.TP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text>\fB</xsl:text>
<xsl:text>--</xsl:text><xsl:apply-templates select="name" />
<xsl:text>\fR</xsl:text>
<xsl:text> </xsl:text>
<xsl:text>\fI</xsl:text>
<xsl:apply-templates select="type" />
<xsl:text>\fR</xsl:text>
<xsl:apply-templates select="default" />
2015-05-19 14:51:15 +00:00
.br
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:apply-templates select="example" />
2015-05-19 14:51:15 +00:00
<xsl:apply-templates select="description" />
<xsl:call-template name="seealso" />
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
</xsl:for-each>
2015-05-19 14:51:15 +00:00
</xsl:template>
<!-- Used only in the config options section: -->
<xsl:template name="seealso">
<xsl:if test="seealso">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text>
2015-05-19 14:51:15 +00:00
</xsl:text>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
See also: <xsl:text />
2015-05-19 14:51:15 +00:00
<xsl:for-each select="seealso">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text />\fB--<xsl:value-of select="." />\fR<xsl:text />
2015-05-19 14:51:15 +00:00
<xsl:if test="position() != last()">
<xsl:text>, </xsl:text>
</xsl:if>
</xsl:for-each>
</xsl:if>
</xsl:template>
<!-- Used only in the config options section: -->
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:template match="default[.!='']">
<xsl:text> (</xsl:text>
<xsl:text>\fB</xsl:text>
<xsl:value-of select="." />
<xsl:text>\fR</xsl:text>
<xsl:text> if unset)</xsl:text>
2015-05-19 14:51:15 +00:00
</xsl:template>
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Do not print redundant examples
(identical for all values of the same Type)
2015-05-19 14:51:15 +00:00
-->
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:template match="
option[
type = 'Boolean'
or type = 'AutoBool'
or type = 'Integer'
or type = 'Tag names'
]/example" priority="2"
/>
2015-05-19 14:51:15 +00:00
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<!-- Used only in the config options section: -->
<xsl:template match="example[.!='']">
<xsl:text>Supported values: </xsl:text>
<xsl:text>\fB</xsl:text>
<xsl:value-of select="." />
<xsl:text>\fR</xsl:text>
<xsl:text>&#xA;&#xA;</xsl:text>
</xsl:template>
2015-05-19 14:51:15 +00:00
<!-- Called from the templates below matching `code`, `em`, `strong`: -->
<xsl:template name="escape-backslash">
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
Since backslashes are "special" to the *roff processors used
to generate man pages, we need to escape backslash characters
appearing in content with another backslash.
2015-05-19 14:51:15 +00:00
-->
<xsl:choose>
<xsl:when test="contains(.,'\')">
<xsl:value-of select=
"concat( substring-before(.,'\'), '\\', substring-after(.,'\') )" />
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates />
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Appears at the bottom of the man page: -->
<xsl:template name="manpage-see-also-section">
.SH SEE ALSO
For more information about HTML Tidy:
.RS 4
.LP
http://www.html-tidy.org/
.RE
.LP
For more information on HTML:
.RS 4
.LP
\fBHTML: Edition for Web Authors\fR (the latest HTML specification)
.br
http://dev.w3.org/html5/spec-author-view
.LP
\fBHTML: The Markup Language\fR (an HTML language reference)
.br
http://dev.w3.org/html5/markup/
.RE
.LP
For bug reports and comments:
.RS 4
.LP
https://github.com/htacg/tidy-html5/issues/
.RE
.LP
Or send questions and comments to \fBpublic-htacg@w3.org\fR.
.LP
Validate your HTML documents using the \fBW3C Nu Markup Validator\fR:
.RS 4
.LP
http://validator.w3.org/nu/
.RE
.SH AUTHOR
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
\fBTidy\fR was written by \fBDave Raggett\fR &lt;dsr@w3.org&gt;,
and subsequently maintained by a team at http://tidy.sourceforge.net/,
2015-05-19 14:51:15 +00:00
and now maintained by \fBHTACG\fR (http://www.htacg.org).
.LP
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
The sources for \fBHTML Tidy\fR are available at
https://github.com/htacg/tidy-html5/ under the MIT Licence.
2015-05-19 14:51:15 +00:00
</xsl:template>
<!-- Regular Templates: -->
<xsl:template match="description">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:apply-templates />
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template match="a">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:apply-templates />
<xsl:text /> at \fI<xsl:value-of select="@href" />\fR<xsl:text />
2015-05-19 14:51:15 +00:00
</xsl:template>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:template match="code | em">
<xsl:text>\fI</xsl:text>
<xsl:call-template name="escape-backslash" />
<xsl:text>\fR</xsl:text>
</xsl:template>
<xsl:template match="var">
<xsl:text>\fB</xsl:text>
<xsl:call-template name="escape-backslash" />
<xsl:text>\fR</xsl:text>
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template match="p[1]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text>
.sp 1
</xsl:text>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text /><xsl:call-template name="escape-backslash" />
</xsl:template>
<xsl:template match="p[position() != 1]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text>
.sp 1
</xsl:text>
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text /><xsl:call-template name="escape-backslash" />
<xsl:text>
.sp 1
</xsl:text>
</xsl:template>
2015-05-19 14:51:15 +00:00
<xsl:template match="br">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text>
.sp 1
2015-05-19 14:51:15 +00:00
</xsl:text>
</xsl:template>
<xsl:template match="strong">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:text />\fB<xsl:call-template name="escape-backslash" />\fR<xsl:text />
2015-05-19 14:51:15 +00:00
</xsl:template>
<!--
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
The following templates
a) normalize whitespace, primarily necessary for `description`
b) do so without stripping possible whitespace surrounding `code`
d) strip leading and trailing whitespace in 'description` and `code`
(courtesy of Ken Holman on the XSL-list):
2015-05-19 14:51:15 +00:00
-->
<xsl:template match="text()[preceding-sibling::node() and
following-sibling::node()]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:variable name="ns" select="normalize-space(concat('x',.,'x'))"/>
<xsl:value-of select="substring( $ns, 2, string-length($ns) - 2 )" />
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template match="text()[preceding-sibling::node() and
not( following-sibling::node() )]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:variable name="ns" select="normalize-space(concat('x',.))"/>
<xsl:value-of select="substring( $ns, 2, string-length($ns) - 1 )" />
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template match="text()[not( preceding-sibling::node() ) and
following-sibling::node()]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:variable name="ns" select="normalize-space(concat(.,'x'))"/>
<xsl:value-of select="substring( $ns, 1, string-length($ns) - 1 )" />
2015-05-19 14:51:15 +00:00
</xsl:template>
<xsl:template match="text()[not( preceding-sibling::node() ) and
not( following-sibling::node() )]">
Merge documentation of "command-line" and "configuration" options (Issue #469) (#473) * Track tidy.1 before merging duplicate sections I am adding the file to the git repository to track and review the changes to this generated file. I will then update the XSLT transformation which produces this file to remove duplicate sections. As a first step, I will stop outputting duplicate sections; I will then merge them into existing sections. I will commit the changes to the generated file at each step. Related issue: #469 * Also track changes in text rendering of the man page tidy.1 The rendering to text was done with following command: /usr/bin/groff -Tascii -mandoc -c tidy.1 This format should make the review of differences more readable. Related issue: #469 * Remove duplicate sections: temporarily discard detailed options Related issue: #469 * Generalize command line given in SYNOPSIS The new SYNOPSIS expresses the fact that multiple files can be provided as argument, and that options and files can be mixed (options apply only to the files specified after, not the ones before). It does not explain that there are actually two types of options; this shall be detailed afterwards: simple options (aka standard options) start with single dash while configuration options start with a double dash. Only the latter can be defined in configuration files, using their name without the double dash. I have also reformatted the terms 'options' and 'file' to be underlined, to follow conventions that I observed in other man pages (ls, grep, wget...) Related issue: #469 * Regroup sentences related to options at the start of OPTIONS section This is an intermediate step before adapting the text to its new location. I will probably start the section with a paragraph to introduce the two different kinds of options. Then describe the "standard" options in more details. Then list the standard options. Then describe the configuration options in more details. Then list the configuration options, using a format similar to the one used for standard options. Related issue: #469 * Describe "standard" and "expanded" options part of OPTIONS section The section now starts with a description of both types of options, and explains that the first part of the section concerns with the "standard" options while the second part of the section concerns with the "expanded" options. More details are provided about "standard" options, which are then listed individually. More details are then provided about "expanded" options and their usage on the command line and in configuration files. The configuration options are not listed yet. In order to avoid repeating a lot of information with every separate configuration option, I will first describe common values and formats; I will then describe each option more succinctly, like "standard" options. Related issue: #469 * Remove redundant USAGE section The fact that the input file defaults to standard input and the output file to standard output is already indicated in the DESCRIPTION section. This was the only information left in this section at this point. Related issue: #469 * Delete separation line The line used to separate "standard" usage from "extended" usage. Both forms are now integrated in the common description of OPTIONS. Related issue: #469 * Delete DETAILED CONFIGURATION OPTIONS section The detailed configuration options are now described together with standard options in a common OPTIONS section. Related issue: #469 * Delete duplicate SYNOPSIS section A single generalized SYNOPSIS now encompasses both kinds of options. Related issue: #469 * Delete WARNING section, no longer relevant The WARNING referred to a separate section for the description of "standard" options. They are now described in the same OPTIONS section as "extended" options. Related issue: #469 * Copy details of configuration options and file format to OPTIONS Just before listing all the configuration options, this is the expected place to describe the "extended" options in more details. The description was already worded as an introduction to the list of configuration options. I will update this description after having compacted entries which describe individual configuration options. Related issue: #469 * Delete duplicate DESCRIPTION section This section has been merged into the generalized OPTIONS section. Related issue: #469 * List configuration options at the end of the OPTIONS section This list is very long, with lots of duplicate information repeated for entries of the same type. The description of configuration options should be compacted to match as closely as possible the description of "standard" options. Related issue: #469 * Delete duplicate OPTIONS section I contained the list of configuration options, which is now included at the end of the generalized OPTIONS section. Related issue: #469 * Delete config-section template The template was now empty. Its contents have been merged into the cmdline-section template. Related issue: #469 * Remove redundant sentence The sentence listed the five categories of configuration options. This kind of made sense when the options were listed in the following section. Now that they are listed just below, it has become redundant. Related issue: #469 * Remove colon ':' at the end of configuration options categories The categories of "standard" options do not end with a colon; no title does actually. Related issue: #469 * Remove extra lines before the list of configuration options Related issue: #469 * Add double space after period '. ' where missing For consistency with usage, sentences within paragraphs shall be separated by a double space rather than a single space. This was done in most places in the document, with only a few places missing. Related issue: #469 * Delete irrelevant comment The comment refers to cmdline section at the start of the processing of configuration options. The cmdline options are opposed to config options in the context of this transformation. They are provided through two separate XML input files. Related issue: #469 * Delete extra blank line before sample configuration file Related issue: #469 * Remove multiple empty lines after heading of each options category Related issue: #469 * Remove duplicate empty line before 'See also:' lines Related issue: #469 * Clarify the terms used for both kinds of options I removed references to "standard" (or regular) command-line options and "extended" (or detailed) options. I used the terms featured in the description of the options which output XML files describing each kind of options: -xml-help list the command line options in XML format -xml-config list all configuration options in XML format The term for single-dash options is now (purely) command-line options while double-dash options are referred to as configuration options. Related issue: #469 * Update copyright year to 2016 * Clarify configuration options equivalent to command-line options I added a paragraph to explain the equivalence of a command-line option with a configuration option and value, and to explicit the format used to describe this equivalence in the description of command-line parameters. I moved the parentheses, which were on the last line, at the end of the description, to the first line at the end of the list of names for the command-line option. Related issue: #469 * Use underlines (I) instead of bold (B) for option names in config example This is for consistency with the format used for the option names in the equivalent command-line example above, and in the other example of configuration file. Related issue: #469 * Update copyright year to 2017 * Add double dash before the name of configuration options This is a first step for the harmonization of the descriptions of command-line and configuration options. Related issue: #469 * Reformat logically to separate formatting (bold) from text (option name) Related issue: #469 * Move Type after name of configuration option This puts it in the position expected on the command line. Related issue: #469 * Move default value after config option name and Type I tried different formats for the default value: --clean Boolean:no --clean Boolean[no] and more formats after I realized that the 'default' value is not applied when the value is omitted, but when the option is not used at all: --clean Boolean (initially: no) --clean Boolean (unset: no) I selected the less confusing format: --clean Boolean (no if unset) which is self-explanatory. Related issue: #469 * Clarify that a configuration option cannot be used without a value For example, using --clean without a value is not equivalent to using -clean option: curl -s https://www.google.com | tidy --clean 2>&1 1>/dev/null | head -n 1 results in: Config: missing or malformed argument for option: clean Related issue: #469 * Add double dash before option names in 'See also' sections This is consistent with the format used at the top of the description of configuration options. Related issue: #469 * Fix order of items in comment describing documentation of config options The 'seealso' comes last actually, after the description. * Break long lines to keep source code readable in a terminal (80 characters) This makes no change on the text generated by /usr/bin/groff -Tascii -mandoc -c tidy.1 > tidy.1.txt * Only output an empty line when Example section is present Otherwise, the description starts with an empty line when no Example section is present. Related issue: #469 * Simplify matching of example elements with contents Using a template match instead of a named template, I will then add rules with higher priority to ignore examples for certain types of values, which are very redundant (identical for all options of the same type). Related issue: #469 * Do not print redundant examples Examples for Boolean and AutoBool are redundant because they are described in the main text and identical for all options of that type. Examples for Tag names are redundant because they are redundant with the name of the Type, and identical for all options of that type. Examples for Integer are redundant because they are identical for all options of that type but one, where the value 0 is followed with a comment, but even in this case the examples are redundant because the comment for the value 0 is also included in the description. Related issue: #469 * Rename 'Examples' section to 'Supported values' to clarify I also updated the description related to 'Examples' section in the introduction paragraphs to the configuration options. Related issue: #469 * Use italics consistently for the names of option types Related issue: #469 * Use capitalization with no extra style consistently for Type Previously, a mix of * Type set in bold font * Type set in regular font * "types" (quoted) * types (unquoted) was found. I replaced all instances by Type in regular font. Related issue: #469 * Consistently use bold format for option values Both parameter names and values are now in bold, while keys and values for configuration files are in italics. Related issue: #469 * Use the same format as other subsections for 'See also' The subsection is now flush left, in regular font, like the 'Supported values' subsection. The previous format was less adequate when the list wrapped to the next line (--new-inline-tags): wrapping started on the very first column, breaking the alignment of the rest of the description. Related issue: #469 * Consistently indent with 2 spaces, use a single line between templates Parts of the file were indented with 2 spaces, others with 3 spaces. Parts of the templates were separated with two empty lines, others with a single one. * Remove temporary files used for step by step comparisons of man page Related issue: #469
2017-01-08 17:19:36 +00:00
<xsl:value-of select="normalize-space(.)"/>
2015-05-19 14:51:15 +00:00
</xsl:template>
</xsl:stylesheet>