Trunk still not open

Trunk still not open

[Stefan Monnier]

Could people try to fix up the few remaining items of NEWS where the
manual hasn't been updated yet?

The most significant one is the item regarding electric-indent-mode,
where we need to check its impact on the tutorial as well as many other
"introduction" or "generic" place where we talk about RET and LFD.

This is what's still holding up the re-opening of the trunk,


        Stefan

Re: Trunk still not open

[Glenn Morris]

Stefan Monnier wrote:

> Could people try to fix up the few remaining items of NEWS where the
> manual hasn't been updated yet?

I don't see any evidence that holding the trunk hostage is making anyone
work on documentation who normally doesn't.
The remaining NEWS items are not easy to document.
It would be better to take time and do it right rather than try to rush
them.

I think that in future there needs to be more of a culture of people at
least trying to document their own changes, around the time they make
them. The NEWS file seems to encourage people to leave it for someone
else to do, some other time.

Some people said they want more frequent releases.
Well, you can't have that unless more people start doing some of the
less-interesting work that goes along with releases.

Re: Trunk still not open

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Thu, 13 Mar 2014 16:55:35 -0400
> Cc: emacs-devel@gnu.org
> 
> I think that in future there needs to be more of a culture of people at
> least trying to document their own changes, around the time they make
> them.

Agreed.

> Some people said they want more frequent releases.
> Well, you can't have that unless more people start doing some of the
> less-interesting work that goes along with releases.

Indeed.

Re: Trunk still not open

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > > I think that in future there needs to be more of a culture of people at
 > > least trying to document their own changes, around the time they make
 > > them.
 > 
 > Agreed.
 > 
 > > Some people said they want more frequent releases.
 > > Well, you can't have that unless more people start doing some of the
 > > less-interesting work that goes along with releases.
 > 
 > Indeed.

All very true, but practically speaking this has to be decided at the
project level, and accompanied by a no-push-without-required-docs
policy.  It's quite possible that this policy once explicitly decided
will require essentially zero enforcement (part of the problem is that
there's probably much less than 100% awareness of the less-interesting
tasks), but you need to be prepared to enforce by demanding docs, and
if necessary reverting doc-less patches.

Of course there's no reason to require that *patch authors* write
docs, 3rd parties can do that just as well.

Steve

Re: Trunk still not open

[David Kastrup]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Eli Zaretskii writes:
>
>  > > I think that in future there needs to be more of a culture of people at
>  > > least trying to document their own changes, around the time they make
>  > > them.
>  > 
>  > Agreed.
>  > 
>  > > Some people said they want more frequent releases.
>  > > Well, you can't have that unless more people start doing some of the
>  > > less-interesting work that goes along with releases.
>  > 
>  > Indeed.
>
> All very true, but practically speaking this has to be decided at the
> project level, and accompanied by a no-push-without-required-docs
> policy.  It's quite possible that this policy once explicitly decided
> will require essentially zero enforcement (part of the problem is that
> there's probably much less than 100% awareness of the less-interesting
> tasks), but you need to be prepared to enforce by demanding docs, and
> if necessary reverting doc-less patches.

Well, one could push them to an "undocumented" branch.  That one gets
rebased from time to time on the trunk, so any commit from there that
has made it with documentation into the trunk will no longer be in there
after rebasing.

What could go wrong?

-- 
David Kastrup

Re: Trunk still not open

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Date: Fri, 14 Mar 2014 18:29:49 +0900
> 
> Eli Zaretskii writes:
> 
>  > > I think that in future there needs to be more of a culture of people at
>  > > least trying to document their own changes, around the time they make
>  > > them.
>  > 
>  > Agreed.
>  > 
>  > > Some people said they want more frequent releases.
>  > > Well, you can't have that unless more people start doing some of the
>  > > less-interesting work that goes along with releases.
>  > 
>  > Indeed.
> 
> All very true, but practically speaking this has to be decided at the
> project level, and accompanied by a no-push-without-required-docs
> policy.

Yes, of course.

> Of course there's no reason to require that *patch authors* write
> docs, 3rd parties can do that just as well.

Indeed, volunteers are welcome for that job.  But if no one steps
forward, demanding documentation as part of the patch submission is
the only alternative.  Some projects already do that.

Re: Trunk still not open

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Fri, 14 Mar 2014 10:35:41 +0100
> 
> Well, one could push them to an "undocumented" branch.  That one gets
> rebased from time to time on the trunk, so any commit from there that
> has made it with documentation into the trunk will no longer be in there
> after rebasing.

This could also work, but IMO this alternative is more complicated
than the other one, and also has the disadvantage that changes appear
on the trunk with delay, which some users might not like.  There's
also the danger that core developers will need to have 2 very active
branches to track rather than one.  So we should probably go there
only if the others cannot possibly work.

Re: Trunk still not open

[Bastien]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Of course there's no reason to require that *patch authors* write
> docs, 3rd parties can do that just as well.

Yes, but blocking code patches while waiting that someone else
write the related doc patches seems very impracticable.

-- 
 Bastien

Re: Trunk still not open

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Fri, 14 Mar 2014 10:35:41 +0100
>> 
>> Well, one could push them to an "undocumented" branch.  That one gets
>> rebased from time to time on the trunk, so any commit from there that
>> has made it with documentation into the trunk will no longer be in there
>> after rebasing.
>
> This could also work, but IMO this alternative is more complicated
> than the other one, and also has the disadvantage that changes appear
> on the trunk with delay, which some users might not like.

Well, that's the point.  A state that isn't an annoyance to anybody is
not likely to change.

> There's also the danger that core developers will need to have 2 very
> active branches to track rather than one.  So we should probably go
> there only if the others cannot possibly work.

This plan will lead to 2 very active branches exactly if the other
strategies do not work.  If the other strategies do work, the
"undocumented" branch will remain dormant anyway.

-- 
David Kastrup

Re: Trunk still not open

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Fri, 14 Mar 2014 11:02:53 +0100
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: David Kastrup <dak@gnu.org>
> >> Date: Fri, 14 Mar 2014 10:35:41 +0100
> >> 
> >> Well, one could push them to an "undocumented" branch.  That one gets
> >> rebased from time to time on the trunk, so any commit from there that
> >> has made it with documentation into the trunk will no longer be in there
> >> after rebasing.
> >
> > This could also work, but IMO this alternative is more complicated
> > than the other one, and also has the disadvantage that changes appear
> > on the trunk with delay, which some users might not like.
> 
> Well, that's the point.  A state that isn't an annoyance to anybody is
> not likely to change.

Annoyance might also lead to unwanted consequences, like rebellion.

Re: Trunk still not open

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Fri, 14 Mar 2014 11:02:53 +0100
>> Cc: emacs-devel@gnu.org
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: David Kastrup <dak@gnu.org>
>> >> Date: Fri, 14 Mar 2014 10:35:41 +0100
>> >> 
>> >> Well, one could push them to an "undocumented" branch.  That one gets
>> >> rebased from time to time on the trunk, so any commit from there that
>> >> has made it with documentation into the trunk will no longer be in there
>> >> after rebasing.
>> >
>> > This could also work, but IMO this alternative is more complicated
>> > than the other one, and also has the disadvantage that changes appear
>> > on the trunk with delay, which some users might not like.
>> 
>> Well, that's the point.  A state that isn't an annoyance to anybody is
>> not likely to change.
>
> Annoyance might also lead to unwanted consequences, like rebellion.

I rebel against generic platitudes.

-- 
David Kastrup

Re: Trunk still not open

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Fri, 14 Mar 2014 11:40:08 +0100
> Cc: emacs-devel@gnu.org
> 
> > Annoyance might also lead to unwanted consequences, like rebellion.
> 
> I rebel against generic platitudes.

See? told you so.

Re: Trunk still not open

[Eric S. Raymond]

Stephen J. Turnbull <stephen@xemacs.org>:
> All very true, but practically speaking this has to be decided at the
> project level, and accompanied by a no-push-without-required-docs
> policy.

+1 for a no-push without documentation policy.

I'll go further than that.  I'll assert that people who write features without
documentating them are being irresponsible and lazy and should be ashamed of
themselves.  Only when that attitude is common and there is real peer
pressure against this kind of sloppy work will good behavior be likely to
become normal.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Trunk still not open

[Dmitry Gutov]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> All very true, but practically speaking this has to be decided at the
> project level, and accompanied by a no-push-without-required-docs
> policy.

I really wish the project went with "no-push-without-tests" requirement
instead, first.

As for docs, I apologize (being one of the culprits), but as I rarely,
if ever, read the manual, one can understand how I can forget its
existence from time to time.

Re: Trunk still not open

[Stefan Monnier]

> As for docs, I apologize (being one of the culprits), but as I rarely,
> if ever, read the manual, one can understand how I can forget its
> existence from time to time.

Hmm... so maybe that's also why I'm one of the other culprits?


        Stefan

Re: Trunk still not open

[Stephen J. Turnbull]

Dmitry Gutov writes:

 > I really wish the project went with "no-push-without-tests" requirement
 > instead, first.
 > 
 > As for docs, I apologize (being one of the culprits), but as I rarely,
 > if ever, read the manual, one can understand how I can forget its
 > existence from time to time.

I'd like to tests too, but Emacs never had a serious policy about
testing.  Docs are another matter.  Requiring tests is not just about
the release cycle; it's about changing the whole process.

Anyway, they're closely related.  If you don't have docs, you don't
know what to test.  If you don't have tests, well, good luck keeping
docs and reality in synch.

Re: Trunk still not open

[Dmitry Gutov]

On 14.03.2014 16:34, Stephen J. Turnbull wrote:
> Anyway, they're closely related.  If you don't have docs, you don't
> know what to test.

If I only have docstrings, I can know what to test pretty well.

The original complaint in this thread is about lack of NEWS entries and 
out-of-date manuals.

Re: Trunk still not open

[Stephen J. Turnbull]

Bastien writes:
 > "Stephen J. Turnbull" <stephen@xemacs.org> writes:

 > > Of course there's no reason to require that *patch authors* write
 > > docs, 3rd parties can do that just as well.

 > Yes, but blocking code patches while waiting that someone else
 > write the related doc patches seems very impracticable.

Take a look around.  Lots of projects practice it with good results.

If you mean some patches will never get applied, sure.

YMMV, but I'll take the docs in the few cases where authors choose
departure.  (Actually I won't, since that would be infringement -- FDL
is incompatible with all licenses used for XEmacs content -- but
that's what I think Emacs should do.)

Re: Trunk still not open

[Eli Zaretskii]

> Date: Fri, 14 Mar 2014 16:57:42 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> Cc: emacs-devel@gnu.org
> 
> On 14.03.2014 16:34, Stephen J. Turnbull wrote:
> > Anyway, they're closely related.  If you don't have docs, you don't
> > know what to test.
> 
> If I only have docstrings, I can know what to test pretty well.

Not necessarily.  You will know how to test a function, but without
some overview docs, you will have no idea how to test a complex
feature that is built of several functions and variables, and relies
on some internals on top of that.  Also, internal functions many times
don't have doc strings -- a practice that Emacs development accepts as
valid.

As another example, testing of infrastructure and C code using just
the doc strings is an impossible task.  E.g., in what doc string will
you find what a 'display' property is supposed to do?

Re: Trunk still not open

[Stephen J. Turnbull]

Dmitry Gutov writes:
 > On 14.03.2014 16:34, Stephen J. Turnbull wrote:
 > > Anyway, they're closely related.  If you don't have docs, you don't
 > > know what to test.
 > 
 > If I only have docstrings, I can know what to test pretty well.

If you have XEmacs docstrings, in many cases, yes, but Emacs generally
doesn't put enough semantic information in docstrings to define the
corner cases where tests actually make a big difference.  You need the
manual level of detail.

 > The original complaint in this thread is about lack of NEWS entries

Agreed, that's not a problem for writing tests.  It's also probably
not all that big a deal for authors.  In many cases the first line of
the commit log for a merge will do, or you can omit it.  Sorting the
NEWS is a pretty big deal but that's not something it makes sense to
ask the patch authors to try to get right, at least not at this stage.

 > and out-of-date manuals.

This is a problem for writing correct and complete tests, though.

Re: Trunk still not open

[Glenn Morris]

Dmitry Gutov wrote:

> I really wish the project went with "no-push-without-tests" requirement
> instead, first.

That is a separate issue. I'd like it not to sidetrack this discussion.

(I previously asked for more people to write tests:

https://lists.gnu.org/archive/html/emacs-devel/2013-06/msg00995.html

Not much happened, except that a bunch of people wrote a bunch of
emails, like always, and nobody did anything. I'd like this current
discussion to actually have tangible results.)

> As for docs, I apologize (being one of the culprits), but as I rarely,
> if ever, read the manual, one can understand how I can forget its
> existence from time to time.

I hope you will change your mindset so that you view the documentation
as central to Emacs.

Re: Trunk still not open

[Glenn Morris]

Stefan Monnier wrote:

>> As for docs, I apologize (being one of the culprits), but as I rarely,
>> if ever, read the manual, one can understand how I can forget its
>> existence from time to time.
>
> Hmm... so maybe that's also why I'm one of the other culprits?

Please at least proof-read the documentation I have recently written for
smie, a subject about which I know nothing. (It is very inefficient for
me to have to document things like this.) And maybe also the tutorial
changes re electric-indent.

Re: Trunk still not open

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 1194 bytes --]

