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

[Eli Zaretskii]

> From: Nick Roberts <address@hidden>
> Date: Sun, 27 Feb 2005 10:20:29 +1300
> Cc: address@hidden
> 
>  > 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.