Re: Documentation for compile.el and grep.el?

[Nick Roberts <nickrob@snap.net.nz>]

 > > In reality it seems to say `exit' when the compiler process terminates followed
 > > by the exit code in square brackets e.g [0] for normal, [1] for abnormal.
 > 
 > It could _also_ say `signal' if the subprocess was interrupted by a
 > signal.  But the text you cited is incorrect as it stands, and should
 > be fixed.

Well, if I type 'C-c C-k' which presumably sends a signal, I still get exit,
but I'll take your word for it.


 > > Given the extensive changes to compile.el and grep.el, I'm surprised that the
 > > documentation has changed so little.
 > > 
 > > For example, compilation-directory-properties does something (mouse-2: visit
 > > current directory) but I don't know what it is. The relevant ChangeLog entry
 > > says:
 > > ...
 > 
 > Some of these are mentioned in etc/NEWS, and they are not marked with
 > a "+++', which means the documentation was not yet updated to reflect
 > that change.  Someone will do that before the release.

FOR-RELEASE does not mention this. In any case, shouldn't it be done *before*
the Emacs manual is proofread, otherwise new errors will creep in.

 > > GDB developers are required to write documentation with their patches. I
 > > think that it makes little sense to check the manual in great detail if
 > > authors don't provide the relevant documentation in the first place.
 > 
 > In Emacs, we do this differently: a significant change should be
 > described in etc/NEWS when it is checked in.  Later, when the time
 > comes to release a version, one of the jobs that should be done is to
 > go through NEWS and update the documentation for every change.

You seem to always argue for the status quo. I'm not saying that Emacs should
do things like GDB but that there should be some formal procedure for recording
changes. Adding an entry to NEWS might be sufficient if someone else updates
the documentation later, but AFAIK there is no README for developers explaining
this, and it doesn't seem to always get done.

 > It is also okay to change the docs right when the changes are
 > committed to CVS, but that is not required, and might actually be
 > worse if the person who wrote the code doesn't speak English well or
 > cannot write good documentation.

In this case, hopefully the author would submit his proposed changes to the
mailing list, just as I have done in the past, when I have not felt
comfortable with what I have written. Also, while it is in CVS, I think poorly
written documentation is better than none at all.


Nick