On 03/14/2014 12:31 PM, Glenn Morris wrote:
> Dmitry Gutov wrote:
> 
>> I really wish the project went with "no-push-without-tests" requirement
>> instead, first.
> 
> That is a separate issue. I'd like it not to sidetrack this discussion.
> 
> (I previously asked for more people to write tests:
> 
> https://lists.gnu.org/archive/html/emacs-devel/2013-06/msg00995.html
> 
> Not much happened, except that a bunch of people wrote a bunch of
> emails, like always, and nobody did anything. I'd like this current
> discussion to actually have tangible results.)

It's worked to some extent. I've written a bunch of tests myself, and
ISTR at least one bug being caught later when these tests failed,
although I can't dig up the email right now.

One thing that would help is making automated testing results more
prominent. It'd be nice to direct build failure messages from
emacs-buildstatus to somewhere more prominent (like bug-gnu-emacs) where
we can treat a build break or test failure like any other bug. It'll
produce a lot of noise at first, but it'd be worth it, IMHO.

Setting up Windows, DOS, OS X, etc. builds would help too, but that's
more SHTDI work.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 901 bytes --]

Re: Trunk still not open

[Stephen J. Turnbull]

Glenn Morris writes:
 > Dmitry Gutov wrote:
 > 
 > > I really wish the project went with "no-push-without-tests" requirement
 > > instead, first.
 > 
 > That is a separate issue. I'd like it not to sidetrack this discussion.
 > 
 > (I previously asked for more people to write tests:
 > 
 > https://lists.gnu.org/archive/html/emacs-devel/2013-06/msg00995.html
 > 
 > Not much happened, except that a bunch of people wrote a bunch of
 > emails, like always, and nobody did anything.

I am sure that is not true, and Daniel documents that.  What is true
is that it is not enough, and that is because the maintainership did
not have the stomach for *requiring* tests.  (And I agree with that
decision, for now.  Especially because docs come first, and
traditionally have been important to GNU and Emacs in particular.)

 >> As for docs, I apologize (being one of the culprits), but as I
 >> rarely, if ever, read the manual, one can understand how I can
 >> forget its existence from time to time.
 > 
 > I hope you will change your mindset so that you view the
 > documentation as central to Emacs.

Why hope?  If the maintainers collectively set this as a rule, I'm
sure Stefan will follow the rule conscientiously, like everybody else.

Without a rule, it's easy to make excuses for yourself.  Stefan may
not, I actually suspect he will exert himself to set an example.  But
that still means way too much code will be added without high-quality
documentation, and sometimes essentially undocumented, because
statistically only a minority will exert themselves.

I believe that the docs rule is actually pretty low-cost to Emacs
developers as shown by the tradition of high-quality documentation.
Why not give it a try, and tackle the much more costly task of
encouraging then requiring testing when a docs rule succeeds?

Re: Trunk still not open

[Dmitry Gutov]

On 15.03.2014 03:55, Stephen J. Turnbull wrote:

> I believe that the docs rule is actually pretty low-cost to Emacs
> developers as shown by the tradition of high-quality documentation.

Updating Texinfo manuals is low-cost? It's a yet another technology a 
person will have to learn to contribute, that, in all likelihood, they 
won't use anywhere else.

Re: Trunk still not open

[Dmitry Gutov]

Glenn Morris <rgm@gnu.org> writes:

> I hope you will change your mindset so that you view the documentation
> as central to Emacs.

Maybe I already do, except I limit that to the docstrings and
commentaries only. The main self-documenting feature for me, though, is
`find-function'.

Having just now updated the manual WRT to the new
`blink-matching-paren', I feel quite disgusted by having to document the
changes in triplicate.

The docstrings in the code, lispref/display.texi and emacs/programs.texi
all contain the descriptions of the relevant symbols, each using quite
different text.

Writing docs does not come easy to me in general, and editing three
seemingly arbitrarily different descriptions of the same things is a
good recipe for a headache. I have no idea how to judge the changes I
made.

Re: Trunk still not open

[Dmitry Gutov]

On 14.03.2014 17:29, Eli Zaretskii wrote:

> Not necessarily.  You will know how to test a function, but without
> some overview docs, you will have no idea how to test a complex
> feature that is built of several functions and variables, and relies
> on some internals on top of that.  Also, internal functions many times
> don't have doc strings -- a practice that Emacs development accepts as
> valid.

If I'm a "testing engineer" in a separate department from people who 
wrote the code (not the case here), then yes, I might like an overview 
document to understand the code, or write tests for it.

"No code without tests" policy assumes that someone actually can write 
the code changes, and they need to supply the tests that fail without that.

I.e. you both seem to be referring to some different kind of testing: 
non-automated, performed by third parties?

If I write automated tests, I'll have to get familiar with the code 
either way, and it's often its own best documentation.

> As another example, testing of infrastructure and C code using just
> the doc strings is an impossible task.  E.g., in what doc string will
> you find what a 'display' property is supposed to do?

Sure, some introductory/overview manual can be good, or even a detailed 
one, for C-level features.

Lisp packages often put the intro or overview in the Commentary, though.

Re: Trunk still not open

[Dmitry Gutov]

On 14.03.2014 17:39, Stephen J. Turnbull wrote:
> If you have XEmacs docstrings, in many cases, yes, but Emacs generally
> doesn't put enough semantic information in docstrings to define the
> corner cases where tests actually make a big difference.  You need the
> manual level of detail.

If the docstring doesn't describe the corner cases, they're usually not 
important for the user to know (what will they be doing in the manual, 
then?), or it's a bug in the docstring.

This is probably different for some large/core features, but on most of 
the features I've worked with, the manual rarely provides a lot of value.

Some context here and there perhaps, but nothing like describing the 
corner cases more than docstrings and comments do.

Re: Trunk still not open

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 483 bytes --]

() Dmitry Gutov <dgutov@yandex.ru>
() Sat, 15 Mar 2014 05:22:52 +0200

   I have no idea how to judge the changes I made.

One way is to imagine yourself to be a non-programmer, and then
also remember that, indeed, you once were (like us all :-D).

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Trunk still not open

[Eli Zaretskii]

> Date: Sat, 15 Mar 2014 04:09:47 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> Cc: emacs-devel@gnu.org
> 
> Updating Texinfo manuals is low-cost? It's a yet another technology a 
> person will have to learn to contribute, that, in all likelihood, they 
> won't use anywhere else.

Texinfo is almost plain text, the markup you need to learn is quite
minimal, and fairly similar semantically to HTML.  The markup is also
quite a mechanical part of writing the docs, and you will quickly
learn to do it correctly given the comments for your first
submissions.

The main part is writing the text itself, and learning to describe a
feature concisely and clearly.  That is something you will find useful
everywhere, as long as you are involved in writing and maintaining
software.  Software engineers who can write good docs are rare and
therefore quite valued.

Take a look at gdb-patches mailing list, where we have people writing
docs for every patch, and see for yourself how this works.  There are
a few of them there for whom writing English is much more difficult
than writing C or Python, and yet they still do this.

Re: Trunk still not open

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 15 Mar 2014 05:22:52 +0200
> Cc: emacs-devel@gnu.org
> 
> Having just now updated the manual WRT to the new
> `blink-matching-paren', I feel quite disgusted by having to document the
> changes in triplicate.
> 
> The docstrings in the code, lispref/display.texi and emacs/programs.texi
> all contain the descriptions of the relevant symbols, each using quite
> different text.
> 
> Writing docs does not come easy to me in general, and editing three
> seemingly arbitrarily different descriptions of the same things is a
> good recipe for a headache. I have no idea how to judge the changes I
> made.

The doc strings and the manuals take different views on the same
features.  The doc strings document only the symbol they pertain to,
with minimal links to others.  By contrast, the manuals should always
describe the features in the context of a larger theme that is the
subject of the containing section of the manual.  This means, in
particular, that the manual text should:

  . contrast each feature with other features and discuss its
    advantages and disadvantages, as in "unlike FOO, this function..."

  . include cross-references to related material and places where
    terminology you use is defined and described

  . provide examples where necessary to clarify the usage of a
    feature, especially when its formal description might not be clear
    enough

  . in general be less concise and more explanatory, since the size of
    the text is less important than in a doc string (it doesn't affect
    the memory footprint of the Emacs process)

  . for the ELisp manual, provide the information that Lisp
    programmers need to use the feature best, such as considerations
    when to use and when not to use it

It is quite rare to have a feature whose documentation in the manual
is simply a repetition of its doc string.

Re: Trunk still not open

[David Kastrup]

Thien-Thi Nguyen <ttn@gnu.org> writes:

> () Dmitry Gutov <dgutov@yandex.ru>
> () Sat, 15 Mar 2014 05:22:52 +0200
>
>    I have no idea how to judge the changes I made.
>
> One way is to imagine yourself to be a non-programmer, and then
> also remember that, indeed, you once were (like us all :-D).

Feels a bit like "try to think in the manner you did before you had the
capacity of speech".  Some things are hard to unimpress from one's mind.

-- 
David Kastrup

Re: Trunk still not open

[Eli Zaretskii]

> Date: Sat, 15 Mar 2014 08:22:39 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: stephen@xemacs.org, emacs-devel@gnu.org
> 
> On 14.03.2014 17:29, Eli Zaretskii wrote:
> 
> > Not necessarily.  You will know how to test a function, but without
> > some overview docs, you will have no idea how to test a complex
> > feature that is built of several functions and variables, and relies
> > on some internals on top of that.  Also, internal functions many times
> > don't have doc strings -- a practice that Emacs development accepts as
> > valid.
> 
> If I'm a "testing engineer" in a separate department from people who 
> wrote the code (not the case here), then yes, I might like an overview 
> document to understand the code, or write tests for it.
> 
> "No code without tests" policy assumes that someone actually can write 
> the code changes, and they need to supply the tests that fail without that.
> 
> I.e. you both seem to be referring to some different kind of testing: 
> non-automated, performed by third parties?

At least I didn't, and I'm quite sure Stephen didn't, either.

Here's what I had in mind: It is quite rare in Emacs nowadays to write
code to implement a new feature entirely from scratch.  Usually, you
either enhance an existing feature or fix a bug in an existing
feature.  IOW, you are adding code on top of existing implementation.
Therefore, writing a good test requires you to know what the existing
code should do, because a good test will test both that you fixed
whatever problem you wanted to fix, and that you didn't break the
existing code where you didn't mean to modify existing behavior.

Therefore, you need to know what was expected of the code which you
modified.  This is exacerbated in Emacs by the lack of good coverage
by existing tests, so in many cases you will be writing a test for
modified implementation without having a test for the existing
implementation.  In those cases, your _only_ source to learn what the
existing implementation tried to do will be the docs.

> If I write automated tests, I'll have to get familiar with the code 
> either way, and it's often its own best documentation.

It's not always possible to get familiar with the code enough to
understand how it was supposed to work and what effects it was
supposed to produce, without investing unduly large or even
impractical effort.  Many times, you fix a bug or add a feature whose
effects are localized enough to make it unnecessary to study too much
surrounding or supporting code.  Sometimes, the code you modify use
some infrastructure which you understand only vaguely, but writing a
test for your changes requires to know some specific detail about
those other parts.  Etc. etc. -- I'm sure that if you dig deep enough
into your own experience, you will recall such incidents.  They all
require one to read the docs and try gleaning from there what the code
in question was supposed to do.

As another data point, consider the bug reports which say "the docs
says FOO should work such-and-such, but in fact I see a different
behavior".  IOW, people use the docs as a kind of contract, and
rightfully so.  Documenting the behavior goes a long way towards
explaining users what they should expect.

> Lisp packages often put the intro or overview in the Commentary, though.

Yes, but it's rare to have there enough stuff to cover the ground.
And if that overview is good enough, copying it into the manual and
adding the necessary markup is almost trivial.

Re: Trunk still not open

[Jambunathan K]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> +1 for a no-push without documentation policy.

Any policy should cater to the lowest commond denominator.  A lowest
common denominator would be

1. No release without documentation.
2. The original developer writes the documentation.

Trying to "synchornize" documentation and code is a stringent
requirement either in terms of the developer's preferred disposition or
the specific task at hand.

----------------------------------------------------------------

It is prudent to delay the documentation

1. When some code or feature churn is expected.  One the developer of
   the code intimately what compromises he has made for a particularl
   commit.

2. To put oneself in the right set of mood or context to surgically
   approach the task at hand.

   Speaking from my own experience, the info documentation comes out
   best when I have sufficiently distanced away from the feature in
   first place (to the point of even forgetting about it).

3. To make good of what one already has in the plate in terms of showing
   it to others, encouraging others to comment on it or to test the
   changes against real-life.

4. To "spread" the effort over a period of time.

One cannot overlook (4) particularly when volunteer effort is involved.

Re: Trunk still not open

[Jambunathan K]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Updating Texinfo manuals is low-cost? It's a yet another technology a
> person will have to learn to contribute, that, in all likelihood, they
> won't use anywhere else.

There is a very high "startup cost" to writing TexInfo documentation.
"Startup cost" come when you are giving birth to a manual or introducing
a big chapter in an existing manual.

What one can do is, write out the documentation in Org and use the
Org->TexInfo exporter to create the initial draft.  Just enable texinfo
in the `org-export-backends' and export the usual way.

