emacs/admin/notes/documentation

-*- outline -*-

Some documentation tips culled from emacs-devel postings.


** Manual indices

https://lists.gnu.org/r/emacs-devel/2008-10/msg00400.html

For example, this text:

    @vindex x-gtk-show-hidden-files
    @vindex x-gtk-file-dialog-help-text
      When Emacs is compiled with GTK+ support, it uses the GTK+ ``file
    chooser'' dialog.  Emacs adds an additional toggle button to this
    dialog, which you can use to enable or disable the display of hidden
    files (files starting with a dot) in that dialog.  If you want this
    toggle to be activated by default, change the variable
    @code{x-gtk-show-hidden-files} to @code{t}.  In addition, Emacs adds
    help text to the GTK+ file chooser dialog; to disable this help text,
    change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.

has index entries for the variables it describes, which is good, but
what if a user looks for this information without knowing the names of
these variables?  For those, I added these two concept index entries:

    @cindex hidden files, in GTK+ file chooser
    @cindex help text, in GTK+ file chooser

Thus, if a user types "i hidden files TAB" in Info, she will see the
first entry, and so if she types "i file chooser RET".  See why it is
better?

The way to come up with useful index entries is to put yourself in the
shoes of someone who looks for the information, and think about words
and phrases you'd use to find it.

One other rule for good indexing is not to have several index entries
that begin with the same substring and point to the same page or
screenful (i.e. to places that are close to one another).  Here's a
fictitious example of such redundant entries:

  @cindex foobar, how to use
  @cindex foobar rules

  Either leave only one of these, e.g. just "@cindex foobar", or
combine them into a single entry, e.g.:

  @cindex foobar, rules and usage


** Point is a proper name

https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html

In Emacs tradition, we treat "point" as a proper name when it refers
to the current editing location.  It should not have an article.

Thus, it is incorrect to write, "The point does not move".  It should
be, "Point does not move".

If you see "the point" anywhere in Emacs documentation or comments,
referring to point, please fix it.


** Don't use passive verbs

https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html

Documentation is clearer if it avoids the passive voice whenever
possible.  For example, rather than saying "Point does not move", say
"This does not move point".  If you come across passive verbs in Emacs
documentation or comments, please see if it is possible to make the
text shorter and clearer using the active voice.  Usually that does
make an improvement.  The explicit subject required by the active voice
often provides important information which makes the text clearer, too.


** Antinews nodes

*** Why Antinews is useful

https://lists.gnu.org/r/emacs-devel/2008-11/msg00893.html

The usefulness of Antinews is to help people who buy the printed
manual and are still using the previous Emacs version.  That's why we
focus on the (eliminated) behavior of the old version rather than on
the new features.

Of course, we try to make it amusing as well.

*** Don't mention in Antinews too many features absent in old versions

https://lists.gnu.org/r/emacs-devel/2008-11/msg01054.html

Since the purpose of Antinews is to help people use the previous Emacs
version, there is usually no need to mention features that are simply
absent in that version.  That situation will be clear enough to users
without help from the manual.

For instance, this

    @item
    Emacs can no longer be started as a daemon.  We decided that having an
    Emacs sitting silently in the background with no visual manifestation
    anywhere in sight is too confusing.

may not need mentioning, because --daemon will give an error message
saying it's not implemented, and other cases aren't affected.

The kind of change for which the user really needs help from Antinews
is where a feature works _differently_ in the previous version.
In those cases, the user might have trouble figuring out how to use
the old version without some sort of help.


** To indicate possession, write Emacs's rather than Emacs'.
https://lists.gnu.org/r/emacs-devel/2012-02/msg00649.html


** etc/NEWS style rules

Any change that matters to end-users should have an entry in etc/NEWS.
This is not intended as reference of design decisions or interfaces.

*** Each NEWS entry starts with a heading that summarizes the entry.
It takes just one line, and will finish with a period.  Section
headings, which are one level up from entry headings, are not full
sentences.  First-level headings are broad categories, and the other
section headings are the names of Emacs features.  Don't use Lisp
symbols for section headings.  E.g. "Random mode" not "'random-mode'".

*** All new, changed or obsoleted user options and commands are documented.
Document the default value or the argument list, respectively.

If a user option or command is obsoleted or changes the default value /
argument list, document how to keep the previous behavior.

Document further new, changed or obsoleted variables and functions, if
they are relevant for package authors.

*** Lisp symbols, Lisp forms and and key sequences are quoted 'like-this'.
This results in clickable Lisp symbols when the NEWS file is visited via
'view-emacs-news' ('C-h n').  Also single key names or keywords must
follow this rule, like 'TAB' or ':type'.  Exception: the symbols t and
nil are not quoted.

Arguments of a function are written in capital letters LIKE-THIS, and they
are not quoted.

If Lisp forms are written in a line of its own, they are not quoted.
Separate these lines from the previous and following text by an empty
line.  Indent them with a width of 4 spaces.

*** File names, buffer names, process names are strings.
Quote them with quotation marks "like this".  Exception: Lisp file names
like subr.el, which are not quoted.

*** External program names are quoted with quotation marks like "this".

*** Manuals (Info pages) are referenced like "(elisp) Documentation Tips".

*** Prior pushing your changes, check the result.
Call 'emacs-news-view-mode'.  Lisp symbols and Info manual links shall
be decorated, and clicking on them shall lead to the respective Help
buffer or Info node.