From: Jambunathan K <kjambunathan@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org, Dmitry Gutov <dgutov@yandex.ru>
Subject: Re: Trunk still not open
Date: Sun, 16 Mar 2014 09:27:08 +0530 [thread overview]
Message-ID: <87wqfukd7v.fsf@gmail.com> (raw)
In-Reply-To: 834n2zdf3s.fsf@gnu.org
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
next prev parent reply other threads:[~2014-03-16 3:57 UTC|newest]
Thread overview: 128+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-02-27 5:00 Trunk still not open 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 [this message]
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
-- strict thread matches above, loose matches on Subject: below --
2014-03-17 14:47 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
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wqfukd7v.fsf@gmail.com \
--to=kjambunathan@gmail.com \
--cc=dgutov@yandex.ru \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.