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