On Sun, Jun 26, 2016 at 09:30:15PM -0400, Ted Unangst wrote: > I find it confusing to read a man page that constantly tells me that this > option is like some other option. I have to go read the other option, then > return here and reparse what's different. In my unimpeachable opinion, the > text for each option should be self contained, with references to other > options only if the redudant text would be too verbose. > > cat.1 has several examples of this. Saying "Implies the -n option" is longer > than simply telling me "Number the lines" and conveys much less information. > > This reworks the page to briefly explain each option. >
morning. i think you're right that "implies the -n option" is limited in the information it conveys. but... not mentioning that an option effectively sets another option opens up a big ambiguity for the reader. -b numbers the line, so do i not need to set -n? is it exactly the same? therefore the pattern is currently to say it explicitly. we could do both, but that adds verbosity. it's a trade off, no? i wouldn;t be against documenting both bits of information, but i'm not sure it's really worth it. i think it'd be wrong to lose the info about options implying other options though. and i note where you now effectively do both (-e and -t) you are at least as verbose as before, if not more. and "as according to" is much less clear than "implies". jmc > Index: cat.1 > =================================================================== > RCS file: /cvs/src/bin/cat/cat.1,v > retrieving revision 1.35 > diff -u -p -r1.35 cat.1 > --- cat.1 4 Nov 2015 21:28:01 -0000 1.35 > +++ cat.1 27 Jun 2016 01:25:12 -0000 > @@ -61,25 +61,23 @@ reads from the standard input. > The options are as follows: > .Bl -tag -width Ds > .It Fl b > -Implies the > -.Fl n > -option but doesn't count blank lines. > +Number the lines, but don't count blank lines. > .It Fl e > -Implies the > -.Fl v > -option and also prints a dollar sign > +Print a dollar sign > .Pq Ql \&$ > at the end of each line. > +Also displays non-printing characters as according to > +.Fl v . > .It Fl n > Number the output lines, starting at 1. > .It Fl s > Squeeze multiple adjacent empty lines, causing the output to be > single spaced. > .It Fl t > -Implies the > -.Fl v > -option and also prints tab characters as > +Print tab characters as > .Ql ^I . > +Also displays other non-printing characters as according to > +.Fl v . > .It Fl u > The output is guaranteed to be unbuffered (see > .Xr setvbuf 3 ) . > @@ -89,9 +87,6 @@ Control characters print as > .Ql ^X > for control-X, with the exception of the tab and EOL characters, > which are displayed normally. > -The tab character, control-I, can be made visible via the > -.Fl t > -option. > The DEL character (octal 0177) prints as > .Ql ^? . > Non-ASCII characters (with the high bit set) are printed as >
