Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Man page has repeated sections #469

Closed
jidanni opened this issue Dec 4, 2016 · 13 comments
Closed

Man page has repeated sections #469

jidanni opened this issue Dec 4, 2016 · 13 comments
Labels
Docs Help Needed Technical Discussion
Milestone
5.3

Comments

@jidanni
Copy link
Contributor

jidanni commented Dec 4, 2016 

$ man tidy|col -b|perl -we '
while (<>) {
    next unless /^[[:upper:]]/;
    $h{$_}++;
}

for ( keys %h ) { print "$h{$_} $_" if $h{$_} > 1 }
'
2 OPTIONS
2 DESCRIPTION
2 SYNOPSIS
@geoffmcl
Copy link
Contributor

geoffmcl commented Dec 5, 2016

@jidanni thanks for your issue...

Now I know very little about what is supposed to be in the tidy.1 man page, its format, but those headers also appear twice in the man/tidy1.xsl.in in the source, used to generate the man page, using xsltproc ...

In other words, it does appear quite deliberate repetition! Is there something wrong with this?

Will leave it to others, who know about man page generation and format to comment... thanks...

@geoffmcl geoffmcl added this to the 5.3 milestone Dec 5, 2016
@jidanni
Copy link
Contributor Author

jidanni commented Dec 8, 2016

Find me one other man page in the world with repeated sections.

And how, when they are converted to HTML, are they supposed to link
to a unique href="#synopsis" ?

And if your professor asks you for a synopsis, do you give him two?

He asked you for a synopsis, i.e., nutshell.

@eric-brechemier
Copy link
Contributor

For comparison, the issue is not present in the Mac version of tidy:

$ tidy --version
HTML Tidy for Mac OS X released on 31 October 2006 - Apple Inc. build 15.17

$ man tidy | grep '^[A-Z]'
TIDY(1)                                                                TIDY(1)
NAME
SYNOPSIS
DESCRIPTION
OPTIONS
USAGE
ENVIRONMENT
EXIT STATUS
SEE ALSO
AUTHORS

@jidanni
Copy link
Contributor Author

jidanni commented Dec 8, 2016

OK must be a Debian bug.
Created http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=847439 .

@eric-brechemier
Copy link
Contributor

@jidanni That's not what I meant. Apple has forked the legacy version of Tidy. And the issue is not present in their version.

Reference:
https://www.apple.com/opensource/

Now, I wonder what causes this behavior.

Here is the tidy1.xsl file in the Apple version that I ran:
https://opensource.apple.com/source/tidy/tidy-15.17/tidy/htmldoc/tidy1.xsl

The version of tidy1.xsl in this project:
https://raw.githubusercontent.com/htacg/tidy-html5/master/man/tidy1.xsl.in

@jidanni
Copy link
Contributor Author

jidanni commented Dec 8, 2016

OK I'll let you guys take care of it.

@eric-brechemier
Copy link
Contributor

The end of the man page of the Mac version (SEE ALSO and AUTHORS) does not match the source code in the style sheet. It must have been post-processed, removing the extra sections (DETAILED CONFIGURATION OPTIONS, SYNOPSIS, WARNING, DESCRIPTION).

As seen in this HTML version of the legacy documentation the extra sections were already present.

@geoffmcl
Copy link
Contributor

@jidanni, yes, as indicated by @eric-brechemier, these duplicated sections have been there for a long, long, time... since circa May 2005... and are thus also present in most Apple forked sources... including the build 15.17 mentioned... thus if not in any particular generated tidy.1 doc, must be due to some additional post processing, not passed back to us...

Of course, time does not necessarily make them right, but for what ever reason, the file was split into two parts with this Mon May 2 16:12:52 2005 UTC commit, in the historic cvs repo - http://tidy.cvs.sourceforge.net/viewvc/tidy/tidy/htmldoc/tidy1.xsl?annotate=1.2 - and has basically remained that way over the 11 years since... to the current, active source - https://github.com/htacg/tidy-html5/blob/master/man/tidy1.xsl.in - in the github repo...

It does seem they wanted to separately list command line options that begin with a single -, from those that begin with --, which can also be placed in a config file... So it is not a simple matter to just delete one or the other... both option types must be there...

And if I read @eric-brechemier correctly, and he has found a tidy.1 doc without duplicates may mean that particular tidy.1 doc only gives information about one or the other type of options, which would also be very bad...

So we need help from someone who understands the tidy.1 doc generation from the .xsl file, using tidy's own xml outputs, and xsltproc, to potentially fix the situation, and still keep all the information...

I can see the two forms of SYNOPSIS could be combined, and the seconds type, the -- config options, be called say OPTIONS2, and DESCRIPTION2... or something... thanks...

@eric-brechemier
Copy link
Contributor

And if I read @eric-brechemier correctly, and he has found a tidy.1 doc without duplicates may mean that particular tidy.1 doc only gives information about one or the other type of options, which would also be very bad...

Correct. Only the single - options are described, not the -- dash options, in the version advertised as:

