Hi Thien, thanks for not giving up on this. Just a couple of minor observations ...
On 04/28/2012 02:13 PM, Thien-Thi Nguyen wrote: > () [email protected] (Alfred M. Szmidt) > () Tue, 17 Jan 2012 14:44:05 -0500 > > - There's no need to describe the full purpose of the > [...] > - function definition to explain what it does. > > Why is this section removed? > > Because it mixes concepts and style (the "however, sometimes > ... batch of changes"), and because the advice on writing comments > is no longer fully applicable (to non-software files, mentioned > first in the following paragraph). Such advice is now an > "implementation detail", dependent on the kind of change to be > logged. > > + Each group of related entries should have a @dfn{title}, a > + one line description or summary of the change, and > + optionally a short paragraph to: > > I find the wording confusing here, and don't really understand > what is optional, or mandatory. > > OK. > > Making the description line (title is confusing) > > To me, "title" suggests succinctness and overall applicability, > and is itself succinct. What would you suggest instead? > "Summary" perhaps? > mandatory is bad. Many changes don't require it. > > I'm ambivalent, but only because i still use RCS, for which it > does seem overkill to require TITLE (though, i have developed a > habit of including one, anyway). > And tomorrow you might convert your RCS repository to git, in which case you'll indeed be grateful to this habit of yours ;-) Thanks, Stefano
