Documentation for compile.el and grep.el?

Documentation for compile.el and grep.el?

[Nick Roberts]

building.texi says:

>    When the compiler process terminates, for whatever reason, the mode
> line of the `*compilation*' buffer changes to say `signal' instead of
> `run'.

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.

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:

> (compilation-first-column, compilation-error)
> (compilation-directory-matcher, compilation-page-delimiter)
> (compilation-mode-font-lock-keywords, compilation-debug)
> (compilation-error-face, compilation-warning-face)
> (compilation-info-face, compilation-line-face)
> (compilation-column-face, compilation-enter-directory-face)
> (compilation-leave-directory-face, compilation-skip-threshold)
> (compilation-skip-visited, compilation-context-lines): New vars.

> (compilation-warning-face, compilation-info-face)
> (compilation-message-face): New faces.

> (compilation-error-regexp-alist-alist): New constant.

> (compilation-face, compilation-directory-properties)
> (compilation-assq, compilation-error-properties, compilation-start)
> (define-compilation-mode, compilation-loop)
> (compilation-set-window): New functions.

which is rather opaque, to say the least.

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.

Nick

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

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sat, 26 Feb 2005 16:43:33 +1300
> 
> building.texi says:
> 
> >    When the compiler process terminates, for whatever reason, the mode
> > line of the `*compilation*' buffer changes to say `signal' instead of
> > `run'.
> 
> 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.

> 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:
> 
> > (compilation-first-column, compilation-error)
> > (compilation-directory-matcher, compilation-page-delimiter)
> > (compilation-mode-font-lock-keywords, compilation-debug)
> > (compilation-error-face, compilation-warning-face)
> > (compilation-info-face, compilation-line-face)
> > (compilation-column-face, compilation-enter-directory-face)
> > (compilation-leave-directory-face, compilation-skip-threshold)
> > (compilation-skip-visited, compilation-context-lines): New vars.
> 
> > (compilation-warning-face, compilation-info-face)
> > (compilation-message-face): New faces.
> 
> > (compilation-error-regexp-alist-alist): New constant.
> 
> > (compilation-face, compilation-directory-properties)
> > (compilation-assq, compilation-error-properties, compilation-start)
> > (define-compilation-mode, compilation-loop)
> > (compilation-set-window): New functions.
> 
> which is rather opaque, to say the least.

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.

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

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.

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

[Nick Roberts]

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

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

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sun, 27 Feb 2005 10:20:29 +1300
> Cc: emacs-devel@gnu.org
> 
>  > 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.

It's mentioned in etc/NEWS, but FOR-RELEASE should probably mention
that as well.  The difference between this issue and everything else
in FOR-RELEASE is that the latter are all temporary, and are removed
as they are resolved, while the NEWS markup with subsequent docs
update is something that is done before every release.

> In any case, shouldn't it be done *before* the Emacs manual is
> proofread, otherwise new errors will creep in.

I don't think we could do everything in sequence, some things need to
be done in parallel, even if that's sub-optimal.

> You seem to always argue for the status quo.

Is that a bad thing?

Anyway, I wasn't arguing for the status quo, just explaining it, since
I figured out you didn't know about how this is done in Emacs.

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

The way I see it, Emacs only starts being a collectively-developed
project, so many things are not formalized yet, since for many years
they used to be in the head of a single individual.

FWIW, I do agree that writing these things up is a Good Thing (how's
that for arguing for the status quo?).

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

I'm afraid submitting patches to the list isn't a mandatory practice,
either (I proposed it in the past, but was voted down).  Not that the
GDB development is an example of sticking to procedures and due
process lately, but that's another story.

> Also, while it is in CVS, I think poorly written documentation is
> better than none at all.

I agree, but again, in the past Emacs developers didn't feel like it
was a good idea to require that each change be committed with a
documentation that goes with it.

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

[Richard Stallman]

    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.

I did go through and update the Lisp manual fully.
However, that was about a year ago, after which things stalled
because I could not convince people to start checking the manual.

As a result, a few more changes have been made which to be documented.
I will try to do that soon.

Now finally Chong Yidong is doing a lot of checking.
But one person is not enough.

Instead of arguing about general policies, which it is very unlikely
we will change, would you like to check a few files of the Lisp
manual?


As for the Emacs manual, I never got around to updating that.
That work still has to be done.

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

[Nick Roberts]

 > Instead of arguing about general policies, which it is very unlikely
 > we will change, would you like to check a few files of the Lisp
 > manual?

I don't think it would very fruitful for me to check the lisp manual as I am
not an expert in these matters. However, I have provided documentation for the
changes that I have made and reported errors when I have found them. The parts
of the manual that I have read seem to be very good and maybe thats why you
could not convince people to check it.

Nick

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

[Richard Stallman]

    Given the extensive changes to compile.el and grep.el, I'm
    surprised that the documentation has changed so little.

This may not be incorrect.  The changes mostly affect aspects not
described in the manual--for instance, to get better results when the
user edits the buffer and then tries to look at some of the error
messages.