ps: I find the texinfo markup verbose-y and the `@'-s irritating.
Honestly speaking, what gets in the way is one's own dislike and
reluctance.

Re: Trunk still not open

[David Kastrup]

Jambunathan K <kjambunathan@gmail.com> writes:

> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>> Updating Texinfo manuals is low-cost? It's a yet another technology a
>> person will have to learn to contribute, that, in all likelihood, they
>> won't use anywhere else.
>
> There is a very high "startup cost" to writing TexInfo documentation.
> "Startup cost" come when you are giving birth to a manual or introducing
> a big chapter in an existing manual.
>
> What one can do is, write out the documentation in Org and use the
> Org->TexInfo exporter to create the initial draft.  Just enable texinfo
> in the `org-export-backends' and export the usual way.
>
> ps: I find the texinfo markup verbose-y and the `@'-s irritating.
> Honestly speaking, what gets in the way is one's own dislike and
> reluctance.

But it's just like Scribe?

-- 
David Kastrup

Re: Trunk still not open

[Juanma Barranquero]

On Sat, Mar 15, 2014 at 9:22 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> Software engineers who can write good docs are rare and
> therefore quite valued.

That's why I'm unimpressed by the idea of forcing changes to include
docs. Not everyone is able to write Emacs-manual-quality docs, and
specially, not everyone is so fluent in English to write good English
docs; some of us struggle with it.

Re: Trunk still not open

[Jambunathan K]

David Kastrup <dak@gnu.org> writes:

>> What one can do is, write out the documentation in Org and use the
>> Org->TexInfo exporter to create the initial draft.  Just enable texinfo
>> in the `org-export-backends' and export the usual way.

> But it's just like Scribe?

Only when one starts using Org->TexInfo will one know how good or
complete a job it does.  My intention was to throw a fancy word like
"ox-texinfo.el" and encourage people to try it out and report bugs.
That is all.

    (info "(org) Other built-in back-ends")

Btw, you seem to be referring to

    http://en.wikipedia.org/wiki/Texinfo#History_and_status
    http://en.wikipedia.org/wiki/Scribe_%28markup_language%29

| Scribe is a markup language and word processing system which pioneered
| the use of descriptive markup.[1][2] Scribe was revolutionary when it
| was proposed, because it involved for the first time a clean
| separation of presentation and content.[3][4]

Looks it has a "chequered" history.

Re: Trunk still not open

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Date: Sat, 15 Mar 2014 15:32:44 +0530
> Cc: "Stephen J. Turnbull" <stephen@xemacs.org>, emacs-devel@gnu.org
> 
> ps: I find the texinfo markup verbose-y and the `@'-s irritating.

The Texinfo mode in Emacs makes the @ thingy non-issue, almost.

Re: Trunk still not open

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Sat, 15 Mar 2014 11:52:44 +0100
> Cc: Dmitry Gutov <dgutov@yandex.ru>, Stephen Turnbull <stephen@xemacs.org>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> On Sat, Mar 15, 2014 at 9:22 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > Software engineers who can write good docs are rare and
> > therefore quite valued.
> 
> That's why I'm unimpressed by the idea of forcing changes to include
> docs. Not everyone is able to write Emacs-manual-quality docs, and
> specially, not everyone is so fluent in English to write good English
> docs; some of us struggle with it.

I understand that, believe me.  I mentioned gdb-patches; you can see
there that most of the burden of helping those whose English is much
worse than yours is on yours truly's shoulders.  So I know something
about that, having done that for several years now, and after all that
I still think this is our best alternative to having manuals that are
in sync with the sources at any given time.  In particular, once a GDB
release is decided on, the release-blocking issues never include the
docs, and in general a release tarball is out the door in no time,
something we can only envy in Emacs.

Of course, if this is decided, we will have to provide the same kind
of help you see on gdb-patches for those whose initial attempts at
providing documentation will need that.

Re: Trunk still not open

[Juanma Barranquero]

On Sat, Mar 15, 2014 at 12:18 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> So I know something
> about that, having done that for several years now

I know, you've helped me too with Emacs docs a few times.

>, and after all that
> I still think this is our best alternative to having manuals that are
> in sync with the sources at any given time.

I guess I'm OK with having stricter policies for commits, but then I'd
like to have stricter policies not just for docs. Also testing, when
it makes sense (which is hard for GUI oriented fixes, I know), forcing
people to push unrelated changes in different commits (applying common
sense as necessary, of course), reminding people again to have a
complete, informative first-line summary in commits, etc.

Yes, most of these things are not release blockers. That shouldn't
stop us from trying to enforce them, to a point.

> Of course, if this is decided, we will have to provide the same kind
> of help you see on gdb-patches for those whose initial attempts at
> providing documentation will need that.

I don't doubt that will be the case.

Re: Trunk still not open

[Dmitry Gutov]

On 15.03.2014 11:02, Eli Zaretskii wrote:

> Therefore, you need to know what was expected of the code which you
> modified.  This is exacerbated in Emacs by the lack of good coverage
> by existing tests, so in many cases you will be writing a test for
> modified implementation without having a test for the existing
> implementation.  In those cases, your _only_ source to learn what the
> existing implementation tried to do will be the docs.

IME either the docstrings are sufficient, or you have to dig into the 
code anyway, see the implementation, and often use `vc-annotate', for 
older code, to find out why things were done one way or another at some 
point of time. Bug references also help.

Manuals usually don't contain historical data, or references to bugs.

> It's not always possible to get familiar with the code enough to
> understand how it was supposed to work and what effects it was
> supposed to produce, without investing unduly large or even
> impractical effort.  Many times, you fix a bug or add a feature whose
> effects are localized enough to make it unnecessary to study too much
> surrounding or supporting code.

Then just skimmings the surrounding code or its docstrings might be enough.

> Sometimes, the code you modify use
> some infrastructure which you understand only vaguely, but writing a
> test for your changes requires to know some specific detail about
> those other parts.

If it's not in the docstrings, I'll probably have to read the code anyway.

> As another data point, consider the bug reports which say "the docs
> says FOO should work such-and-such, but in fact I see a different
> behavior".  IOW, people use the docs as a kind of contract, and
> rightfully so.  Documenting the behavior goes a long way towards
> explaining users what they should expect.

This can be applied to docstrings just as well.

>> Lisp packages often put the intro or overview in the Commentary, though.
>
> Yes, but it's rare to have there enough stuff to cover the ground.
> And if that overview is good enough, copying it into the manual and
> adding the necessary markup is almost trivial.

And then you'll have to maintain the text in both places.

Re: Trunk still not open

[Dmitry Gutov]

On 15.03.2014 10:45, Eli Zaretskii wrote:

> The doc strings and the manuals take different views on the same
> features.  The doc strings document only the symbol they pertain to,
> with minimal links to others.  By contrast, the manuals should always
> describe the features in the context of a larger theme that is the
> subject of the containing section of the manual.  This means, in
> particular, that the manual text should: ...

Thanks, that's a good list, and it explain well why one may want to 
document core functionality and concepts in a manual.

I'm not so sure about plain variables and functions.

> It is quite rare to have a feature whose documentation in the manual
> is simply a repetition of its doc string.

If it's not radically different, I'd still question the separation. 
Maybe that's often a cause the improve the docstring, rather than 
rewrite the same information in different ways?

I see that no one has commented on "documenting the changes in triplicate".

Re: Trunk still not open

[Dmitry Gutov]

On 15.03.2014 10:22, Eli Zaretskii wrote:

> Texinfo is almost plain text, the markup you need to learn is quite
> minimal, and fairly similar semantically to HTML.  The markup is also
> quite a mechanical part of writing the docs, and you will quickly
> learn to do it correctly given the comments for your first
> submissions.

It can be easy to change some small part of an existing page. Writing a 
new one would be a bit harder. I think it would cut down on casual 
contributions either way.

> Take a look at gdb-patches mailing list, where we have people writing
> docs for every patch, and see for yourself how this works.  There are
> a few of them there for whom writing English is much more difficult
> than writing C or Python, and yet they still do this.

As a program written in C, GDB doesn't have the same concept of 
docstrings visible to the user. So the manual is necessary, and if the 
author of a patch doesn't do it, AFAICT in many cases that won't be 
practical to do post-factum.

At least they don't have to duplicate the text.

Re: Trunk still not open

[Glenn Morris]

Daniel Colascione wrote:

> One thing that would help is making automated testing results more
> prominent. It'd be nice to direct build failure messages from
> emacs-buildstatus to somewhere more prominent (like bug-gnu-emacs) where
> we can treat a build break or test failure like any other bug. It'll
> produce a lot of noise at first, but it'd be worth it, IMHO.

I disagree with that. I think it's better to keep them on a separate
list. E.g., the failures are often due to hydra glitches.

Re: Trunk still not open

[Glenn Morris]

Juanma Barranquero wrote:

> On Sat, Mar 15, 2014 at 9:22 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> Software engineers who can write good docs are rare and
>> therefore quite valued.
>
> That's why I'm unimpressed by the idea of forcing changes to include
> docs. Not everyone is able to write Emacs-manual-quality docs, and
> specially, not everyone is so fluent in English to write good English
> docs; some of us struggle with it.

