Re: [patch #4610] Consolidated documentation patch

[Julian Foad]

Charles Levert wrote:
> * On Friday 2005-11-18 at 14:05:26 +0000, Julian Foad wrote:
>
> > * Maybe have a look at my patch (attached) and combine the best of your and 
> > my changes.  (Sorry, I should have sent this earlier rather than trying to 
> > "finish" it first.)
>
> Merged.

That was quick!

> Note that "Erase in Line to Right" is not EL,
[...]

Thanks for correcting me.


> I have chosen to work on the actual documentation
> first, and to get it out early for review, rather
> than working on a ChangeLog entry right away.

Ah.  A philosophical disconnect.

One can't really review changes without the log entry.  I'll try to explain why.

The first change I see, in grep.1, looks trivial:

-.\" grep man page
+.\" GNU grep man page

Without knowing why you did this, all I can say is, "Fair enough; it looks like 
a harmless comment that's of no consequence at all.  I can't see that causing 
any problems nor any benefit ... unless that string is picked up by format 
converters or other utilities, perhaps to generate an index of man pages or 
something, in which case this might be important.  I wonder whether this change 
makes it more consistent or less consistent with other GNU man pages."

That is, I can't say anything useful about it.

The next change is:

+ .ie t .ds Tx \s-1T\v'.4n'\h'-.1667'E\v'-.4n'\h'-.125'X\s0
+ . el  .ds Tx TeX

and I'm thinking to myself, "Hmm... is this a good change or a bad change? 
What the hell is it anyway?"  (Excuse my language.)

Now, I could of course go and study man-page magic until I can figure out what 
those lines mean, and then I could guess at the reason you added them, and say, 
"OK, I see what that change does, and I can guess why you wanted to do it, and 
that would be OK."

But I don't care to go and study that magic or guess why you added it.  I would 
like to read something like:

* grep.1:
  Add a man-to-html indexing header as required by the new GNU rules.

Then I could say, "OK, I don't understand the syntax so can't verify its 
correctness, but I understand why it's there and agree that's a good reason to 
add it, and I can trust you to have verified the syntax."

If I don't see it mentioned as an intentional change, then I will ask, "Did you 
mean to put this in here or did it get inserted by accident?"


The same sort of thing applies to each change.  In most cases, I can understand 
what effect the change has in a basic context (not including knowing how it 
will affect other output devices etc.) but I would still like to know what the 
INTENTION of the change was so that I can check whether the actual change 
implements the intention.  Then (or first) I want to know why it was changed at 
all, even if the reason is just "personal taste", because sometimes the reason 
is important.

For example: "Write the date in ISO-standard format for consistency with other 
GNU man pages."  Because you haven't said that, I don't know whether you've 
changed it for that reason or just personal taste (in which case it might 
differ from all other pages, which would be poor) or some other reason.

Of course, for documentation, I don't expect every little change to be spelled 
out in great precise detail; you can just write "Order of sections changed for 
clarity" without specifying exactly what the criteria for "clarity" were or 
what sections were moved.

While I remember, I must confess that in my "doc.patch" that I attached in my 
last message, there was one fairly extensive change not mentioned in the log 
entry.  That change was: reduce the inconsequential differences between the 
text in grep.1 and the text in grep.texi, by changing wording in one or both files.


> That doesn't mean there won't be one.  It's
> forthcoming, but please have a look at the
> generally reworked structure of both man and
> info documentation in the meantime, just in case
> you'd prefer to have some of the general changes
> reverted anyways.

I could and will have a look through the formatted output documents, and see if 
I notice anything.  (I can't review the man page source for structural 
differences.  There are FAR too many differences for me to see what's going on 
just by scrolling through the diff (I use a side-by-side coloured vimdiff).)


*** A bit of review

I do notice something straight away in the man page: the grouping of options by 
category.  I like this very much.  Excellent.  It may be a break from tradition 
but I think it is much more useful.

I don't see any reason to keep alphabetical order within each section.  I think 
keeping related options together would make more sense.

I think the "(... is specified by POSIX)" parts are OK - not too obtrusive.

I like the expanded explanation of GREP_COLORS with its table of sub-options.

I think all the options about input file format should be grouped together: 
that is, all the options to do with "binary" and "text" files, and "-z, 
--null-data".  They could go Under "Other Options" (where two of them already 
are), or in a new section called something like "Input Data Format".

(I haven't looked at the info yet.)


> I have made sure that every sentence ends a
> source-code line.  This way, when smaller changes [...]

Good idea.  But note that source-formatting changes don't have to wait for and 
be combined with an opportunity when widespead content layout changes are being 
made.  It would actually be easier to review if you did the source-formatting 
change as a separate patch from the content-changing patch (before or after, it 
doesn't matter which).

- Julian