Re: [patch #4610] Consolidated documentation patch

[Charles Levert]

A long essay deserves a long answer...


* On Friday 2005-11-18 at 21:48:54 +0000, Julian Foad wrote:
> Charles Levert wrote:
> >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.

Let's rather start by affirming where we most
likely have a strong connect:  dislike for cowboy
practices, and valuing individual concentration,
strong review, and good documentation (of code
and in manuals).


> One can't really review changes without the log entry.

I would argue that really strong and stringent
review is in fact only possible by initially
putting aside the log entry, or any in-line
comment.  There are no shortcuts to it:  one
must independently assess all that a change
actually does.

Documentation at the review stage can even
in fact be counter-productive:  it influences
the reviewer, it is a distraction from useful
intuitive and unique personal first reactions.

(I could make an analogy to the war-field
journalist who stays in his/her hotel lobby and
relies on his/her few more entreprising peers
to do the actual job, or to the shockingly
evident lack of any actual review or critical
thinking in at lot of what gets published in the
media today.  At least, we both seem to value
otherwise, regarding software.)

Once one is out of skeptical review mode,
documentation and trust can then become useful
shortcuts and enable faster further developments,
by avoiding repetition of something that has
already been done and concentrating on the
specific task now at hand.

The main reason to include the documentative
explanation is to put it up for review as
well to evaluate its ability to fulfill that
further-development-aid goal.  That's why it
goes in a log or in-line with the code, rather
than stay in the email messages.

Two very important principles/criterions are:
   -- not avoiding necessary efforts;
   -- early two-way communication.
I think we both believe in this, only we bring up
separate interpretations and applications of it.


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

Quite the contrary, there is definitely no such
restriction.  One is as free as can be to have
whatever first thought that comes up on it.

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

One can have the same no-problem reaction if the
intent is fully described.  The real question is:
what are the _actual_ effects and consequences,
regardless of spin/intent?

Explaining intent is better suited as a safety
net in avoiding unfortunate misunderstandings.

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

I argue that one is in fact even less influenced
and more likely to show that kind of skepticism
when not considering the log entry explanation.


(Specific answer:  Because one system can
have several installed grep implementations,
and this is one of the first question that
comes to mind about a man page, not everything
always being under package management.  As for
the indexing/makewhatis issue, I believe that
.TH and ".SH NAME" are already what's used for
this purpose, but don't know about the details.
There is no standardization of such initial
comments.)


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

Would a '\" TeX' comment bring anything more
here?  No, because the word 'TeX' is already
there, in plain view.


(Specific answer:  Attention to typographical
details, in emulation/admiration/respect of
TeX's instigator and his spelling wishes.)


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

That I can agree with.  But this is like an
answer-to-the-exercises section.  One eventually
looks at it, but not right away.  Peer review
isn't a learning exercise, but it requires the
same kind of independent first-run-at-it for
its full benefits to be reaped.


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

(Specific answer:  It doesn't, not in the sense
that there is widespread uniformization of this.
Quite the contrary, unfortunately.)

> which would be poor) or some other reason.

(Specific answer:  Because standardization is
good for such things.  ISO 8601 isn't a personal
thing or a GNU thing, it's a worldwide thing,
including equivalent directives from FIPS or
NIST for a long time in the USA, I forget which.
Exactly that good/poor taste thing, in a broader
scope.  The comment actually explains more: what
many people think is the only form of ISO 8601
dates is in fact just one specific form of them.)


> >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 was referring to the obvious main structural
changes, and you did spot them right away as
you explain below.

To reiterate:  there will be a ChangeLog entry.
Looking at my previous work, you can notice
that there always has been an invested one up
to now, and that it's been submitted for review
in all but very trivial to explain changes.
I also have acted on or answered late-submitted
after-commit reviews.


> (I use a side-by-side coloured vimdiff).

I eat my own dog food:  diffc.  As in

   cvs diff -pudT grep/src/grep.c | diffc | less -R

(Shameless plug.)



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

Good.

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

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 think the "(... is specified by POSIX)" parts are OK - not too obtrusive.

Good.


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

Good.


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

The latter sounds good.  I'll see what I can do,
keeping things synchronized in both grep.texi
and grep.1.


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

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?


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

True.  But other many projects frown on them
and promise to spend one isolated revision
pass in each release cycle just doing them...
and then never do.  Hence my calling this an
opportunity, out of experience (including merely
observational, not necessarily involved, one).