You can't force people to do anything, and that's not what I asked.

I just want people to try more, rather than relying on someone else to
do it.

If your English is not the best, then do the best job that you can, and
ask people to proof-read the result. This is much better than doing
nothing at all. (If you were talking about yourself, I think your
English is totally up to the task of writing Emacs docs.)

To get specific: please try and document frameset.el in the lispref.

Re: Trunk still not open

[Glenn Morris]

Dmitry Gutov wrote:

> I see that no one has commented on "documenting the changes in triplicate".

The Emacs manual and the lispref should not duplicate each other (in
non-trivial ways). The manual describes the user-level interface, and
the lispref the programmer-level interface (the distinction between the
two can be a bit grey of course), and they should cross-reference each
other where relevant.

In this specific case, I think you found an example where the lispref
repeats too much information from the manual. The manual should document
what blink-matching-paren does, and how to turn it off, and what (main)
customization options exists. The lispref should contain the stuff about
blink-paren-function and blink-matching-open. The descriptions of
blink-matching-paren, blink-matching-paren-distance,
blink-matching-delay should probably be removed from the lispref in
favour of a cross-reference to the Emacs manual.

Re: Trunk still not open

[Juanma Barranquero]

On Sun, Mar 16, 2014 at 2:08 AM, Glenn Morris <rgm@gnu.org> wrote:

> You can't force people to do anything, and that's not what I asked.

True, though that kind of sentiment has at least been thrown around.
Quoting Stephen:

> All very true, but practically speaking this has to be decided at the
> project level, and accompanied by a no-push-without-required-docs
> policy.  It's quite possible that this policy once explicitly decided
> will require essentially zero enforcement (part of the problem is that
> there's probably much less than 100% awareness of the less-interesting
> tasks), but you need to be prepared to enforce by demanding docs, and
> if necessary reverting doc-less patches.

and that motivated my answer.

> I just want people to try more, rather than relying on someone else to
> do it.

"Relying on someone else to do it" can also be interpreted as "leaving
that particular work for those that are more skilled at it".

> If your English is not the best, then do the best job that you can, and
> ask people to proof-read the result. This is much better than doing
> nothing at all.

Hmm. I'm not so sure, because I don't agree with the "doing nothing at
all". I mean, surely there are some metrics in which it is "much
better", but these metrics are not necessarily related to efficiency,
but peers' goodwill (or project satisfaction, if you will), etc. If
developer A requires X hours to document something, and developers B,
C or D could do it in a tenth of that time, it is really efficient for
A to do it, assuming that in general A will spend these X hours in
another Emacs-related task anyway? Of course, A has no right to demand
B or anyone else to do it in their place; that's a given. But at the
end of the day, isn't contributing to a project like this a matter of
knowing how to spend your time in productive ways? I suppose a
counterargument could be given against developers who only want to do
"shiny new" things and leave the grunt work to others, but I do
believe that's not the case in the emacs devel community: most of us
do our share of grunt work (squashing bugs, fixing typos, testing,
revising and commenting proposed patches, commiting code from
non-committers, building snapshots, etc.).

> (If you were talking about yourself, I think your
> English is totally up to the task of writing Emacs docs.)

Well, I'm not just talking about myself. But thanks.

> To get specific: please try and document frameset.el in the lispref.

I didn't even know that it had to be documented in the lisp reference.
There are pretty fundamental libraries, like uniquify, which are not
(uniquify is briefly described in the Emacs manual). I will be very
surprised if the non-doc status of framesets has kept the freeze from
unfreezing ;-)

But assuming I try, where would that go? A subnode of "Frames", perhaps?

Re: Trunk still not open

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 637 bytes --]

On 03/15/2014 06:00 PM, Glenn Morris wrote:
> Daniel Colascione wrote:
> 
>> One thing that would help is making automated testing results more
>> prominent. It'd be nice to direct build failure messages from
>> emacs-buildstatus to somewhere more prominent (like bug-gnu-emacs) where
>> we can treat a build break or test failure like any other bug. It'll
>> produce a lot of noise at first, but it'd be worth it, IMHO.
> 
> I disagree with that. I think it's better to keep them on a separate
> list. E.g., the failures are often due to hydra glitches.

Aren't these Hydra glitches themselves bugs that should be fixed?


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 901 bytes --]

Re: Trunk still not open

[Eli Zaretskii]

> Date: Sun, 16 Mar 2014 02:26:21 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: stephen@xemacs.org, emacs-devel@gnu.org
> 
> If it's not in the docstrings, I'll probably have to read the code anyway.

For complicated features, this won't be enough.  Recall my 'display'
property example again.

Re: Trunk still not open

[Eli Zaretskii]

> Date: Sun, 16 Mar 2014 02:39:54 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: stephen@xemacs.org, rgm@gnu.org, emacs-devel@gnu.org
> 
> > Take a look at gdb-patches mailing list, where we have people writing
> > docs for every patch, and see for yourself how this works.  There are
> > a few of them there for whom writing English is much more difficult
> > than writing C or Python, and yet they still do this.
> 
> As a program written in C, GDB doesn't have the same concept of 
> docstrings visible to the user.

That's not true.  Here's a random example of a GDB command definition:

    c = add_cmd ("directory", class_files, directory_command, _("\
  Add directory DIR to beginning of search path for source files.\n\
  Forget cached info on source file locations and line positions.\n\
  DIR can also be $cwd for the current working directory, or $cdir for the\n\
  directory in which the source file was compiled into object code.\n\
  With no argument, reset the search path to $cdir:$cwd, the default."),
		 &cmdlist);

What is that if not a doc string?

Re: Trunk still not open

[Jambunathan K]

To the below list, I would also add this (just for emphasis).  Eli, I am
not saying it is an oversight on your part.  So don't pounce on me :-)

    1. Document the design decisions
    
    2. Provide some historical context or add a personal note
    
    3. Consolidate (as in "bring together") various aspects of the
       feature "scattered" across multiple files or symbols in a single
       node and provide a cohesive narrative.

The nodes on overlay, text properties, extents is a good example of (1).
If I want to learn about text properties or overlays, I can progress
quickly by starting with reference manual than by starting with
underlying C files.

(2) is very very important for software like Emacs whose life-term is
measured in decades and not in years.  I saw a recent commit where the
documentation used the word "now" in questionable manner.  (I cannot
locate the commit right now) Use of such words is highly questionable
and shows a lack of appreciation of historical context.

In summary, I would say the "foreword" or "preamble" part of a Info
chapter is "equally" the most important part and can be exploited by the
author - both to give his creativity an expression and stimulate an
explorer by having his curiosity sufficiently aroused.


Eli Zaretskii <eliz@gnu.org> writes:

> The doc strings and the manuals take different views on the same
> features.  The doc strings document only the symbol they pertain to,
> with minimal links to others.  By contrast, the manuals should always
> describe the features in the context of a larger theme that is the
> subject of the containing section of the manual.  This means, in
> particular, that the manual text should:
>
>   . contrast each feature with other features and discuss its
>     advantages and disadvantages, as in "unlike FOO, this function..."
>
>   . include cross-references to related material and places where
>     terminology you use is defined and described
>
>   . provide examples where necessary to clarify the usage of a
>     feature, especially when its formal description might not be clear
>     enough
>
>   . in general be less concise and more explanatory, since the size of
>     the text is less important than in a doc string (it doesn't affect
>     the memory footprint of the Emacs process)
>
>   . for the ELisp manual, provide the information that Lisp
>     programmers need to use the feature best, such as considerations
>     when to use and when not to use it

Re: Trunk still not open

[Dmitry Gutov]

Eli Zaretskii <eliz@gnu.org> writes:

> That's not true.  Here's a random example of a GDB command definition:

...

> What is that if not a doc string?

Are there a lot of them? I'd expect the ratio of docstrings/manual
volume in GCC to be much lower than in Emacs.

Re: Trunk still not open

[Dmitry Gutov]

On 16.03.2014 03:27, Glenn Morris wrote:

> In this specific case, I think you found an example where the lispref
> repeats too much information from the manual.

I'm glad to know that this isn't how things should be. At least that 
reduces the duplication to no more than the factor of 2.

> The manual should document
> what blink-matching-paren does, and how to turn it off, and what (main)
> customization options exists. The lispref should contain the stuff about
> blink-paren-function and blink-matching-open. The descriptions of
> blink-matching-paren, blink-matching-paren-distance,
> blink-matching-delay should probably be removed from the lispref in
> favour of a cross-reference to the Emacs manual.

Could you make that change?

Re: Trunk still not open

[martin rudalics]

 > I didn't even know that it had to be documented in the lisp reference.

It is very much needed.

 > There are pretty fundamental libraries, like uniquify, which are not
 > (uniquify is briefly described in the Emacs manual). I will be very
 > surprised if the non-doc status of framesets has kept the freeze from
 > unfreezing ;-)

Maybe it didn't.  But it should have done so ;-)

And yes - uniquify should have some documentation as well.

 > But assuming I try, where would that go? A subnode of "Frames", perhaps?

Yes.  It should go into "Frame Configurations".  Maybe we can also find
a better title for that section then and apply something similar for
"Window Configurations" (which includes "window states" as a subset).

martin

Re: Trunk still not open

[Nicolas Richard]

Dmitry Gutov <dgutov@yandex.ru> writes:
> Thanks, that's a good list, and it explain well why one may want to
> document core functionality and concepts in a manual.
>
> I'm not so sure about plain variables and functions.

Maybe not a full documentation for each of them, which indeeds sometimes
duplicates (usually partially) the docstring, but at least a list of
those. At least that's how I can get an overview of what is part of a
given feature :
e.g. if I want to use hash tables, I look into the manual and see what
functions I have for hash tables. I don't have to browse through an M-x
apropos output or similar, in which there are many non-relevant results.

It's one of the things that is very useful to me, so thanks for keeping
the manuals up to date !

-- 
Nico.

Re: Trunk still not open

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Cc: stephen@xemacs.org,  emacs-devel@gnu.org
> Date: Sun, 16 Mar 2014 07:25:12 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > That's not true.  Here's a random example of a GDB command definition:
> 
> ...
> 
> > What is that if not a doc string?
> 
> Are there a lot of them? I'd expect the ratio of docstrings/manual
> volume in GCC to be much lower than in Emacs.

