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