Re: [patch #4610] Consolidated documentation patch

[Julian Foad]

Charles Levert wrote:
> * On Saturday 2005-11-19 at 20:57:46 +0000, Julian Foad wrote:
>
> > 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:

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

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

Well, kind of.  Not necessarily.  In my example above, we wouldn't necessarily 
want to separate the first four (to do with file name) from the second four (to 
do with location in file).  In fact, "--with-filename" ought to be adjacent to 
"--line-number" and "--byte-offset" because they are the options that cause 
prefixes to be printed.  It's really just a subjectively chosen order that 
can't perfectly represent the real graph of relationships between those options.

So, I don't really agree that we have to think of this as structuring the 
material into disjoint sub-subsections.

When options are completely unrelated, they ought to be (and are) in separate 
major subsections.


> 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)?

I think marking up sub-subsections would be overkill.


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

OK.  That's fine by me.

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

Any of those first three - whichever you think fits best with the rest of the 
documentation.

>    -- "grep Variant Selection"
>    -- "Matching Engine Type Selection"

Those two are what I don't like, as I don't think it's obvious to the user that 
the interpretation of PATTERN is the only behaviour affected by the choice of 
engine.  (The sort of thing I mean is that, after finding that Grep does or 
doesn't recurse into hidden directories, the user might think: "I'll try using 
each of the other "engines"; maybe one of them will recurse differently.")


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

Excellent.


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

Yes, absolutely.  I noticed you'd changed FILE_PATTERN to FILE_GLOB in the 
patch, but forgot to comment that I liked it, and didn't check to see whether 
you'd done it consistently.  Please do.


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

I didn't notice that.  I'll try to have a look later.

- Julian