(It's GDB, not GCC.)  Not sure why would you expect that, but here are
the numbers:

There are 2500 commands in "emacs -Q" and 2600 variables.  The Emacs
user manual weighs in at 49000 lines, and describes more than just
"emacs -Q", but does not describe all of the commands and variables.

There are about 1100 commands and options in GDB.  The GDB manual is
also about 49000 lines, but only 30000 of these describe interactive
commands and options (the rest is about GDB/MI, the remote protocol,
and other non-interactive issues).

So the ratio sounds very similar to me.

Re: Trunk still not open

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Cc: Dmitry Gutov <dgutov@yandex.ru>,  emacs-devel@gnu.org
> Date: Sun, 16 Mar 2014 09:27:08 +0530
> 
> 
> To the below list, I would also add this (just for emphasis).  Eli, I am
> not saying it is an oversight on your part.  So don't pounce on me :-)

It's not an oversight, because I didn't intend to provide a checklist
of how to document a feature, only how a description suitable for a
manual _differs_ from a doc string.

>     1. Document the design decisions

Definitely not!  Users are not interested in design decisions, they
are interested in how things should work as designed.  Sometimes,
describing the latter will hint (or more than hint) on the former, but
it's definitely not an end in itself.

>     2. Provide some historical context or add a personal note

Not needed, IMO, and will generally bloat the documentation for no
good reason.

>     3. Consolidate (as in "bring together") various aspects of the
>        feature "scattered" across multiple files or symbols in a single
>        node and provide a cohesive narrative.

Yes, a feature should be generally described in one place, and then
cross-references to that place put in related sections.

> The nodes on overlay, text properties, extents is a good example of (1).

That's the odd one out, and the reason is lost in history that only
old men such as myself remember.

Re: Trunk still not open

[Dmitry Gutov]

On 16.03.2014 18:10, Eli Zaretskii wrote:

> (It's GDB, not GCC.)  Not sure why would you expect that, but here are
> the numbers:

Sorry, selective blindness. I'd expect that of GCC, at least.

I've also looked at one of the recent patches:

https://www.sourceware.org/ml/gdb-patches/2014-03/msg00331.html

It contains a relatively large chunk of updates for both NEWS and the 
manual, a couple of comments definitely not intended for the user, and 
~4 lines of documentation for a user command.

> So the ratio sounds very similar to me.

Hm yes, seems like it.

Re: Trunk still not open

[Eli Zaretskii]

> Date: Sun, 16 Mar 2014 18:36:47 +0200
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: stephen@xemacs.org, emacs-devel@gnu.org
> 
> I've also looked at one of the recent patches:
> 
> https://www.sourceware.org/ml/gdb-patches/2014-03/msg00331.html
> 
> It contains a relatively large chunk of updates for both NEWS and the 
> manual, a couple of comments definitely not intended for the user, and 
> ~4 lines of documentation for a user command.

That patch is relatively unusual, since it is about introducing a new
user option.  So it includes an unusually large proportion of
documentation changes and relatively small code changes.  Normally,
the ratio of code to documentation is much larger.

Re: Trunk still not open

[Jambunathan K]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jambunathan K <kjambunathan@gmail.com>
>> Cc: Dmitry Gutov <dgutov@yandex.ru>,  emacs-devel@gnu.org
>> Date: Sun, 16 Mar 2014 09:27:08 +0530
>> 
>> 
>>     1. Document the design decisions
>
> Definitely not!  Users are not interested in design decisions

Will you say the same for Emacs Lisp manual as well.

>> The nodes on overlay, text properties, extents is a good example of (1).
>
> That's the odd one out, and the reason is lost in history that only
> old men such as myself remember.

The thing is: We have a precedent (which I found useful).

Re: Trunk still not open

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Cc: emacs-devel@gnu.org,  dgutov@yandex.ru
> Date: Mon, 17 Mar 2014 00:47:50 +0530
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Jambunathan K <kjambunathan@gmail.com>
> >> Cc: Dmitry Gutov <dgutov@yandex.ru>,  emacs-devel@gnu.org
> >> Date: Sun, 16 Mar 2014 09:27:08 +0530
> >> 
> >> 
> >>     1. Document the design decisions
> >
> > Definitely not!  Users are not interested in design decisions
> 
> Will you say the same for Emacs Lisp manual as well.

Yes.  Its readers want to know how to write their program, not how
Emacs was designed and why.  The latter is (or should be) subject for
a separate document, as yet unwritten (AFAIK).

Re: Trunk still not open

[Stephen J. Turnbull]

Dmitry Gutov writes:
 > On 14.03.2014 17:39, Stephen J. Turnbull wrote:
 > > If you have XEmacs docstrings, in many cases, yes, but Emacs generally
 > > doesn't put enough semantic information in docstrings to define the
 > > corner cases where tests actually make a big difference.  You need the
 > > manual level of detail.
 > 
 > If the docstring doesn't describe the corner cases, they're usually not 
 > important for the user to know

True.

 > (what will they be doing in the manual, then?),

Providing documentation for the unusual user or unusual use case --
including the folks who write tests.

 > or it's a bug in the docstring.

In XEmacs you'd quite possibly be right, but AIUI, no, not in Emacs.
In Emacs docstrings are to explain the basic function plus the syntax
of different arguments.  Detailed explanation of semantics is left to
the manual.  To take an absolutely obvious case (where even XEmacs
would refuse a patch to provide completely detailed semantics of a
function), consider "looking-at".  The REGEXP argument is described
(surprisingly enough) as a regular expression.  The Emacs dialect of
regular expression, however, is not explained in detail (and this is
true in *all* regexp-accepting functions).

But in the manual it should be explained, and tests should make sure
that all syntax in the manual is accepted and functions properly.

 > This is probably different for some large/core features, but on
 > most of the features I've worked with, the manual rarely provides a
 > lot of value.

That's a shame.

Re: Trunk still not open

[Stephen J. Turnbull]

Juanma Barranquero writes:

 > That's why I'm unimpressed by the idea of forcing changes to include
 > docs. Not everyone is able to write Emacs-manual-quality docs, and

Many projects have proved that to be false.  I can cite Python; Eli
has cited gdb.  It very rare that a person who can code is incapable
of writing docs to an acceptable level of quality.  It is of course
common that they have had little practice at it.  So give them some
practice, review their work, and teach them. :-)

 > specially, not everyone is so fluent in English to write good
 > English docs; some of us struggle with it.

This is certainly true, and those same projects show how to deal with
it: if the docs are obviously missing content, reject the patch and
iterate; if the docs are uninterpretable, ask questions to help the
contributor revise; if the docs are interpretable having reviewed the
code part of the patch, fix them and apply.

Re: Trunk still not open

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > Yes.  Its readers want to know how to write their program, not how
 > Emacs was designed and why.  The latter is (or should be) subject for
 > a separate document, as yet unwritten (AFAIK).

To the extent that you want lower-level details from the horse's
mouth, somebody will probably have to interview Richard (general
Emacs), Gerd (redisplay), and Ken'ichi (MULE), among others (those are
the areas where I know a particular person did a lot of design by
themselves, but I don't have comprehensive knowledge of Emacs) but
Richard's paper

http://www.gnu.org/software/emacs/emacs-paper.html

is a pretty good start on the "whys" and many of the higher-level
"hows" of Emacs design.  Also

http://www.xemacs.org/Documentation/21.5/html/internals.html

is in great part relevant, with many lower-level details that are
applicable to Emacs as well.  It is quite incomplete and there are
piles of junk that are basically old block comments mover there from
the source, but I still find it useful when I read Emacs C code.

Re: Trunk still not open

[Juanma Barranquero]

On Mon, Mar 17, 2014 at 5:43 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:

> It very rare that a person who can code is incapable
> of writing docs to an acceptable level of quality.  It is of course
> common that they have had little practice at it.

I've been a tech writer, and editor, for the Spanish edition of PC
World (back when paper magazines still mattered); I've written
features for tech magazines, and ghost written some for the leading
Spanish technews blog; many years ago I worked for a small VoIP telco
(before Skype, though they are still active) where there was a mandate
to document everything in English; I've also written book reviews,
non-tech features, and even once a cooking recipe; additionally, I've
translated lots of technical texts (including OS-400 docs for IBM) and
non-tech too (I translated "Snow Crash" to Spanish, a fact I'm pretty
proud of).

I'm not bragging; I'm pointing out that I can put words together well
enough to be professionally published. And yet, I *suck* at it, I'm
extremely slow and inefficient doing that work, because of the simple
fact that I *HATE* writing. I consider my teeth being pulled out
without painkillers an acceptable, even alluring, procrastinating
alternative to writing. Practice has nothing to do with it. I have
practice.

Re: Trunk still not open

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 17 Mar 2014 13:38:59 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, Emacs developers <emacs-devel@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>
> 
> On Mon, Mar 17, 2014 at 5:43 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
> 
> I'm not bragging; I'm pointing out that I can put words together well
> enough to be professionally published. And yet, I *suck* at it, I'm
> extremely slow and inefficient doing that work, because of the simple
> fact that I *HATE* writing. I consider my teeth being pulled out
> without painkillers an acceptable, even alluring, procrastinating
> alternative to writing. Practice has nothing to do with it. I have
> practice.

I'm sure when taken in small portions, this isn't so bad.

Re: Trunk still not open

[Stefan]

> I believe that the docs rule is actually pretty low-cost to Emacs
> developers as shown by the tradition of high-quality documentation.

FWIW, while I suck both at writing documentation and at forcing myself
to write documentation, I'm in favor of being more strict
w.r.t documentation.  But in many cases, code is installed in
a non-definitive way, so it's convenient to install the code first, then
fix up some of it based on user's feedback and only later write the doc.
That saves us the time of documenting the intermediate state.

This is linked to our "linear history" workflow.


        Stefan

Re: Trunk still not open

[Barry OReilly]

[-- Attachment #1: Type: text/plain, Size: 378 bytes --]

> This is probably different for some large/core features, but on most
> of the features I've worked with, the manual rarely provides a lot
> of value.

The Elisp manual has been very useful for me. I basically learned Lisp
from it, and continue to read sections that are relevant to what I'm
doing. It is written in a very clear and helpful style. The authors
should be proud.

[-- Attachment #2: Type: text/html, Size: 448 bytes --]

Re: Trunk still not open

[Lars Magne Ingebrigtsen]

Stefan <monnier@iro.umontreal.ca> writes:

> FWIW, while I suck both at writing documentation and at forcing myself
> to write documentation, I'm in favor of being more strict
> w.r.t documentation.  But in many cases, code is installed in
> a non-definitive way, so it's convenient to install the code first, then
> fix up some of it based on user's feedback and only later write the doc.
> That saves us the time of documenting the intermediate state.

I agree.  Being able to add functionality and get feedback on it fast is
very valuable.  Writing in-depth documentation for stuff that will
likely change is wasted time.

The other thing is that I kinda feel that we're over-documenting some
things.  I think things should just work without the user having to read
documentation at all.  And Emacs has some methods for discoverability
(like 'C-h m') that work quite well if you're looking for what commands
are available.

Not all modes need an entry in the Emacs and Lispref manuals.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Trunk still not open

[Glenn Morris]

Stefan wrote:

> [...] I'm in favor of being more strict w.r.t documentation. But in
> many cases, code is installed in a non-definitive way, so it's
> convenient to install the code first, then fix up some of it based on
> user's feedback and only later write the doc. That saves us the time
> of documenting the intermediate state.

This is absolutely fine by me, and basically what I had in mind when I
said:

   I think that in future there needs to be more of a culture of people at
   least trying to document their own changes, around the time they make
   them.

Not "document it right away", but "don't leave it 12 months till the
next release for some other sucker to do, while you go off and develop
the next shiny thing."

Re: Trunk still not open

[Glenn Morris]

Lars Magne Ingebrigtsen wrote:

> Not all modes need an entry in the Emacs and Lispref manuals.

Sure, and they certainly don't all have them.

Re: Trunk still not open

[Glenn Morris]

Juanma Barranquero wrote:

> Hmm. I'm not so sure, because I don't agree with the "doing nothing at
> all". I mean, surely there are some metrics in which it is "much
> better", but these metrics are not necessarily related to efficiency,
> but peers' goodwill (or project satisfaction, if you will), etc.

Documenting someone else's code is a good way to learn it, but it wears
you down when you spend months and months doing nothing but that.
So yes, it eventually burns through my goodwill, which is basically what
caused me to start this discussion.

>  If developer A requires X hours to document something, and developers
> B, C or D could do it in a tenth of that time, it is really efficient
> for A to do it, assuming that in general A will spend these X hours in
> another Emacs-related task anyway?

I don't think A and B are who you think they are in this scenario. I
think you underestimate the amount of time it would take for me (say) to
document frameset (say). I first have to get familiar with the code, and
only then can I start to try and document it. The first bit takes me a
long time. So to repeat the point I made to start with:

   Some people said they want more frequent releases.
   Well, you can't have that unless more people start doing some of the
   less-interesting work that goes along with releases.

> I suppose a counterargument could be given against developers who only
> want to do "shiny new" things and leave the grunt work to others, but
> I do believe that's not the case in the emacs devel community: most of
> us do our share of grunt work (squashing bugs, fixing typos, testing,
> revising and commenting proposed patches, commiting code from
> non-committers, building snapshots, etc.).

I think I disagree with your assessment here.

>> To get specific: please try and document frameset.el in the lispref.
>
> I didn't even know that it had to be documented in the lisp reference.

Well it does. This just seems obvious to me, if you want people to
actually use it.

> There are pretty fundamental libraries, like uniquify, which are not
> (uniquify is briefly described in the Emacs manual). 

I'm sure there are older features that are not well documented.
All I can say is, patches welcome.

> I will be very surprised if the non-doc status of framesets has kept
> the freeze from unfreezing ;-)

I'm surprised you're surprised. It's been sitting in NEWS without
---/+++ for months, during the time in which Stefan asked for people to
document remaining NEWS items.

Re: Trunk still not open

[Eli Zaretskii]

> From: Stefan <monnier@iro.umontreal.ca>
> Date: Mon, 17 Mar 2014 10:32:42 -0400
> Cc: Dmitry Gutov <dgutov@yandex.ru>, emacs-devel@gnu.org
> 
> it's convenient to install the code first, then fix up some of it
> based on user's feedback and only later write the doc.

There's nothing wrong in writing and fixing the docs together with the
code.  The savings from not doing that are minimal, while the waste --
like this "dead season" we have now, and have had around every release
-- is tangible and painful.

Re: Trunk still not open

[Eli Zaretskii]

> From: Lars Magne Ingebrigtsen <larsi@gnus.org>
> Date: Mon, 17 Mar 2014 16:13:29 +0100
> Cc: emacs-devel@gnu.org
> 
> Being able to add functionality and get feedback on it fast is very
> valuable.  Writing in-depth documentation for stuff that will likely
> change is wasted time.

Deferring documentation for later is a sure recipe to get back where
we are now.  For starters, who will remember to get back to writing
docs afterwards (or want to, for that matter)?  Who will manage the
queue, and how?  etc/NEWS again?  We know where that leads.

> The other thing is that I kinda feel that we're over-documenting some
> things.  I think things should just work without the user having to read
> documentation at all.  And Emacs has some methods for discoverability
> (like 'C-h m') that work quite well if you're looking for what commands
> are available.

I think we already document only what needs to be, see the "---"
markers in NEWS.

> Not all modes need an entry in the Emacs and Lispref manuals.

Neither are they.

Re: Trunk still not open

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Mon, 17 Mar 2014 12:13:19 -0400
> Cc: emacs-devel@gnu.org
> 
> Not "document it right away", but "don't leave it 12 months till the
> next release for some other sucker to do, while you go off and develop
> the next shiny thing."

In my experience, if you don't document right away, you get an
unmanageable pile of pending documentation before long.  It's
impractical.  Not to mention that several months after I write the
code I don't really remember all of the fine points, and the
documentation comes out worse than it could have been.

Re: Trunk still not open

[Juanma Barranquero]

On Mon, Mar 17, 2014 at 5:26 PM, Glenn Morris <rgm@gnu.org> wrote:

> So yes, it eventually burns through my goodwill, which is basically what
> caused me to start this discussion.

I understand that, and for my part in your burnout, I'm sorry.

> I don't think A and B are who you think they are in this scenario. I
> think you underestimate the amount of time it would take for me (say) to
> document frameset (say).

I watch emacs-diffs, so I know whos spend a lot of effort writing
docs. But in my example I wasn't pointing to anyone, nor suggesting
that you or Eli should do it; perhaps it is not evident, but I have a
great deal of respect for both of you and wouldn't dream of assuming
that I know how you should spend your time...

> I think I disagree with your assessment here.

?

So do you think that most emacs developers are only interested in the
"new, shiny" things?

> Well it does. This just seems obvious to me, if you want people to
> actually use it.

Well, framesets aren't documented in the elisp reference, but they are
hardly undocumented. In fact, once I start writing the info docs for
it, I don't think I'm going to say much, if anything, that isn't
already in the docstrings or the comments. frameset.el has a bit more
of 1100 non-empty lines, and ~56% of that is comments or docstrings.

> I'm surprised you're surprised. It's been sitting in NEWS without
> ---/+++ for months, during the time in which Stefan asked for people to
> document remaining NEWS items.

I cannot honestly say that I've looked at NEWS much for months, except
out of necessity (so, infrequently). Also, I find the "+++"/"---"/""
marking opaque, confusing and quite error-prone.

But enough. If framesets must be documented in the elisp reference, I'll do it.

That said, next time I read something like this (Martin's words) in Emacs devel:

  In Emacs 24.3 there are two functions `window-state-get' and
  `window-state-put' which can be used to do that.  The only missing part
  is to write an interface to these functions when saving and restoring
  the desktop.  I don't know whether anybody has done that.

I'm gonna sit on my hands or go fishing typos in lisp/*.el until the
urge to implement passes ;-)

   J

Re: Trunk still not open

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 17 Mar 2014 18:03:33 +0100
> Cc: Eli Zaretskii <eliz@gnu.org>, Stephen Turnbull <stephen@xemacs.org>, 
> 	Emacs developers <emacs-devel@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>
> 
> > Well it does. This just seems obvious to me, if you want people to
> > actually use it.
> 
> Well, framesets aren't documented in the elisp reference, but they are
> hardly undocumented. In fact, once I start writing the info docs for
> it, I don't think I'm going to say much, if anything, that isn't
> already in the docstrings or the comments. frameset.el has a bit more
> of 1100 non-empty lines, and ~56% of that is comments or docstrings.

Try not to document the commands at all, and none of the user-level
facets of the feature.  Only document the functions and variables that
can be used as infrastructure for other similar features.  Then you
won't need to repeat so much of the doc strings.

Re: Trunk still not open

[Juanma Barranquero]

On Mon, Mar 17, 2014 at 6:25 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> Try not to document the commands at all

I'm not going to document the desktop side of things (Xue Fuqiao
already did that); and frameset.el only has a "command" (an
interactive function) and it is register-related, so I wasn't planning
of documenting it either.

> and none of the user-level facets of the feature.  Only document the functions and variables that
> can be used as infrastructure for other similar features.

From my POV, all of frameset.el is infrastructure (though not all
functions need to be documented, of course).

    J

Re: Trunk still not open

[Stephen J. Turnbull]

Juanma Barranquero writes:
 > On Mon, Mar 17, 2014 at 5:43 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
 > 
 > > It very rare that a person who can code is incapable
 > > of writing docs to an acceptable level of quality.  It is of course
 > > common that they have had little practice at it.

 > I'm not bragging; I'm pointing out that I can put words together well
 > enough to be professionally published. And yet, I *suck* at it, I'm
 > extremely slow and inefficient doing that work, because of the simple
 > fact that I *HATE* writing.

Except when posting to mailing lists?<wink/>

 > I consider my teeth being pulled out without painkillers an
 > acceptable, even alluring, procrastinating alternative to
 > writing. Practice has nothing to do with it. I have practice.

So you're one of the very rare ones. *shrug*  My advice to you is
to start looking for somebody who's willing to share the burden of
writing docs with you, because the trend among serious volunteer
projects is to require docs.

Re: Trunk still not open

[David Kastrup]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Juanma Barranquero writes:
>  > On Mon, Mar 17, 2014 at 5:43 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:
>  > 
>  > > It very rare that a person who can code is incapable
>  > > of writing docs to an acceptable level of quality.  It is of course
>  > > common that they have had little practice at it.
>
>  > I'm not bragging; I'm pointing out that I can put words together well
>  > enough to be professionally published. And yet, I *suck* at it, I'm
>  > extremely slow and inefficient doing that work, because of the simple
>  > fact that I *HATE* writing.
>
> Except when posting to mailing lists?<wink/>

   “I didn't have time to write a short letter, so I wrote a long one
   instead.” -- Mark Twain

Documentation is like writing short letters.  There is a similar message
in the joke

    When the head of the experimental physics department approached the
    dean because of funding a particle accelerator, the dean sighed "Why
    can't you be more like the mathematicians?  They just need pen and
    paper and a wastebasket and are busy for years.  And the
    philosophers don't even need a wastebasket."

-- 
David Kastrup

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 7:00 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote:

> Except when posting to mailing lists?<wink/>

*Including* posts. But it's easier to write read-and-forget stuff not
meant to last, of course.

Re: Trunk still not open

[John Yates]

[-- Attachment #1: Type: text/plain, Size: 253 bytes --]

On Tue, Mar 18, 2014 at 3:51 AM, David Kastrup <dak@gnu.org> wrote:

>
>    "I didn't have time to write a short letter, so I wrote a long one
>    instead." -- Mark Twain
>

A common mis-attribution: http://www.classy.dk/log/archive/001074.html

/john

[-- Attachment #2: Type: text/html, Size: 782 bytes --]

Re: Trunk still not open

[David Kastrup]

John Yates <john@yates-sheets.org> writes:

> On Tue, Mar 18, 2014 at 3:51 AM, David Kastrup <dak@gnu.org> wrote:
>
>>
>>    "I didn't have time to write a short letter, so I wrote a long one
>>    instead." -- Mark Twain
>>
>
> A common mis-attribution: http://www.classy.dk/log/archive/001074.html

A misattribution is not when somebody was not the first to say something
but rather when he did not say it at all.

-- 
David Kastrup

Re: Trunk still not open

[John Yates]

[-- Attachment #1: Type: text/plain, Size: 359 bytes --]

On Tue, Mar 18, 2014 at 8:20 AM, David Kastrup <dak@gnu.org> wrote:
>
> A misattribution is not when somebody was not the first to say something
> but rather when he did not say it at all.
>

You are correct.  I stand corrected.  Still, much as I enjoy Mark Twain, I
regret that he gets so much credit for a witticism with a long illustrious
pedigree.

/john

[-- Attachment #2: Type: text/html, Size: 690 bytes --]

Re: Trunk still not open

[David Kastrup]

John Yates <john@yates-sheets.org> writes:

> On Tue, Mar 18, 2014 at 8:20 AM, David Kastrup <dak@gnu.org> wrote:
>>
>> A misattribution is not when somebody was not the first to say
>> something but rather when he did not say it at all.
>>
>
> You are correct.  I stand corrected.  Still, much as I enjoy Mark
> Twain, I regret that he gets so much credit for a witticism with a
> long illustrious pedigree.

Shrug.  He's a humorist, and a _lot_ of humor dates back to antiquity.
You don't blame Shakespeare for plundering the classics either, do you?

Stravinsky once said "lesser artists borrow, great artists steal".  The
point of art is not to be the first in any endeavor but the best.

The perversion of the copyright industry makes it easy to forget that
culture is supposed to be a battlefield of ideas, not a large prison
with solitary confinement for each idea.

It's like code...

-- 
David Kastrup

Re: Trunk still not open

[Glenn Morris]

Juanma Barranquero wrote:

> Well, framesets aren't documented in the elisp reference, but they are
> hardly undocumented. In fact, once I start writing the info docs for
> it, I don't think I'm going to say much, if anything, that isn't
> already in the docstrings or the comments. frameset.el has a bit more
> of 1100 non-empty lines, and ~56% of that is comments or docstrings.

Yes, I found it daunting when I tried to look at it! :)
(But also it convinced me you can write perfectly good English
documentation; not that I needed convincing.)
You don't need to repeat all that info.
A brief definition of what a frameset is, and what you might want to use
it for, and then an overview of the main functions for creating,
manipulating them, etc. So that people know the concept exists and what
functions to look at to get started.

(But I say this without having looked at it in detail. I see Eli already
commented as well.)

> I cannot honestly say that I've looked at NEWS much for months, except
> out of necessity (so, infrequently).

So, I think you are kind of proving my point here.

For months/weeks, the project's leader has been saying: no new development
can happen until the remaining items in NEWS have been documented.
So why hasn't everyone been making that their number one priority?
I can only assume it's because they thought "someone else will take care
of that".


In case anyone else hasn't looked at NEWS, please do.
For example, there are some OS X specific changes that I imagine need at
least a brief mention in the OS X appendix.
There are several CEDET items that may or may not have already been
documented (and may or may not even need documenting).
I am not familiar with these things and cannot document them.


There are also many bugs that need addressing.
First the "important" ones (several related to package.el), but also at
some point ideally anything filed after 24.3's release, or against
24.3 or 24.3.50, should be reviewed. This is ~ 700 bugs. Although ~ half
of those are wishlist/minor.

Re: Trunk still not open

[Jambunathan K]

Juanma Barranquero <lekktu@gmail.com> writes:

> I'm not bragging;

True.  You are whining.

> I *HATE* writing.

(If you managed to get here)

A mere feeling is of little relevance to this list.

It is better to contextualize that feeling and articulate clearly how
that feeling is of interest to emacs-devel (i.e., how does your feelings
"affect" - positively, negatively or neutrally - Emacs development)

So,

1. IF the code changes MUST be accompanied by documentation and
2. IF your patches are without documentation
3. THEN they will be queued
4. UNTIL the documentation is written.

`IF' in (1) and (2) are big `IFs'.  I am just describing a possible
(even if remote) scenario.

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 5:13 PM, Jambunathan K <kjambunathan@gmail.com> wrote:

> A mere feeling is of little relevance to this list.

Your opinion about my feelings is of no relevance whatsoever to me.

   J

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 4:54 PM, Glenn Morris <rgm@gnu.org> wrote:

> Yes, I found it daunting when I tried to look at it! :)

That's... good to know, I suppose? ;-)

> (But also it convinced me you can write perfectly good English
> documentation; not that I needed convincing.)

Documentation can be extracted from me, in a process somewhat akin to
fracking but not so nice, you mean.

> You don't need to repeat all that info.
> A brief definition of what a frameset is, and what you might want to use
> it for, and then an overview of the main functions for creating,
> manipulating them, etc. So that people know the concept exists and what
> functions to look at to get started.

As David just reminded us, is hard to do brief. I'll try.

> So why hasn't everyone been making that their number one priority?
> I can only assume it's because they thought "someone else will take care
> of that".

Or they just think they're not good at it?

> There are also many bugs that need addressing.
> First the "important" ones (several related to package.el), but also at
> some point ideally anything filed after 24.3's release, or against
> 24.3 or 24.3.50, should be reviewed. This is ~ 700 bugs. Although ~ half
> of those are wishlist/minor.

Yes, but fixing bugs shouldn't affect the (un)freezing; pretest is as
good a time as any to fix bug.

   J

Re: Trunk still not open

[David Kastrup]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Tue, Mar 18, 2014 at 4:54 PM, Glenn Morris <rgm@gnu.org> wrote:
>
>> So why hasn't everyone been making that their number one priority?  I
>> can only assume it's because they thought "someone else will take
>> care of that".
>
> Or they just think they're not good at it?

If two relay teams are running against each other, and the first relay
for team A is to be run by a cripple, and the first relay of team B by a
healthy person sleeping on a couch, chances are that team A will win.

The chances that somebody will improve bad documentation are much better
than the chances of somebody writing documentation from scratch.

-- 
David Kastrup

Re: Trunk still not open

[Jambunathan K]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Tue, Mar 18, 2014 at 5:13 PM, Jambunathan K <kjambunathan@gmail.com> wrote:
>
>> A mere feeling is of little relevance to this list.
>
> Your opinion about my feelings is of no relevance whatsoever to me.

You talk about "me" and "you" but not about other folks who are on
emacs-devel.

Assessment: Avoids responsibility to write documentation and cloaks that
in skillful language.

>
>    J

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 6:21 PM, David Kastrup <dak@gnu.org> wrote:

> If two relay teams are running against each other, and the first relay
> for team A is to be run by a cripple, and the first relay of team B by a
> healthy person sleeping on a couch, chances are that team A will win.

Thankfully we aren't running a relay race, uh?

> The chances that somebody will improve bad documentation are much better
> than the chances of somebody writing documentation from scratch.

Agreed.

   J

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 6:25 PM, Jambunathan K <kjambunathan@gmail.com> wrote:

> Assessment: Avoids responsibility to write documentation and cloaks that
> in skillful language.

Assessment: you're a prime target for the late Erik Naggum's wonderful comment,

  I'm bothered by the fact that stupid people don't spontaneously
  combust, which they should.
                              -- Erik Naggum

Re: Trunk still not open

[Jambunathan K]

Juanma Barranquero <lekktu@gmail.com> writes:


You won't be able send in patches, if Maintainers take a strict view.
You are arguing that Maintainers should take a lenient view because
patches are exceptional.

(You are trying to divert the discussion)

----------------------------------------------------------------

>   I'm bothered by the fact that stupid people don't spontaneously
>   combust, which they should.
>                               -- Erik Naggum


Erik Naggum is already combusted or composted.  I am not.

In this list, the arguments generally boil to this:

1. Dog twists the tail.
2. Tail twists the dog

3. Dog becomes tail.
4. Tail becomes Dog.

(3) or (4) adds complexity and nuance to discussion.

Re: Trunk still not open

[Juanma Barranquero]

On Tue, Mar 18, 2014 at 6:51 PM, Jambunathan K <kjambunathan@gmail.com> wrote:

> Erik Naggum is already combusted or composted.  I am not.

A pity.

Re: Trunk still not open

[Jambunathan K]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Tue, Mar 18, 2014 at 6:51 PM, Jambunathan K <kjambunathan@gmail.com> wrote:
>
>> Erik Naggum is already combusted or composted.  I am not.
>
> A pity.

Don't give excuses.  Write that documentation.

Re: Trunk still not open

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 345 bytes --]

On Mar 18, 2014 8:07 PM, "Jambunathan K" <kjambunathan@gmail.com> wrote:
>
> Don't give excuses.  Write that documentation.

Obviously, you're too stupid to notice that I had agreed to write it even
before your quite enlightening first... intervention. Don't let facts get
in the way of your patronizing, you could burst an artery or something.

[-- Attachment #2: Type: text/html, Size: 484 bytes --]

Re: Trunk still not open

[Jambunathan K]

Juanma Barranquero <lekktu@gmail.com> writes:

> I had agreed to write it

If this were reddit, I will give you gold for saying this.

Re: Trunk still not open

[David Kastrup]

Jambunathan K <kjambunathan@gmail.com> writes:

> Juanma Barranquero <lekktu@gmail.com> writes:
>
>> On Tue, Mar 18, 2014 at 6:51 PM, Jambunathan K <kjambunathan@gmail.com> wrote:
>>
>>> Erik Naggum is already combusted or composted.  I am not.
>>
>> A pity.
>
> Don't give excuses.  Write that documentation.

git shortlog --follow -s origin doc
[...]
    18  Jambunathan K
[...]
  5151  Juanma Barranquero

-- 
David Kastrup

Re: Trunk still not open

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Jambunathan K <kjambunathan@gmail.com> writes:
>
>> Juanma Barranquero <lekktu@gmail.com> writes:
>>
>>> On Tue, Mar 18, 2014 at 6:51 PM, Jambunathan K <kjambunathan@gmail.com> wrote:
>>>
>>>> Erik Naggum is already combusted or composted.  I am not.
>>>
>>> A pity.
>>
>> Don't give excuses.  Write that documentation.
>
> git shortlog --follow -s origin doc
> [...]
>     18  Jambunathan K
> [...]
>   5151  Juanma Barranquero

Actually, I should have quoted the line

   174  Erik Naggum

here as well.  It's a fixed target to aspire to, modulo changes in the
git shortlog --follow algorithm, of course.

-- 
David Kastrup

Re: Trunk still not open

[joakim]

Glenn Morris <rgm@gnu.org> writes:

> Stefan Monnier wrote:
>
>>> As for docs, I apologize (being one of the culprits), but as I rarely,
>>> if ever, read the manual, one can understand how I can forget its
>>> existence from time to time.
>>
>> Hmm... so maybe that's also why I'm one of the other culprits?
>
> Please at least proof-read the documentation I have recently written for
> smie, a subject about which I know nothing. (It is very inefficient for
> me to have to document things like this.) And maybe also the tutorial
> changes re electric-indent.
>

I attempted to proofread the SMIE dokumentation. I dont know anything
more about operator precedence grammars than what I learned by reading
the manual section, and the wikipedia article. I also toyed a bit with
the examples provided in the docs.

I only found the minor debatable nitpicks included below.

SMIE, short for Simple Minded Indentation Engine,  is a package that provides a generic navigation and indentation
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    
IMHO its nicer to not rely on the title in the flow of the text

   An operator precedence grammar is a very primitive technology for
   ^^
tho
^^^ is ´tho´ a real word?


-- 
Joakim Verona

Re: Trunk still not open

[Stephen J. Turnbull]

Glenn Morris writes:

 > For months/weeks, the project's leader has been saying: no new
 > development can happen until the remaining items in NEWS have been
 > documented.  So why hasn't everyone been making that their number
 > one priority?

Because it's simply not true.  You just do your development on a local
branch and wait for trunk to open again, and then push your doc-less
changesets as usual.

 > I can only assume it's because they thought "someone else will take
 > care of that".

And they're right.  Eventually, someone will.

Re: Trunk still not open

[David Kastrup]

Jambunathan K <kjambunathan@gmail.com> writes:

> David Kastrup <dak@gnu.org> writes:
>
>> git shortlog --follow -s origin doc
>> [...]
>>     18  Jambunathan K
>> [...]
>>   5151  Juanma Barranquero
>
> You are underestimating my contribution.
>
> ox-html.el and ox-odt.el lists me as an author.
>
> The ODT section of Org manual runs to atleast 10 printed pages.

Do you really want me to tabulate the corresponding line counts as well?

> So I have the right to be part of emacs-devel and participate in this
> thread.

You are currently not as much "participating" as making an ass of
yourself.  When you write stuff like "Don't give excuses.  Write that
documentation." to Juanma, you are not impressing anybody.

> You should appreciate me for having an opinion and stating it publicly
> in a direct language.  As an Emacs user, I have a vested interest in
> making sure that various components come with good documentation and I
> will use whatever is within my powers - stating an opinion - to
> promote good behaviour.

If you want to "promote good behavior", you could start by not acting
like you are in a position to order people around.  Even Richard only
has the power to tell people what _not_ to do, but not what to do.

> If you want more nuanced arguments - something that doesn't limit it's
> critique to kicking in the groin - just ping me.

I think you misunderstand what a public mailing list is for.  Civility
is not an option that has to be requested first.

-- 
David Kastrup

Re: Trunk still not open

[Glenn Morris]

joakim@verona.se wrote:

> SMIE, short for Simple Minded Indentation Engine,  is a package that provides a generic navigation and indentation
>       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    
> IMHO its nicer to not rely on the title in the flow of the text

I agree; please apply.

>    An operator precedence grammar is a very primitive technology for
>    ^^

It read fine to me without "an".

> tho
> ^^^ is ´tho´ a real word?

I can't see this anywhere in the manual, but please replace it with
"though" if it's there.

Re: Trunk still not open

[Jambunathan K]

David Kastrup <dak@gnu.org> writes:

> Do you really want me to tabulate the corresponding line counts as
> well?

If I confront a fact with a fact, does that make you un-settled?

It seems people in upper-houses take offence when I point out proper
etiquette.  'Stupid', 'ass' and 'kill yourself' are words I don't -
didn't - use.  It is beneath to me stoop to such low levels.

I am happy to belong to the lower house.

Re: Trunk still not open

[Jambunathan K]

Stephen

Thanks for this note.  I can put these links to some use.

I MAY take up
http://lists.gnu.org/archive/html/emacs-devel/2012-08/msg00308.html.

A lot depends on how mature a conversation senior developers, old timers
and the staunch loyalist can hold.

PS: This is a list of elites who would ascend their throne to make their
arguments forceful.  Being an ass myself, I dislike elites :-).


"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> To the extent that you want lower-level details from the horse's
> mouth, somebody will probably have to interview Richard (general
> Emacs), Gerd (redisplay), and Ken'ichi (MULE), among others (those are
> the areas where I know a particular person did a lot of design by
> themselves, but I don't have comprehensive knowledge of Emacs) but
> Richard's paper
>
> http://www.gnu.org/software/emacs/emacs-paper.html
>
> is a pretty good start on the "whys" and many of the higher-level
> "hows" of Emacs design.  Also
>
> http://www.xemacs.org/Documentation/21.5/html/internals.html
>
> is in great part relevant, with many lower-level details that are
> applicable to Emacs as well.  It is quite incomplete and there are
> piles of junk that are basically old block comments mover there from
> the source, but I still find it useful when I read Emacs C code.

Re: Trunk still not open

[Alexander Poslavsky]

[-- Attachment #1: Type: text/plain, Size: 503 bytes --]

There might me people lurking on the list who might be interested in
writing (some) documentation. Is there some low-hanging fruit and / or
documentation how people could start?

Looking in the bug-tracker for documentation bugs shows several of them,
but none that actually involve writing docs, instead they seem to be bugs
related to how docs are being shown.

Reading the source when writing documentation is fine, but reading *all*
the source to find things to document is a bit much.

Newbie Alex

[-- Attachment #2: Type: text/html, Size: 603 bytes --]

Re: Trunk still not open

[Jambunathan K]

David Kastrup <dak@gnu.org> writes:

> git shortlog --follow -s origin doc
> [...]
>     18  Jambunathan K
> [...]
>   5151  Juanma Barranquero

You are underestimating my contribution.

ox-html.el and ox-odt.el lists me as an author.

The ODT section of Org manual runs to atleast 10 printed pages.  So I
have the right to be part of emacs-devel and participate in this thread.

You should appreciate me for having an opinion and stating it publicly
in a direct language.  As an Emacs user, I have a vested interest in
making sure that various components come with good documentation and I
will use whatever is within my powers - stating an opinion - to promote
good behaviour.

If you want more nuanced arguments - something that doesn't limit it's
critique to kicking in the groin - just ping me.

Re: Trunk still not open

[Jambunathan K]

Alexander Poslavsky <a.poslavsky@gmail.com> writes:

> There might me people lurking on the list who might be interested in
> writing (some) documentation. Is there some low-hanging fruit and / or
> documentation how people could start?

Look the NEWS file.

    C-h n

and read through it.

http://repo.or.cz/w/emacs.git/blob_plain/HEAD:/etc/NEWS

----------------------------------------------------------------

Here is a very small and well-defined task.

    http://lists.gnu.org/archive/html/emacs-devel/2014-03/msg00204.html

and a related bug

    http://lists.gnu.org/archive/html/emacs-devel/2014-03/msg00330.html


> Newbie Alex

Re: Trunk still not open

[Alexander Poslavsky]

[-- Attachment #1: Type: text/plain, Size: 802 bytes --]

Thanks, something to look into tonight


On Wed, Mar 19, 2014 at 5:18 PM, Jambunathan K <kjambunathan@gmail.com>wrote:

> Alexander Poslavsky <a.poslavsky@gmail.com> writes:
>
> > There might me people lurking on the list who might be interested in
> > writing (some) documentation. Is there some low-hanging fruit and / or
> > documentation how people could start?
>
> Look the NEWS file.
>
>     C-h n
>
> and read through it.
>
> http://repo.or.cz/w/emacs.git/blob_plain/HEAD:/etc/NEWS
>
> ----------------------------------------------------------------
>
> Here is a very small and well-defined task.
>
>     http://lists.gnu.org/archive/html/emacs-devel/2014-03/msg00204.html
>
> and a related bug
>
>     http://lists.gnu.org/archive/html/emacs-devel/2014-03/msg00330.html
>
>
> > Newbie Alex
>

[-- Attachment #2: Type: text/html, Size: 1566 bytes --]

Re: Trunk still not open

[Jambunathan K]

David Kastrup <dak@gnu.org> writes:

> git shortlog --follow -s origin doc
> [...]
>     18  Jambunathan K
> [...]
>   5151  Juanma Barranquero

Poor or stupid people shouldn't vote.  Is that your political position?

I am not much familiar with the political situation in Switzerland but I
have some personal experience of situation here in India.

Re: Trunk still not open

[Glenn Morris]

Alexander Poslavsky wrote:

> Thanks, something to look into tonight

Pleae be careful whose advice you follow, especially when they suggest
you work on their own issues. (Also, a lot of doc bugs in the tracker are
not worth spending time on IMO.)

Re: Trunk still not open

[Bastien]

Hi Alexander,

Alexander Poslavsky <a.poslavsky@gmail.com> writes:

> Thanks, something to look into tonight

Hint:

C-u C-s [ ^ - + ] C-q C-j \ * \ { 3 \ } RET

will move the cursor to entries that may need documentation
(there are some false positives, though.)

-- 
 Bastien

Re: Trunk still not open

[Bastien]

Bastien <bzg@gnu.org> writes:

> C-u C-s [ ^ - + ] C-q C-j \ * \ { 3 \ } RET

(Of course, this is in the etc/NEWS file.)

-- 
 Bastien

Re: Trunk still not open

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Date: Wed, 19 Mar 2014 13:27:12 +0530
> Cc: emacs-devel@gnu.org
> 
> I MAY take up
> http://lists.gnu.org/archive/html/emacs-devel/2012-08/msg00308.html.
> 
> A lot depends on how mature a conversation senior developers, old timers
> and the staunch loyalist can hold.

As long as your copyright assignment is not on file, I see no point in
conversing with you about any such tasks.

Re: Trunk still not open

[Glenn Morris]

Bastien wrote:

> Bastien <bzg@gnu.org> writes:
>
>> C-u C-s [ ^ - + ] C-q C-j \ * \ { 3 \ } RET
>
> (Of course, this is in the etc/NEWS file.)

I don't mean to be discouraging, but I suspect the remaining
undocumented NEWS items are not an easy place for new contributors to
start. In fact, a quick scan suggests only Martin's display-related
changes (which I think he is in the process of documenting?) and some
OS X bits remain.

I'm afraid I'm not sure what the best way to find relevant issues
needing documentation is. Maybe start with a search for bugs with "doc"
in the subject, but the results need interpreting with a bit of care.

Re: Trunk still not open

[Stephen J. Turnbull]

Glenn Morris writes:
 > Alexander Poslavsky wrote:
 > 
 > > Thanks, something to look into tonight
 > 
 > Pleae be careful whose advice you follow, especially when they suggest
 > you work on their own issues. (Also, a lot of doc bugs in the tracker are
 > not worth spending time on IMO.)

Why not?  (The point being that if you explain briefly, Alexander
could put together a list of bugs he thinks could be closed for that
reason, and you could then close them efficiently.  Then for the next
round, give him tracker privilege and he can close them!)

Re: Trunk still not open

[Stefan]

> Please at least proof-read the documentation I have recently written for
> smie, a subject about which I know nothing. (It is very inefficient for
> me to have to document things like this.) And maybe also the tutorial
> changes re electric-indent.

I did read them when you installed them.  They both looked very good.
I just re-read them, and they still look great.  Thanks a lot.


        Stefan

Re: Trunk still not open

[Nicolas Richard]

[-- Attachment #1: Type: text/plain, Size: 291 bytes --]

Hi Bastien,

Bastien <bzg@gnu.org> writes:
> Hint:
>
> C-u C-s [ ^ - + ] C-q C-j \ * \ { 3 \ } RET
>
> will move the cursor to entries that may need documentation
> (there are some false positives, though.)

I'm surprised you did not convert that to some org mode thingy.

Ok, here you are:

[-- Attachment #2: convert NEWS file unmarked items to TODO items suitable for org mode --]
[-- Type: application/emacs-lisp, Size: 2806 bytes --]

[-- Attachment #3: Type: text/plain, Size: 137 bytes --]


then :
C-h N
C-x C-q
M-x yf/NEWS-to-TODO
M-x org-mode
M-x org-agenda
<
t

(I'll admit that the above UI is not really good.)

-- 
Nico.

Re: Trunk still not open

[Stefan]

We currently need to finish updating the doc w.r.t the NEWS file, but as
Glenn points out, the remaining entries are being done IIUC and probably
not that easy.

The next thing we need is to proofread the manual.  We always have a lot
of trouble finding people to do that, so help would be greatly
appreciated in this regard.

Here's how to do it:
1- pick a chapter in the Emacs or Elisp manual.
2- read the chapter, paying particular attention to parts that could be
   affected by the changes in 24.4 (need to read the NEWS file for
   that).
3- tell us which chapter you've read, along with any
   comments/fixes/questions you may have about it.
4- go back to 1 until all chapters have been reviewed.

We keep track (in admin/FOR-RELEASE) of which chapter has been reviewed
(and by whom).  Currently, this still has the data for 24.3 (where you
can see that Yidong and Glenn did all the work: shame on the rest of
us), so really, no chapter has been proofread yet.


        Stefan

Re: Trunk still not open

[Glenn Morris]

Stefan wrote:

> We keep track (in admin/FOR-RELEASE) of which chapter has been reviewed
> (and by whom).  Currently, this still has the data for 24.3 (where you
> can see that Yidong and Glenn did all the work: shame on the rest of
> us), so really, no chapter has been proofread yet.

I believe that's actually the data for 24.1.
Traditionally we weaseled our way out of this job by saying that it only
had to be done on a major release (23.1, 24.1). So I wasn't expecting
this to be necessary for 24.4. (But necessary or not, it's always welcome.)

(Personally I simply don't think the human resources exist to do this
job for every minor release. Remember that originally it was supposed to
be at least two people reading every chapter, but we could only manage
one in recent years. And the person who did the majority of it isn't
around any more. But I should stop spreading negativity...)

Re: Trunk still not open

[Jambunathan K]

Glenn Morris <rgm@gnu.org> writes:

> Alexander Poslavsky wrote:
>
>> Thanks, something to look into tonight
>
> Pleae be careful whose advice you follow, especially when they suggest
> you work on their own issues. (Also, a lot of doc bugs in the tracker are
> not worth spending time on IMO.)

A small correction.  The issue I pointed to are GNU Emacs issues.

Re: Trunk still not open

[Paul Eggert]

On 03/19/2014 11:45 AM, Stefan wrote:
> 3- tell us which chapter you've read, along with any
>     comments/fixes/questions you may have about it.

I read the Elisp manual's chapter "Numbers", and installed fixes for the 
problems I found.

Re: Trunk still not open

[Jambunathan K]

I have decided not to make any assignments at all.  I am also leaving
this and Org-mode list.

Disappointed more with himself (than others),
Jambunathan K.

> As long as your copyright assignment is not on file, I see no point in
> conversing with you about any such tasks.

This is a reasonable line of argument and I have no issues with it.

Re: Trunk still not open

[Bastien]

Hi Nicolas,

"Nicolas Richard" <theonewiththeevillook@yahoo.fr> writes:

> I'm surprised you did not convert that to some org mode thingy.

:)

Thanks for the recipe!  I *might* use it one day---for now I'm
busy enough with Org... and M-x debbugs-org RET (which you may
also enjoy, if you don't know it.)

-- 
 Bastien

Re: Trunk still not open

[Stefan]

> I believe that's actually the data for 24.1.
> Traditionally we weaseled our way out of this job by saying that it only
> had to be done on a major release (23.1, 24.1). So I wasn't expecting
> this to be necessary for 24.4.

Oh, that's right.  So it's not strictly necessary.

> (But necessary or not, it's always welcome.)

Yes, very much so, even if the proofreading is not exhaustive: there
have been many changes since 24.1.

> (Personally I simply don't think the human resources exist to do this
> job for every minor release. Remember that originally it was supposed to
> be at least two people reading every chapter, but we could only manage
> one in recent years. And the person who did the majority of it isn't
> around any more. But I should stop spreading negativity...)

Yes, I think you've done your share (and so did Yidong).


        Stefan

Re: Trunk still not open

[Stefan]

>> 3- tell us which chapter you've read, along with any
>> comments/fixes/questions you may have about it.
> I read the Elisp manual's chapter "Numbers", and installed fixes for the
> problems I found.

Thanks,


        Stefan