Re: [patch #4610] Consolidated documentation patch

[Charles Levert]

* On Saturday 2005-11-19 at 20:57:46 +0000, Julian Foad wrote:
> Charles Levert wrote:
> >
> >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:
[...]
> (which is in any case only alphabetical by short name, not long name) to, 
> for example:
[...]
> so that members of these groups of related options are adjacent:
[...]
> 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.

This is what I understood.  What I meant was
that this effectively creates implicit unlabeled
subsubsections.  There is no provision in man
for them (i.e., a well-known predefined macro),
and the visual presentation is already just
"busy" enough with sections and subsections.
But from a document structure point of view,
this is really what's happening then.  The info
documentation supports @subsubsections; would
it be appropriate to use them there (with no
new @nodes or @menus)?


> >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.

They form a coherent group of mutually exclusive
options by themselves and I would prefer
keeping it that way, in their own subsection.
As for the subsection title, here are some more
candidates, all based on words above or already
in the documentation:

   -- "Pattern Type Selection"
   -- "Expression Type Selection"
   -- "Regular Expression Type Selection"
   -- "grep Variant Selection"
   -- "Matching Engine Type Selection"

> 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".

I'll change the info structure to match the man one.

~~~

Here is another change I made that's worth
discussing:  remove use of the word PATTERN
altogether in expressions such as FILE_PATTERN,
and replace it by GLOB.  Because it's the
established name for it, because the "SEE
ALSO" section can refer the reader to glob(7)
for a more complete explanation, and because
using different words emphasizes the marked
distinction between input-line matching and
file-name matching, and the two similarly
looking but different syntax they rely on.
The context and now added explanations make it
clear what general kind of a thing a GLOB is;
having never seen the word before shouldn't be
a problem as such.  If this is accepted, maybe
the --help text should be updated to use GLOB
as well (and solve the horizontal misalignment
there caused by FILE_PATTERN being too long).


Another thing to notice is the substructure
in the "Regular Expressions" section, in both
man and info.  Subsections are new for man,
and title-reworked or simply new for info.
The important difference from the start is
that roughly the same paragraphs appeared in
both man and info, but in different order.
I mostly didn't change that order but made the
exercise of adding subsections to each.  Hence,
each document ended up with a slightly different
structure there.  Which is better?  Looking at
it, I find the man page version to have an order
and structure that is more useful and consequent.
What do you and others think?