* Trunk still not open
@ 2014-02-27 5:00 Stefan Monnier
2014-03-13 20:55 ` Glenn Morris
0 siblings, 1 reply; 128+ messages in thread
From: Stefan Monnier @ 2014-02-27 5:00 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-02-27 5:00 Stefan Monnier
@ 2014-03-13 20:55 ` Glenn Morris
2014-03-14 7:58 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-13 20:55 UTC (permalink / raw
To: Stefan Monnier; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-13 20:55 ` Glenn Morris
@ 2014-03-14 7:58 ` Eli Zaretskii
2014-03-14 9:29 ` Stephen J. Turnbull
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 7:58 UTC (permalink / raw
To: Glenn Morris; +Cc: monnier, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 7:58 ` Eli Zaretskii
@ 2014-03-14 9:29 ` Stephen J. Turnbull
2014-03-14 9:35 ` David Kastrup
` (4 more replies)
0 siblings, 5 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-14 9:29 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:29 ` Stephen J. Turnbull
@ 2014-03-14 9:35 ` David Kastrup
2014-03-14 9:47 ` Eli Zaretskii
2014-03-14 9:43 ` Eli Zaretskii
` (3 subsequent siblings)
4 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-14 9:35 UTC (permalink / raw
To: emacs-devel
"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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:29 ` Stephen J. Turnbull
2014-03-14 9:35 ` David Kastrup
@ 2014-03-14 9:43 ` Eli Zaretskii
2014-03-14 9:55 ` Bastien
` (2 subsequent siblings)
4 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 9:43 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:35 ` David Kastrup
@ 2014-03-14 9:47 ` Eli Zaretskii
2014-03-14 10:02 ` David Kastrup
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 9:47 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:29 ` Stephen J. Turnbull
2014-03-14 9:35 ` David Kastrup
2014-03-14 9:43 ` Eli Zaretskii
@ 2014-03-14 9:55 ` Bastien
2014-03-14 15:16 ` Stephen J. Turnbull
2014-03-14 11:42 ` Eric S. Raymond
2014-03-14 12:34 ` Dmitry Gutov
4 siblings, 1 reply; 128+ messages in thread
From: Bastien @ 2014-03-14 9:55 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
"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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:47 ` Eli Zaretskii
@ 2014-03-14 10:02 ` David Kastrup
2014-03-14 10:23 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-14 10:02 UTC (permalink / raw
To: Eli Zaretskii; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 10:02 ` David Kastrup
@ 2014-03-14 10:23 ` Eli Zaretskii
2014-03-14 10:40 ` David Kastrup
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 10:23 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 10:23 ` Eli Zaretskii
@ 2014-03-14 10:40 ` David Kastrup
2014-03-14 11:02 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-14 10:40 UTC (permalink / raw
To: Eli Zaretskii; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 10:40 ` David Kastrup
@ 2014-03-14 11:02 ` Eli Zaretskii
0 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 11:02 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:29 ` Stephen J. Turnbull
` (2 preceding siblings ...)
2014-03-14 9:55 ` Bastien
@ 2014-03-14 11:42 ` Eric S. Raymond
2014-03-15 9:13 ` Jambunathan K
2014-03-14 12:34 ` Dmitry Gutov
4 siblings, 1 reply; 128+ messages in thread
From: Eric S. Raymond @ 2014-03-14 11:42 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
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>
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:29 ` Stephen J. Turnbull
` (3 preceding siblings ...)
2014-03-14 11:42 ` Eric S. Raymond
@ 2014-03-14 12:34 ` Dmitry Gutov
2014-03-14 13:38 ` Stefan Monnier
` (2 more replies)
4 siblings, 3 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-14 12:34 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
"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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 12:34 ` Dmitry Gutov
@ 2014-03-14 13:38 ` Stefan Monnier
2014-03-14 19:35 ` Glenn Morris
2014-03-14 14:34 ` Stephen J. Turnbull
2014-03-14 19:31 ` Glenn Morris
2 siblings, 1 reply; 128+ messages in thread
From: Stefan Monnier @ 2014-03-14 13:38 UTC (permalink / raw
To: Dmitry Gutov; +Cc: Stephen J. Turnbull, emacs-devel
> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 12:34 ` Dmitry Gutov
2014-03-14 13:38 ` Stefan Monnier
@ 2014-03-14 14:34 ` Stephen J. Turnbull
2014-03-14 14:57 ` Dmitry Gutov
2014-03-14 19:31 ` Glenn Morris
2 siblings, 1 reply; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-14 14:34 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 14:34 ` Stephen J. Turnbull
@ 2014-03-14 14:57 ` Dmitry Gutov
2014-03-14 15:29 ` Eli Zaretskii
2014-03-14 15:39 ` Stephen J. Turnbull
0 siblings, 2 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-14 14:57 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 9:55 ` Bastien
@ 2014-03-14 15:16 ` Stephen J. Turnbull
0 siblings, 0 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-14 15:16 UTC (permalink / raw
To: Bastien; +Cc: emacs-devel
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.)
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 14:57 ` Dmitry Gutov
@ 2014-03-14 15:29 ` Eli Zaretskii
2014-03-15 6:22 ` Dmitry Gutov
2014-03-14 15:39 ` Stephen J. Turnbull
1 sibling, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-14 15:29 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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?
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 14:57 ` Dmitry Gutov
2014-03-14 15:29 ` Eli Zaretskii
@ 2014-03-14 15:39 ` Stephen J. Turnbull
2014-03-15 6:30 ` Dmitry Gutov
1 sibling, 1 reply; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-14 15:39 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 12:34 ` Dmitry Gutov
2014-03-14 13:38 ` Stefan Monnier
2014-03-14 14:34 ` Stephen J. Turnbull
@ 2014-03-14 19:31 ` Glenn Morris
2014-03-14 20:08 ` Daniel Colascione
` (2 more replies)
2 siblings, 3 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-14 19:31 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 13:38 ` Stefan Monnier
@ 2014-03-14 19:35 ` Glenn Morris
2014-03-18 20:01 ` joakim
2014-03-19 16:43 ` Stefan
0 siblings, 2 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-14 19:35 UTC (permalink / raw
To: Stefan Monnier; +Cc: Stephen J. Turnbull, emacs-devel, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 19:31 ` Glenn Morris
@ 2014-03-14 20:08 ` Daniel Colascione
2014-03-16 1:00 ` Glenn Morris
2014-03-15 1:55 ` Stephen J. Turnbull
2014-03-15 3:22 ` Dmitry Gutov
2 siblings, 1 reply; 128+ messages in thread
From: Daniel Colascione @ 2014-03-14 20:08 UTC (permalink / raw
To: Glenn Morris, Dmitry Gutov; +Cc: emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 19:31 ` Glenn Morris
2014-03-14 20:08 ` Daniel Colascione
@ 2014-03-15 1:55 ` Stephen J. Turnbull
2014-03-15 2:09 ` Dmitry Gutov
2014-03-17 14:32 ` Stefan
2014-03-15 3:22 ` Dmitry Gutov
2 siblings, 2 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-15 1:55 UTC (permalink / raw
To: Glenn Morris; +Cc: emacs-devel, Dmitry Gutov
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?
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 1:55 ` Stephen J. Turnbull
@ 2014-03-15 2:09 ` Dmitry Gutov
2014-03-15 8:22 ` Eli Zaretskii
2014-03-15 10:02 ` Jambunathan K
2014-03-17 14:32 ` Stefan
1 sibling, 2 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-15 2:09 UTC (permalink / raw
To: Stephen J. Turnbull, Glenn Morris; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 19:31 ` Glenn Morris
2014-03-14 20:08 ` Daniel Colascione
2014-03-15 1:55 ` Stephen J. Turnbull
@ 2014-03-15 3:22 ` Dmitry Gutov
2014-03-15 7:10 ` Thien-Thi Nguyen
2014-03-15 8:45 ` Eli Zaretskii
2 siblings, 2 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-15 3:22 UTC (permalink / raw
To: Glenn Morris; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 15:29 ` Eli Zaretskii
@ 2014-03-15 6:22 ` Dmitry Gutov
2014-03-15 9:02 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-15 6:22 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 15:39 ` Stephen J. Turnbull
@ 2014-03-15 6:30 ` Dmitry Gutov
2014-03-17 4:33 ` Stephen J. Turnbull
0 siblings, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-15 6:30 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 3:22 ` Dmitry Gutov
@ 2014-03-15 7:10 ` Thien-Thi Nguyen
2014-03-15 9:02 ` David Kastrup
2014-03-15 8:45 ` Eli Zaretskii
1 sibling, 1 reply; 128+ messages in thread
From: Thien-Thi Nguyen @ 2014-03-15 7:10 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 2:09 ` Dmitry Gutov
@ 2014-03-15 8:22 ` Eli Zaretskii
2014-03-15 10:52 ` Juanma Barranquero
2014-03-16 0:39 ` Dmitry Gutov
2014-03-15 10:02 ` Jambunathan K
1 sibling, 2 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-15 8:22 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 3:22 ` Dmitry Gutov
2014-03-15 7:10 ` Thien-Thi Nguyen
@ 2014-03-15 8:45 ` Eli Zaretskii
2014-03-16 0:32 ` Dmitry Gutov
2014-03-16 3:57 ` Jambunathan K
1 sibling, 2 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-15 8:45 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 7:10 ` Thien-Thi Nguyen
@ 2014-03-15 9:02 ` David Kastrup
0 siblings, 0 replies; 128+ messages in thread
From: David Kastrup @ 2014-03-15 9:02 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 6:22 ` Dmitry Gutov
@ 2014-03-15 9:02 ` Eli Zaretskii
2014-03-16 0:26 ` Dmitry Gutov
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-15 9:02 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 11:42 ` Eric S. Raymond
@ 2014-03-15 9:13 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-15 9:13 UTC (permalink / raw
To: Eric S. Raymond; +Cc: Stephen J. Turnbull, emacs-devel
"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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 2:09 ` Dmitry Gutov
2014-03-15 8:22 ` Eli Zaretskii
@ 2014-03-15 10:02 ` Jambunathan K
2014-03-15 10:19 ` David Kastrup
2014-03-15 11:10 ` Eli Zaretskii
1 sibling, 2 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-15 10:02 UTC (permalink / raw
To: Dmitry Gutov; +Cc: Stephen J. Turnbull, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:02 ` Jambunathan K
@ 2014-03-15 10:19 ` David Kastrup
2014-03-15 11:01 ` Jambunathan K
2014-03-15 11:10 ` Eli Zaretskii
1 sibling, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-15 10:19 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 8:22 ` Eli Zaretskii
@ 2014-03-15 10:52 ` Juanma Barranquero
2014-03-15 11:18 ` Eli Zaretskii
` (2 more replies)
2014-03-16 0:39 ` Dmitry Gutov
1 sibling, 3 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-15 10:52 UTC (permalink / raw
To: Eli Zaretskii; +Cc: Stephen Turnbull, Emacs developers, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:19 ` David Kastrup
@ 2014-03-15 11:01 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-15 11:01 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:02 ` Jambunathan K
2014-03-15 10:19 ` David Kastrup
@ 2014-03-15 11:10 ` Eli Zaretskii
1 sibling, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-15 11:10 UTC (permalink / raw
To: Jambunathan K; +Cc: stephen, emacs-devel, dgutov
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:52 ` Juanma Barranquero
@ 2014-03-15 11:18 ` Eli Zaretskii
2014-03-15 11:28 ` Juanma Barranquero
2014-03-16 1:08 ` Glenn Morris
2014-03-17 4:43 ` Stephen J. Turnbull
2 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-15 11:18 UTC (permalink / raw
To: Juanma Barranquero; +Cc: stephen, emacs-devel, dgutov
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 11:18 ` Eli Zaretskii
@ 2014-03-15 11:28 ` Juanma Barranquero
0 siblings, 0 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-15 11:28 UTC (permalink / raw
To: Eli Zaretskii; +Cc: Stephen Turnbull, dgutov, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 9:02 ` Eli Zaretskii
@ 2014-03-16 0:26 ` Dmitry Gutov
2014-03-16 3:49 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 0:26 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 8:45 ` Eli Zaretskii
@ 2014-03-16 0:32 ` Dmitry Gutov
2014-03-16 1:27 ` Glenn Morris
2014-03-16 11:26 ` Nicolas Richard
2014-03-16 3:57 ` Jambunathan K
1 sibling, 2 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 0:32 UTC (permalink / raw
To: Eli Zaretskii; +Cc: emacs-devel
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".
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 8:22 ` Eli Zaretskii
2014-03-15 10:52 ` Juanma Barranquero
@ 2014-03-16 0:39 ` Dmitry Gutov
2014-03-16 3:52 ` Eli Zaretskii
1 sibling, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 0:39 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 20:08 ` Daniel Colascione
@ 2014-03-16 1:00 ` Glenn Morris
2014-03-16 2:30 ` Daniel Colascione
0 siblings, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-16 1:00 UTC (permalink / raw
To: Daniel Colascione; +Cc: emacs-devel, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:52 ` Juanma Barranquero
2014-03-15 11:18 ` Eli Zaretskii
@ 2014-03-16 1:08 ` Glenn Morris
2014-03-16 2:09 ` Juanma Barranquero
2014-03-17 4:43 ` Stephen J. Turnbull
2 siblings, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-16 1:08 UTC (permalink / raw
To: Juanma Barranquero
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 0:32 ` Dmitry Gutov
@ 2014-03-16 1:27 ` Glenn Morris
2014-03-16 5:31 ` Dmitry Gutov
2014-03-16 11:26 ` Nicolas Richard
1 sibling, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-16 1:27 UTC (permalink / raw
To: Dmitry Gutov; +Cc: Eli Zaretskii, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 1:08 ` Glenn Morris
@ 2014-03-16 2:09 ` Juanma Barranquero
2014-03-16 10:02 ` martin rudalics
2014-03-17 16:26 ` Glenn Morris
0 siblings, 2 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-16 2:09 UTC (permalink / raw
To: Glenn Morris
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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?
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 1:00 ` Glenn Morris
@ 2014-03-16 2:30 ` Daniel Colascione
0 siblings, 0 replies; 128+ messages in thread
From: Daniel Colascione @ 2014-03-16 2:30 UTC (permalink / raw
To: Glenn Morris; +Cc: Dmitry Gutov, emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 0:26 ` Dmitry Gutov
@ 2014-03-16 3:49 ` Eli Zaretskii
0 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 3:49 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 0:39 ` Dmitry Gutov
@ 2014-03-16 3:52 ` Eli Zaretskii
2014-03-16 5:25 ` Dmitry Gutov
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 3:52 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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?
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 8:45 ` Eli Zaretskii
2014-03-16 0:32 ` Dmitry Gutov
@ 2014-03-16 3:57 ` Jambunathan K
2014-03-16 16:17 ` Eli Zaretskii
1 sibling, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-16 3:57 UTC (permalink / raw
To: Eli Zaretskii; +Cc: emacs-devel, Dmitry Gutov
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 3:52 ` Eli Zaretskii
@ 2014-03-16 5:25 ` Dmitry Gutov
2014-03-16 16:10 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 5:25 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 1:27 ` Glenn Morris
@ 2014-03-16 5:31 ` Dmitry Gutov
0 siblings, 0 replies; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 5:31 UTC (permalink / raw
To: Glenn Morris; +Cc: Eli Zaretskii, emacs-devel
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?
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 2:09 ` Juanma Barranquero
@ 2014-03-16 10:02 ` martin rudalics
2014-03-17 16:26 ` Glenn Morris
1 sibling, 0 replies; 128+ messages in thread
From: martin rudalics @ 2014-03-16 10:02 UTC (permalink / raw
To: Juanma Barranquero
Cc: Eli Zaretskii, Emacs developers, Stephen Turnbull, Dmitry Gutov
> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 0:32 ` Dmitry Gutov
2014-03-16 1:27 ` Glenn Morris
@ 2014-03-16 11:26 ` Nicolas Richard
1 sibling, 0 replies; 128+ messages in thread
From: Nicolas Richard @ 2014-03-16 11:26 UTC (permalink / raw
To: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 5:25 ` Dmitry Gutov
@ 2014-03-16 16:10 ` Eli Zaretskii
2014-03-16 16:36 ` Dmitry Gutov
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 16:10 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 3:57 ` Jambunathan K
@ 2014-03-16 16:17 ` Eli Zaretskii
2014-03-16 19:17 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 16:17 UTC (permalink / raw
To: Jambunathan K; +Cc: emacs-devel, dgutov
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 16:10 ` Eli Zaretskii
@ 2014-03-16 16:36 ` Dmitry Gutov
2014-03-16 18:20 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Dmitry Gutov @ 2014-03-16 16:36 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 16:36 ` Dmitry Gutov
@ 2014-03-16 18:20 ` Eli Zaretskii
0 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 18:20 UTC (permalink / raw
To: Dmitry Gutov; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 16:17 ` Eli Zaretskii
@ 2014-03-16 19:17 ` Jambunathan K
2014-03-16 20:10 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-16 19:17 UTC (permalink / raw
To: Eli Zaretskii; +Cc: dgutov, emacs-devel
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).
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 19:17 ` Jambunathan K
@ 2014-03-16 20:10 ` Eli Zaretskii
2014-03-17 4:56 ` Stephen J. Turnbull
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-16 20:10 UTC (permalink / raw
To: Jambunathan K; +Cc: dgutov, emacs-devel
> 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).
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 6:30 ` Dmitry Gutov
@ 2014-03-17 4:33 ` Stephen J. Turnbull
0 siblings, 0 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-17 4:33 UTC (permalink / raw
To: Dmitry Gutov; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 10:52 ` Juanma Barranquero
2014-03-15 11:18 ` Eli Zaretskii
2014-03-16 1:08 ` Glenn Morris
@ 2014-03-17 4:43 ` Stephen J. Turnbull
2014-03-17 12:38 ` Juanma Barranquero
2 siblings, 1 reply; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-17 4:43 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Eli Zaretskii, Dmitry Gutov, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 20:10 ` Eli Zaretskii
@ 2014-03-17 4:56 ` Stephen J. Turnbull
2014-03-19 7:57 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-17 4:56 UTC (permalink / raw
To: Eli Zaretskii; +Cc: emacs-devel, Jambunathan K, dgutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 4:43 ` Stephen J. Turnbull
@ 2014-03-17 12:38 ` Juanma Barranquero
2014-03-17 14:31 ` Eli Zaretskii
` (2 more replies)
0 siblings, 3 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-17 12:38 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: Eli Zaretskii, Dmitry Gutov, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 12:38 ` Juanma Barranquero
@ 2014-03-17 14:31 ` Eli Zaretskii
2014-03-18 6:00 ` Stephen J. Turnbull
2014-03-18 16:13 ` Jambunathan K
2 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-17 14:31 UTC (permalink / raw
To: Juanma Barranquero; +Cc: stephen, dgutov, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-15 1:55 ` Stephen J. Turnbull
2014-03-15 2:09 ` Dmitry Gutov
@ 2014-03-17 14:32 ` Stefan
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
` (2 more replies)
1 sibling, 3 replies; 128+ messages in thread
From: Stefan @ 2014-03-17 14:32 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: Dmitry Gutov, emacs-devel
> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
@ 2014-03-17 14:47 Barry OReilly
2014-03-18 17:55 ` Juanma Barranquero
0 siblings, 1 reply; 128+ messages in thread
From: Barry OReilly @ 2014-03-17 14:47 UTC (permalink / raw
To: emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 14:32 ` Stefan
@ 2014-03-17 15:13 ` Lars Magne Ingebrigtsen
2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:43 ` Eli Zaretskii
2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:33 ` Eli Zaretskii
2 siblings, 2 replies; 128+ messages in thread
From: Lars Magne Ingebrigtsen @ 2014-03-17 15:13 UTC (permalink / raw
To: Stefan; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 14:32 ` Stefan
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
@ 2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:52 ` Eli Zaretskii
2014-03-17 16:33 ` Eli Zaretskii
2 siblings, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-17 16:13 UTC (permalink / raw
To: Stefan; +Cc: emacs-devel
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."
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
@ 2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:43 ` Eli Zaretskii
1 sibling, 0 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-17 16:13 UTC (permalink / raw
To: Lars Magne Ingebrigtsen; +Cc: Stefan, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-16 2:09 ` Juanma Barranquero
2014-03-16 10:02 ` martin rudalics
@ 2014-03-17 16:26 ` Glenn Morris
2014-03-17 17:03 ` Juanma Barranquero
1 sibling, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-17 16:26 UTC (permalink / raw
To: Juanma Barranquero
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 14:32 ` Stefan
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
2014-03-17 16:13 ` Glenn Morris
@ 2014-03-17 16:33 ` Eli Zaretskii
2 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-17 16:33 UTC (permalink / raw
To: Stefan; +Cc: stephen, emacs-devel, dgutov
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
2014-03-17 16:13 ` Glenn Morris
@ 2014-03-17 16:43 ` Eli Zaretskii
1 sibling, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-17 16:43 UTC (permalink / raw
To: Lars Magne Ingebrigtsen; +Cc: monnier, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 16:13 ` Glenn Morris
@ 2014-03-17 16:52 ` Eli Zaretskii
0 siblings, 0 replies; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-17 16:52 UTC (permalink / raw
To: Glenn Morris; +Cc: monnier, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 16:26 ` Glenn Morris
@ 2014-03-17 17:03 ` Juanma Barranquero
2014-03-17 17:25 ` Eli Zaretskii
2014-03-18 15:54 ` Glenn Morris
0 siblings, 2 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-17 17:03 UTC (permalink / raw
To: Glenn Morris
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 17:03 ` Juanma Barranquero
@ 2014-03-17 17:25 ` Eli Zaretskii
2014-03-17 17:31 ` Juanma Barranquero
2014-03-18 15:54 ` Glenn Morris
1 sibling, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-17 17:25 UTC (permalink / raw
To: Juanma Barranquero; +Cc: stephen, dgutov, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 17:25 ` Eli Zaretskii
@ 2014-03-17 17:31 ` Juanma Barranquero
0 siblings, 0 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-17 17:31 UTC (permalink / raw
To: Eli Zaretskii; +Cc: Stephen Turnbull, dgutov, Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 12:38 ` Juanma Barranquero
2014-03-17 14:31 ` Eli Zaretskii
@ 2014-03-18 6:00 ` Stephen J. Turnbull
2014-03-18 7:51 ` David Kastrup
2014-03-18 10:56 ` Juanma Barranquero
2014-03-18 16:13 ` Jambunathan K
2 siblings, 2 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-18 6:00 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Eli Zaretskii, Emacs developers, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 6:00 ` Stephen J. Turnbull
@ 2014-03-18 7:51 ` David Kastrup
2014-03-18 12:10 ` John Yates
2014-03-18 10:56 ` Juanma Barranquero
1 sibling, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-18 7:51 UTC (permalink / raw
To: emacs-devel
"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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 6:00 ` Stephen J. Turnbull
2014-03-18 7:51 ` David Kastrup
@ 2014-03-18 10:56 ` Juanma Barranquero
1 sibling, 0 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 10:56 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: Eli Zaretskii, Emacs developers, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 7:51 ` David Kastrup
@ 2014-03-18 12:10 ` John Yates
2014-03-18 12:20 ` David Kastrup
0 siblings, 1 reply; 128+ messages in thread
From: John Yates @ 2014-03-18 12:10 UTC (permalink / raw
To: David Kastrup; +Cc: Emacs developers
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 12:10 ` John Yates
@ 2014-03-18 12:20 ` David Kastrup
2014-03-18 12:52 ` John Yates
0 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-18 12:20 UTC (permalink / raw
To: John Yates; +Cc: Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 12:20 ` David Kastrup
@ 2014-03-18 12:52 ` John Yates
2014-03-18 13:01 ` David Kastrup
0 siblings, 1 reply; 128+ messages in thread
From: John Yates @ 2014-03-18 12:52 UTC (permalink / raw
To: David Kastrup; +Cc: Emacs developers
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 12:52 ` John Yates
@ 2014-03-18 13:01 ` David Kastrup
0 siblings, 0 replies; 128+ messages in thread
From: David Kastrup @ 2014-03-18 13:01 UTC (permalink / raw
To: John Yates; +Cc: Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 17:03 ` Juanma Barranquero
2014-03-17 17:25 ` Eli Zaretskii
@ 2014-03-18 15:54 ` Glenn Morris
2014-03-18 17:07 ` Juanma Barranquero
2014-03-19 4:25 ` Stephen J. Turnbull
1 sibling, 2 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-18 15:54 UTC (permalink / raw
To: Juanma Barranquero
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 12:38 ` Juanma Barranquero
2014-03-17 14:31 ` Eli Zaretskii
2014-03-18 6:00 ` Stephen J. Turnbull
@ 2014-03-18 16:13 ` Jambunathan K
2014-03-18 16:16 ` Juanma Barranquero
2 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-18 16:13 UTC (permalink / raw
To: Juanma Barranquero
Cc: Stephen J. Turnbull, Emacs developers, Eli Zaretskii,
Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 16:13 ` Jambunathan K
@ 2014-03-18 16:16 ` Juanma Barranquero
2014-03-18 17:25 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 16:16 UTC (permalink / raw
To: Jambunathan K
Cc: Stephen J. Turnbull, Emacs developers, Eli Zaretskii,
Dmitry Gutov
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 15:54 ` Glenn Morris
@ 2014-03-18 17:07 ` Juanma Barranquero
2014-03-18 17:21 ` David Kastrup
2014-03-19 4:25 ` Stephen J. Turnbull
1 sibling, 1 reply; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 17:07 UTC (permalink / raw
To: Glenn Morris
Cc: Eli Zaretskii, Dmitry Gutov, Stephen Turnbull, Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 17:07 ` Juanma Barranquero
@ 2014-03-18 17:21 ` David Kastrup
2014-03-18 17:27 ` Juanma Barranquero
0 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-18 17:21 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 16:16 ` Juanma Barranquero
@ 2014-03-18 17:25 ` Jambunathan K
2014-03-18 17:30 ` Juanma Barranquero
0 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-18 17:25 UTC (permalink / raw
To: Juanma Barranquero
Cc: Stephen J. Turnbull, Dmitry Gutov, Eli Zaretskii,
Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 17:21 ` David Kastrup
@ 2014-03-18 17:27 ` Juanma Barranquero
0 siblings, 0 replies; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 17:27 UTC (permalink / raw
To: David Kastrup; +Cc: Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 17:25 ` Jambunathan K
@ 2014-03-18 17:30 ` Juanma Barranquero
2014-03-18 17:51 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 17:30 UTC (permalink / raw
To: Jambunathan K
Cc: Stephen J. Turnbull, Dmitry Gutov, Eli Zaretskii,
Emacs developers
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 17:30 ` Juanma Barranquero
@ 2014-03-18 17:51 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-18 17:51 UTC (permalink / raw
To: Juanma Barranquero
Cc: Stephen J. Turnbull, Emacs developers, Eli Zaretskii,
Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 14:47 Trunk still not open Barry OReilly
@ 2014-03-18 17:55 ` Juanma Barranquero
2014-03-18 19:05 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 17:55 UTC (permalink / raw
To: Jambunathan K
Cc: Stephen J. Turnbull, Emacs developers, Eli Zaretskii,
Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 17:55 ` Juanma Barranquero
@ 2014-03-18 19:05 ` Jambunathan K
2014-03-18 19:24 ` Juanma Barranquero
2014-03-18 19:47 ` David Kastrup
0 siblings, 2 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-18 19:05 UTC (permalink / raw
To: Juanma Barranquero
Cc: Stephen J. Turnbull, Dmitry Gutov, Eli Zaretskii,
Emacs developers
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:05 ` Jambunathan K
@ 2014-03-18 19:24 ` Juanma Barranquero
2014-03-18 19:29 ` Jambunathan K
2014-03-18 19:47 ` David Kastrup
1 sibling, 1 reply; 128+ messages in thread
From: Juanma Barranquero @ 2014-03-18 19:24 UTC (permalink / raw
To: Jambunathan K
Cc: Stephen Turnbull, Dmitry Gutov, Eli Zaretskii, Emacs developers
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:24 ` Juanma Barranquero
@ 2014-03-18 19:29 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-18 19:29 UTC (permalink / raw
To: Juanma Barranquero
Cc: Stephen Turnbull, Emacs developers, Eli Zaretskii, Dmitry Gutov
Juanma Barranquero <lekktu@gmail.com> writes:
> I had agreed to write it
If this were reddit, I will give you gold for saying this.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:05 ` Jambunathan K
2014-03-18 19:24 ` Juanma Barranquero
@ 2014-03-18 19:47 ` David Kastrup
2014-03-18 19:57 ` David Kastrup
` (2 more replies)
1 sibling, 3 replies; 128+ messages in thread
From: David Kastrup @ 2014-03-18 19:47 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:47 ` David Kastrup
@ 2014-03-18 19:57 ` David Kastrup
2014-03-19 15:17 ` Jambunathan K
2014-03-19 15:22 ` Jambunathan K
2 siblings, 0 replies; 128+ messages in thread
From: David Kastrup @ 2014-03-18 19:57 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 19:35 ` Glenn Morris
@ 2014-03-18 20:01 ` joakim
2014-03-19 6:29 ` Glenn Morris
2014-03-19 16:43 ` Stefan
1 sibling, 1 reply; 128+ messages in thread
From: joakim @ 2014-03-18 20:01 UTC (permalink / raw
To: Glenn Morris; +Cc: Stefan Monnier, emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 15:54 ` Glenn Morris
2014-03-18 17:07 ` Juanma Barranquero
@ 2014-03-19 4:25 ` Stephen J. Turnbull
1 sibling, 0 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-19 4:25 UTC (permalink / raw
To: Glenn Morris
Cc: Juanma Barranquero, Eli Zaretskii, Emacs developers, Dmitry Gutov
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:17 ` Jambunathan K
@ 2014-03-19 6:20 ` David Kastrup
2014-03-19 7:24 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: David Kastrup @ 2014-03-19 6:20 UTC (permalink / raw
To: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 20:01 ` joakim
@ 2014-03-19 6:29 ` Glenn Morris
0 siblings, 0 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-19 6:29 UTC (permalink / raw
To: joakim; +Cc: Stefan Monnier, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 6:20 ` David Kastrup
@ 2014-03-19 7:24 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 7:24 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-17 4:56 ` Stephen J. Turnbull
@ 2014-03-19 7:57 ` Jambunathan K
2014-03-19 16:06 ` Eli Zaretskii
0 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 7:57 UTC (permalink / raw
To: Stephen J. Turnbull; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
@ 2014-03-19 14:54 Alexander Poslavsky
2014-03-19 15:18 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Alexander Poslavsky @ 2014-03-19 14:54 UTC (permalink / raw
To: emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:47 ` David Kastrup
2014-03-18 19:57 ` David Kastrup
@ 2014-03-19 15:17 ` Jambunathan K
2014-03-19 6:20 ` David Kastrup
2014-03-19 15:22 ` Jambunathan K
2 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 15:17 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 14:54 Alexander Poslavsky
@ 2014-03-19 15:18 ` Jambunathan K
2014-03-19 15:21 ` Alexander Poslavsky
0 siblings, 1 reply; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 15:18 UTC (permalink / raw
To: Alexander Poslavsky; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:18 ` Jambunathan K
@ 2014-03-19 15:21 ` Alexander Poslavsky
2014-03-19 15:51 ` Glenn Morris
` (2 more replies)
0 siblings, 3 replies; 128+ messages in thread
From: Alexander Poslavsky @ 2014-03-19 15:21 UTC (permalink / raw
Cc: emacs-devel
[-- 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 --]
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-18 19:47 ` David Kastrup
2014-03-18 19:57 ` David Kastrup
2014-03-19 15:17 ` Jambunathan K
@ 2014-03-19 15:22 ` Jambunathan K
2 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 15:22 UTC (permalink / raw
To: David Kastrup; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:21 ` Alexander Poslavsky
@ 2014-03-19 15:51 ` Glenn Morris
2014-03-19 16:23 ` Stephen J. Turnbull
2014-03-19 20:38 ` Jambunathan K
2014-03-19 15:57 ` Bastien
2014-03-19 18:45 ` Stefan
2 siblings, 2 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-19 15:51 UTC (permalink / raw
To: Alexander Poslavsky; +Cc: emacs-devel
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.)
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:21 ` Alexander Poslavsky
2014-03-19 15:51 ` Glenn Morris
@ 2014-03-19 15:57 ` Bastien
2014-03-19 15:59 ` Bastien
2014-03-19 17:15 ` Nicolas Richard
2014-03-19 18:45 ` Stefan
2 siblings, 2 replies; 128+ messages in thread
From: Bastien @ 2014-03-19 15:57 UTC (permalink / raw
To: Alexander Poslavsky; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:57 ` Bastien
@ 2014-03-19 15:59 ` Bastien
2014-03-19 16:13 ` Glenn Morris
2014-03-19 17:15 ` Nicolas Richard
1 sibling, 1 reply; 128+ messages in thread
From: Bastien @ 2014-03-19 15:59 UTC (permalink / raw
To: Alexander Poslavsky; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 7:57 ` Jambunathan K
@ 2014-03-19 16:06 ` Eli Zaretskii
2014-03-19 23:21 ` Jambunathan K
0 siblings, 1 reply; 128+ messages in thread
From: Eli Zaretskii @ 2014-03-19 16:06 UTC (permalink / raw
To: Jambunathan K; +Cc: stephen, emacs-devel
> 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:59 ` Bastien
@ 2014-03-19 16:13 ` Glenn Morris
0 siblings, 0 replies; 128+ messages in thread
From: Glenn Morris @ 2014-03-19 16:13 UTC (permalink / raw
To: Bastien; +Cc: emacs-devel, Alexander Poslavsky
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:51 ` Glenn Morris
@ 2014-03-19 16:23 ` Stephen J. Turnbull
2014-03-19 20:38 ` Jambunathan K
1 sibling, 0 replies; 128+ messages in thread
From: Stephen J. Turnbull @ 2014-03-19 16:23 UTC (permalink / raw
To: Glenn Morris; +Cc: emacs-devel, Alexander Poslavsky
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!)
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-14 19:35 ` Glenn Morris
2014-03-18 20:01 ` joakim
@ 2014-03-19 16:43 ` Stefan
1 sibling, 0 replies; 128+ messages in thread
From: Stefan @ 2014-03-19 16:43 UTC (permalink / raw
To: Glenn Morris; +Cc: Stephen J. Turnbull, emacs-devel, Dmitry Gutov
> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:57 ` Bastien
2014-03-19 15:59 ` Bastien
@ 2014-03-19 17:15 ` Nicolas Richard
2014-03-19 23:38 ` Bastien
1 sibling, 1 reply; 128+ messages in thread
From: Nicolas Richard @ 2014-03-19 17:15 UTC (permalink / raw
To: emacs-devel
[-- 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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:21 ` Alexander Poslavsky
2014-03-19 15:51 ` Glenn Morris
2014-03-19 15:57 ` Bastien
@ 2014-03-19 18:45 ` Stefan
2014-03-19 20:01 ` Glenn Morris
2014-03-19 21:21 ` Paul Eggert
2 siblings, 2 replies; 128+ messages in thread
From: Stefan @ 2014-03-19 18:45 UTC (permalink / raw
To: Alexander Poslavsky; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 18:45 ` Stefan
@ 2014-03-19 20:01 ` Glenn Morris
2014-03-20 1:22 ` Stefan
2014-03-19 21:21 ` Paul Eggert
1 sibling, 1 reply; 128+ messages in thread
From: Glenn Morris @ 2014-03-19 20:01 UTC (permalink / raw
To: Stefan; +Cc: emacs-devel, Alexander Poslavsky
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...)
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 15:51 ` Glenn Morris
2014-03-19 16:23 ` Stephen J. Turnbull
@ 2014-03-19 20:38 ` Jambunathan K
1 sibling, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 20:38 UTC (permalink / raw
To: Glenn Morris; +Cc: emacs-devel, Alexander Poslavsky
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 18:45 ` Stefan
2014-03-19 20:01 ` Glenn Morris
@ 2014-03-19 21:21 ` Paul Eggert
2014-03-20 1:24 ` Stefan
1 sibling, 1 reply; 128+ messages in thread
From: Paul Eggert @ 2014-03-19 21:21 UTC (permalink / raw
To: Stefan; +Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 16:06 ` Eli Zaretskii
@ 2014-03-19 23:21 ` Jambunathan K
0 siblings, 0 replies; 128+ messages in thread
From: Jambunathan K @ 2014-03-19 23:21 UTC (permalink / raw
To: Eli Zaretskii; +Cc: stephen, emacs-devel
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.
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 17:15 ` Nicolas Richard
@ 2014-03-19 23:38 ` Bastien
0 siblings, 0 replies; 128+ messages in thread
From: Bastien @ 2014-03-19 23:38 UTC (permalink / raw
To: Nicolas Richard; +Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 20:01 ` Glenn Morris
@ 2014-03-20 1:22 ` Stefan
0 siblings, 0 replies; 128+ messages in thread
From: Stefan @ 2014-03-20 1:22 UTC (permalink / raw
To: Glenn Morris; +Cc: emacs-devel, Alexander Poslavsky
> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
* Re: Trunk still not open
2014-03-19 21:21 ` Paul Eggert
@ 2014-03-20 1:24 ` Stefan
0 siblings, 0 replies; 128+ messages in thread
From: Stefan @ 2014-03-20 1:24 UTC (permalink / raw
To: Paul Eggert; +Cc: emacs-devel
>> 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
^ permalink raw reply [flat|nested] 128+ messages in thread
end of thread, other threads:[~2014-03-20 1:24 UTC | newest]
Thread overview: 128+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-03-17 14:47 Trunk still not open Barry OReilly
2014-03-18 17:55 ` Juanma Barranquero
2014-03-18 19:05 ` Jambunathan K
2014-03-18 19:24 ` Juanma Barranquero
2014-03-18 19:29 ` Jambunathan K
2014-03-18 19:47 ` David Kastrup
2014-03-18 19:57 ` David Kastrup
2014-03-19 15:17 ` Jambunathan K
2014-03-19 6:20 ` David Kastrup
2014-03-19 7:24 ` Jambunathan K
2014-03-19 15:22 ` Jambunathan K
-- strict thread matches above, loose matches on Subject: below --
2014-03-19 14:54 Alexander Poslavsky
2014-03-19 15:18 ` Jambunathan K
2014-03-19 15:21 ` Alexander Poslavsky
2014-03-19 15:51 ` Glenn Morris
2014-03-19 16:23 ` Stephen J. Turnbull
2014-03-19 20:38 ` Jambunathan K
2014-03-19 15:57 ` Bastien
2014-03-19 15:59 ` Bastien
2014-03-19 16:13 ` Glenn Morris
2014-03-19 17:15 ` Nicolas Richard
2014-03-19 23:38 ` Bastien
2014-03-19 18:45 ` Stefan
2014-03-19 20:01 ` Glenn Morris
2014-03-20 1:22 ` Stefan
2014-03-19 21:21 ` Paul Eggert
2014-03-20 1:24 ` Stefan
2014-02-27 5:00 Stefan Monnier
2014-03-13 20:55 ` Glenn Morris
2014-03-14 7:58 ` Eli Zaretskii
2014-03-14 9:29 ` Stephen J. Turnbull
2014-03-14 9:35 ` David Kastrup
2014-03-14 9:47 ` Eli Zaretskii
2014-03-14 10:02 ` David Kastrup
2014-03-14 10:23 ` Eli Zaretskii
2014-03-14 10:40 ` David Kastrup
2014-03-14 11:02 ` Eli Zaretskii
2014-03-14 9:43 ` Eli Zaretskii
2014-03-14 9:55 ` Bastien
2014-03-14 15:16 ` Stephen J. Turnbull
2014-03-14 11:42 ` Eric S. Raymond
2014-03-15 9:13 ` Jambunathan K
2014-03-14 12:34 ` Dmitry Gutov
2014-03-14 13:38 ` Stefan Monnier
2014-03-14 19:35 ` Glenn Morris
2014-03-18 20:01 ` joakim
2014-03-19 6:29 ` Glenn Morris
2014-03-19 16:43 ` Stefan
2014-03-14 14:34 ` Stephen J. Turnbull
2014-03-14 14:57 ` Dmitry Gutov
2014-03-14 15:29 ` Eli Zaretskii
2014-03-15 6:22 ` Dmitry Gutov
2014-03-15 9:02 ` Eli Zaretskii
2014-03-16 0:26 ` Dmitry Gutov
2014-03-16 3:49 ` Eli Zaretskii
2014-03-14 15:39 ` Stephen J. Turnbull
2014-03-15 6:30 ` Dmitry Gutov
2014-03-17 4:33 ` Stephen J. Turnbull
2014-03-14 19:31 ` Glenn Morris
2014-03-14 20:08 ` Daniel Colascione
2014-03-16 1:00 ` Glenn Morris
2014-03-16 2:30 ` Daniel Colascione
2014-03-15 1:55 ` Stephen J. Turnbull
2014-03-15 2:09 ` Dmitry Gutov
2014-03-15 8:22 ` Eli Zaretskii
2014-03-15 10:52 ` Juanma Barranquero
2014-03-15 11:18 ` Eli Zaretskii
2014-03-15 11:28 ` Juanma Barranquero
2014-03-16 1:08 ` Glenn Morris
2014-03-16 2:09 ` Juanma Barranquero
2014-03-16 10:02 ` martin rudalics
2014-03-17 16:26 ` Glenn Morris
2014-03-17 17:03 ` Juanma Barranquero
2014-03-17 17:25 ` Eli Zaretskii
2014-03-17 17:31 ` Juanma Barranquero
2014-03-18 15:54 ` Glenn Morris
2014-03-18 17:07 ` Juanma Barranquero
2014-03-18 17:21 ` David Kastrup
2014-03-18 17:27 ` Juanma Barranquero
2014-03-19 4:25 ` Stephen J. Turnbull
2014-03-17 4:43 ` Stephen J. Turnbull
2014-03-17 12:38 ` Juanma Barranquero
2014-03-17 14:31 ` Eli Zaretskii
2014-03-18 6:00 ` Stephen J. Turnbull
2014-03-18 7:51 ` David Kastrup
2014-03-18 12:10 ` John Yates
2014-03-18 12:20 ` David Kastrup
2014-03-18 12:52 ` John Yates
2014-03-18 13:01 ` David Kastrup
2014-03-18 10:56 ` Juanma Barranquero
2014-03-18 16:13 ` Jambunathan K
2014-03-18 16:16 ` Juanma Barranquero
2014-03-18 17:25 ` Jambunathan K
2014-03-18 17:30 ` Juanma Barranquero
2014-03-18 17:51 ` Jambunathan K
2014-03-16 0:39 ` Dmitry Gutov
2014-03-16 3:52 ` Eli Zaretskii
2014-03-16 5:25 ` Dmitry Gutov
2014-03-16 16:10 ` Eli Zaretskii
2014-03-16 16:36 ` Dmitry Gutov
2014-03-16 18:20 ` Eli Zaretskii
2014-03-15 10:02 ` Jambunathan K
2014-03-15 10:19 ` David Kastrup
2014-03-15 11:01 ` Jambunathan K
2014-03-15 11:10 ` Eli Zaretskii
2014-03-17 14:32 ` Stefan
2014-03-17 15:13 ` Lars Magne Ingebrigtsen
2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:43 ` Eli Zaretskii
2014-03-17 16:13 ` Glenn Morris
2014-03-17 16:52 ` Eli Zaretskii
2014-03-17 16:33 ` Eli Zaretskii
2014-03-15 3:22 ` Dmitry Gutov
2014-03-15 7:10 ` Thien-Thi Nguyen
2014-03-15 9:02 ` David Kastrup
2014-03-15 8:45 ` Eli Zaretskii
2014-03-16 0:32 ` Dmitry Gutov
2014-03-16 1:27 ` Glenn Morris
2014-03-16 5:31 ` Dmitry Gutov
2014-03-16 11:26 ` Nicolas Richard
2014-03-16 3:57 ` Jambunathan K
2014-03-16 16:17 ` Eli Zaretskii
2014-03-16 19:17 ` Jambunathan K
2014-03-16 20:10 ` Eli Zaretskii
2014-03-17 4:56 ` Stephen J. Turnbull
2014-03-19 7:57 ` Jambunathan K
2014-03-19 16:06 ` Eli Zaretskii
2014-03-19 23:21 ` Jambunathan K
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.