Updating manuals

Updating manuals

[Eli Zaretskii]

Having invested now 5 days in updating the ELisp manual, I'm quite
sure we should request that each code contribution be accompanied with
some meaningful documentation, even if it's not valid Texinfo.  The
amount of research that is needed to convert a short and at times
cryptic NEWS entry into a decent manual style description, and while
at that find and fix all the inaccuracies in the related doc strings,
is simply overwhelming.  The person who writes the code in the first
place is in a much better position to describe that, especially around
the time the code is written.  By contrast, fixing English and the
Texinfo markup is a rather mechanical job that takes much less effort.
Therefore not being a native English speaker should not be an excuse
for not writing documentation to go with the code.

Judging by the rather small progress I made during these 5 days (30
NEWS entries, with about 120 entries more remaining, including those
describing internationalization and multi-tty, which will require a
_really_ serious effort), I am now quite sure we are in trouble with
the prospective schedule of the pretest and release, unless much more
people will come on board to work on updating the manuals.  (I could
only invest this many hours because it's a public holiday down here,
and it's almost over.)

Re: Updating manuals

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

> Judging by the rather small progress I made during these 5 days (30
> NEWS entries, with about 120 entries more remaining, including those
> describing internationalization and multi-tty, which will require a
> _really_ serious effort), I am now quite sure we are in trouble with
> the prospective schedule of the pretest and release, unless much more
> people will come on board to work on updating the manuals.  (I could
> only invest this many hours because it's a public holiday down here,
> and it's almost over.)

Thanks for taking the time to work on this.

A couple of people have stepped forward to volunteer for various jobs.
They are handling the documentation for the new font handling and the
new display-buffer behavior.  Hopefully, more will step up to the plate.

> Having invested now 5 days in updating the ELisp manual, I'm quite
> sure we should request that each code contribution be accompanied with
> some meaningful documentation, even if it's not valid Texinfo.

Yes.  In the past, RMS spent quite a bit of time writing the
documentation himself.  In the future, we'll have to be more rigorous
about requiring documentation with code changes.

Re: Updating manuals

[Eli Zaretskii]

> From: Chong Yidong <cyd@stupidchicken.com>
> Cc: emacs-devel@gnu.org
> Date: Sat, 18 Oct 2008 22:45:13 -0400
> 
> A couple of people have stepped forward to volunteer for various jobs.

That's good news.

> They are handling the documentation for the new font handling and the
> new display-buffer behavior.

If you mean documenting display-buffer at the ELisp level, I already
did that.  Of course, if someone who knows more than I do about the
intricacies would proofread what I did and fix any mistakes I made,
that's only for the netter.

As for other parts, could you please say which NEWS ELisp entries are
handled by others?  I'd like to avoid duplicate work in what little
time I still have to work on this.

Re: Updating manuals

[Chong Yidong]

Eli Zaretskii <eliz@gnu.org> writes:

>> They are handling the documentation for the new font handling and the
>> new display-buffer behavior.
>
> If you mean documenting display-buffer at the ELisp level, I already
> did that.  Of course, if someone who knows more than I do about the
> intricacies would proofread what I did and fix any mistakes I made,
> that's only for the netter.

Martin Rudalics offered to check the documentation to the Window
chapters in both manuals.

> As for other parts, could you please say which NEWS ELisp entries are
> handled by others?  I'd like to avoid duplicate work in what little
> time I still have to work on this.

No one else has volunteered to document the other NEW ELisp entries,
yet.

Re: Updating manuals

[Richard M. Stallman]

I think it is better to insist that people provide full
descriptions for NEWS, rather than that they write text for
the manual.  If we install text in the manual from someone
who isn't good at technical writing, it will be very likely that people
fail to rewrite it, and it  will be released with bad writing and/or
errors in Texinfo usage.

Re: Updating manuals

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: emacs-devel@gnu.org
> Date: Sun, 19 Oct 2008 21:13:44 -0400
> 
> I think it is better to insist that people provide full
> descriptions for NEWS, rather than that they write text for
> the manual.

I agree, and I didn't mean to say that the text must be installed in
the manual.  It could be in NEWS, or it could be elsewhere.  The
important part is that it's a required part of any code contribution,
and that terse one-sentence notes in NEWS are not good enough.