Re: [patch #4610] Consolidated documentation patch

[Charles Levert]

* On Friday 2005-11-11 at 15:59:25 +0100, Benno Schulenberg wrote:
> Charles Levert wrote:
> > +7th Edition -s-1UNIX-s0
> 
> \s  (Although I don't like to see "Unix" in allcaps.)

I wasn't sure about this one.

   -- UNIX was the original marketing term (see, e.g.,
      <http://cm.bell-labs.com/cm/cs/who/dmr/unixad.gif>).
   -- The Open Group, current owner of the
      trademark, uses UNIX.
   -- Uniformization of typographical conventions
      within the two documents:  GNU, POSIX, and UNIX.
   -- Its instigators now spell it Unix.
   -- New words tend to simplify over time,
      as they are accepted in everyday language.
      They incrementally loose their capital letters
      and their hyphen:  UNIX, Unix, unix.


> > +to report byte offsets as if the file were \s-1UNIX\s0-style
> > text file,
> 
> Missing an "a" after "were".

Fixed.


> > -Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
> > +Copyright @copyright{} 1998--2005 Free Software Foundation, Inc.
> 
> If I'm not mistaken, the years listed here should be the ones in 
> which _modified versions of this texi document were _released.

Yes.  How to interpret theses rules, though?

   -- What modifications are important enough?
   -- Is public CVS a release (mere publication)?

So:

   -- 2005: keep, no question.
   -- 2004: very minor additions and clarifications; gone?
   -- 2003: only a typo; gone.
   -- 2002: document --label; keep?
   -- 2001: already there, several options; keep.
   -- 2000: already there, several options; keep.
   -- 1999: several FAQs, -Z, -z, -H; keep.
   -- 1998: several options, rewriting; keep.

Stable releases:  1996, 1998, 1999, 2000, 2002, 2004.


> > +* GNU Options::          GNU extensions, grouped by categories.
> 
> Better "in categories" or "by category".

Fixed.


> On second thought, I don't see the point of separating the POSIX 
> options from the GNU extensions, and it kind of invalidates the 
> categorisation.  If it really should be mentioned which options are 
> POSIX, then it's easy to sum them up in some final paragrah.

How's this?  We append a parenthesized sentence
to each option, so that it's right there when
the reader needs it for portability purposes?
E.g.:  "(@samp{-i} is specified by @sc{posix}.)".
Since there are far more GNU extensions than
POSIX-specified options, it's simpler to do it
this way than the opposite way.


> So the categorisation I would do differently: put --help and -V in 
> the Other Options, as these are so generic, they really shouldn't 
> come first.
> 
> First would be Matching control: -e, -f, -i, -v, -w, -x.
> Second, Output Control: -c --color, -L, -l, -m, -o, -q, -s.
> Third, Output Line Prefix Control, with the addition of -n.
> Fourth, Context Line Control.
> Fifth, File and Directory Selection.
> Sixth, Other Options: --help, --line-buffered, --mmap, -V, -U, -z.

I'll look into this and post the result.


> > +The long option names are a @sc{gnu} extension in themselves,
> > +but these options as such are from @sc{posix} specifications.
> 
> Better without "in themselves".

Fixed, but may be gone later.


> > +Each group may contain several matching lines
> > +when they are close enough to each other
> > +that two otherwise adjacent but divided groups connect
> > +and can just merge into a single contiguous one.
> 
> "Each group may contain several matching lines
> when these lines are separated by less than 2*NUM context lines."

No:  "less than or exactly NUM_after+NUM_before context lines".
Worth the change from the original?


> > +regardless of the order in which these options may have been
> > specified. 
> 
> Better simply "were specified".

Fixed.


> > address@hidden --With-filename
> 
> No cap.

Fixed.