Re: Trunk still not open

[Jambunathan K]

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

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

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

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

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


Eli Zaretskii <address@hidden> 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