$ tidy --version
HTML Tidy for Mac OS X released on 31 October 2006 - Apple Inc. build 15.17

So we need help from someone who understands the tidy.1 doc generation from the .xsl file, using tidy's own xml outputs, and xsltproc, to potentially fix the situation, and still keep all the information...

@geoffmcl I can help with that. Merging the description of both types of options seems the way to go. I'll make a first pass by the end of the week with some kind of diff to visualize the changes in generated man pages.

@geoffmcl
Copy link
Contributor

@eric-brechemier look forward to what you can do to fix this situation... thanks...

eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Track tidy.1 before merging duplicate sections
69cbf82 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Also track changes in text rendering of the man page tidy.1
59ab4a2 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Remove duplicate sections: temporarily discard detailed options
571a18e 
Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Generalize command line given in SYNOPSIS
b28aa8b 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Regroup sentences related to options at the start of OPTIONS section
5a70782 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Describe "standard" and "expanded" options part of OPTIONS section
bc9951a 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Remove redundant USAGE section
2ac514e 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete separation line
df90d5b 
The line used to separate "standard" usage from "extended" usage.
Both forms are now integrated in the common description of OPTIONS.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete DETAILED CONFIGURATION OPTIONS section
1d00a97 
The detailed configuration options are now described together
with standard options in a common OPTIONS section.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete duplicate SYNOPSIS section
3629a40 
A single generalized SYNOPSIS now encompasses both kinds of options.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete WARNING section, no longer relevant
55920d3 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Copy details of configuration options and file format to OPTIONS
ddfbeb6 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete duplicate DESCRIPTION section
38dae9c 
This section has been merged into the generalized OPTIONS section.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
List configuration options at the end of the OPTIONS section
9100aa7 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete duplicate OPTIONS section
ac9b375 
I contained the list of configuration options, which is now included
at the end of the generalized OPTIONS section.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete config-section template
c9e70c8 
The template was now empty. Its contents have been merged
into the cmdline-section template.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Add double space after period '. ' where missing
7087ac1 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete irrelevant comment
7bbd20e 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Delete extra blank line before sample configuration file
fb00411 
Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Remove multiple empty lines after heading of each options category
6b7911e 
Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Dec 18, 2016
Remove duplicate empty line before 'See also:' lines
6be0599 
Related issue: htacg#469
@eric-brechemier
Copy link
Contributor

@geoffmcl I have opened a pull request for preliminary review: #473.
Can you take a look and confirm whether I am headed in the right direction?

@geoffmcl geoffmcl mentioned this issue Dec 20, 2016
Merged
@geoffmcl
Copy link
Contributor

@jidanni @eric-brechemier - see #473 for further comments on this, and a WIP PR... thanks...

eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Clarify the terms used for both kinds of options
29215e3 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Clarify configuration options equivalent to command-line options
50254e7 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Use underlines (I) instead of bold (B) for option names in config exa…
d95fad6 
…mple

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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Add double dash before the name of configuration options
7e4f58d 
This is a first step for the harmonization of the descriptions
of command-line and configuration options.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Reformat logically to separate formatting (bold) from text (option name)
bbdd971 
Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Move Type after name of configuration option
e4dc57c 
This puts it in the position expected on the command line.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Move default value after config option name and Type
767c771 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Clarify that a configuration option cannot be used without a value
c153b7a 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Add double dash before option names in 'See also' sections
b48b72c 
This is consistent with the format used at the top of the
description of configuration options.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Only output an empty line when Example section is present
87bad94 
Otherwise, the description starts with an empty line when
no Example section is present.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Simplify matching of example elements with contents
ba18ebe 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Do not print redundant examples
1492cc7 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Rename 'Examples' section to 'Supported values' to clarify
f09f096 
I also updated the description related to 'Examples' section
in the introduction paragraphs to the configuration options.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Use italics consistently for the names of option types
c3b81cb 
Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Use capitalization with no extra style consistently for Type
7919853 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Consistently use bold format for option values
7366315 
Both parameter names and values are now in bold,
while keys and values for configuration files are in italics.

Related issue: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 4, 2017
Use the same format as other subsections for 'See also'
82b2034 
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: htacg#469
eric-brechemier pushed a commit to eric-brechemier/tidy-html5 that referenced this issue Jan 7, 2017
Remove temporary files used for step by step comparisons of man page
2b13d33 
Related issue: htacg#469
geoffmcl pushed a commit that referenced this issue Jan 8, 2017
@geoffmcl
Merge documentation of "command-line" and "configuration" options (Is…
7593d7b 
…sue #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
geoffmcl added a commit that referenced this issue Jan 8, 2017
@geoffmcl
Issue #469 #473 Bump to 5.3.13
2243510
@balthisar
Copy link
Member

Given that this is in master now, I'll close this issue. Feel free to reopen this is I've missed something.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Docs Help Needed Technical Discussion
Projects
None yet
Milestone
5.3
Development

No branches or pull requests
4 participants
@eric-brechemier @jidanni @geoffmcl @balthisar