Re: [patch #4610] Consolidated documentation patch

[Julian Foad]

Charles Levert wrote:
> > I don't see any reason to keep alphabetical order within each section.  I 
> > think keeping related options together would make more sense.
>
> Unfortunately, there is no "an.tmac" provision
> for another hierarchical level and adding one
> would definitely be out of tradition.  So I'm
> not sure about this.  But I like your suggestion
> further down, which would add one subsection.

I didn't mean we need another level of sub-sections.  Just change the order of 
the options within each section, e.g. from:

  --byte-offset
  --with-filename
  --no-filename
  --label=LABEL
  --line-number
  --initial-tab
  --unix-byte-offsets
  --null

(which is in any case only alphabetical by short name, not long name) to, for 
example:

  --with-filename
  --no-filename
  --label=LABEL
  --null
  --line-number
  --byte-offset
  --unix-byte-offsets
  --initial-tab

so that members of these groups of related options are adjacent:

  --unix-byte-offsets, --byte-offset
  --byte-offset, --line-number
  filename stuff (--with-filename, --no-filename, --label, --null)

That would be somewhat subjective, but more useful and consistent with the aim 
of the overall grouping, and less arbitrary than ordering by short-option name 
within a group.


> There is an uniformization issue:  which is
> better?  grep.texi's "grep Programs" section or
> grep.1's new "Matcher Selection" early subsection
> in the OPTIONS section?

The section title "Matcher Selection" would be better as something else, maybe 
"Expression Type", since a user is not expected to know that the software is 
structured with different "matchers"; a user may justly consider that choosing 
whether an expression is interpreted as a BRE or an ERE is on the same level as 
choosing whether case is ignored or any other "Matching Control" option.  It 
would be quite reasonable to put these in the "Matching Control" section.

Apart from that, I'd say the man page version is better.  The "info" sentence 
"There are four major variants of `grep', controlled by the following
options." is the only extra text there, and it seems redundant (a user need not 
consider those to be "major variants").  Not having those four options listed 
under the "options" section seems wrong.

The two remaining paragraphs under "grep Programs" should of course move to 
"Invoking".

- Julian