"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/admin/notes/documentation" (23 Apr 2018, 4359 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "documentation": 25.3_vs_26.1.

    1 -*- outline -*-
    2 
    3 Some documentation tips culled from emacs-devel postings.
    4 
    5 
    6 ** Manual indices
    7 
    8 https://lists.gnu.org/r/emacs-devel/2008-10/msg00400.html
    9 
   10 For example, this text:
   11 
   12     @vindex x-gtk-show-hidden-files
   13     @vindex x-gtk-file-dialog-help-text
   14       When Emacs is compiled with GTK+ support, it uses the GTK+ ``file
   15     chooser'' dialog.  Emacs adds an additional toggle button to this
   16     dialog, which you can use to enable or disable the display of hidden
   17     files (files starting with a dot) in that dialog.  If you want this
   18     toggle to be activated by default, change the variable
   19     @code{x-gtk-show-hidden-files} to @code{t}.  In addition, Emacs adds
   20     help text to the GTK+ file chooser dialog; to disable this help text,
   21     change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.
   22 
   23 has index entries for the variables it describes, which is good, but
   24 what if a user looks for this information without knowing the names of
   25 these variables?  For those, I added these two concept index entries:
   26 
   27     @cindex hidden files, in GTK+ file chooser
   28     @cindex help text, in GTK+ file chooser
   29 
   30 Thus, if a user types "i hidden files TAB" in Info, she will see the
   31 first entry, and so if she types "i file chooser RET".  See why it is
   32 better?
   33 
   34 The way to come up with useful index entries is to put yourself in the
   35 shoes of someone who looks for the information, and think about words
   36 and phrases you'd use to find it.
   37 
   38 One other rule for good indexing is not to have several index entries
   39 that begin with the same substring and point to the same page or
   40 screenful (i.e. to places that are close to one another).  Here's a
   41 fictitious example of such redundant entries:
   42 
   43   @cindex foobar, how to use
   44   @cindex foobar rules
   45 
   46   Either leave only one of these, e.g. just "@cindex foobar", or
   47 combine them into a single entry, e.g.:
   48 
   49   @cindex foobar, rules and usage
   50 
   51 
   52 ** Point is a proper name
   53 
   54 https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html
   55 
   56 In Emacs tradition, we treat "point" as a proper name when it refers
   57 to the current editing location. It should not have an article.
   58 
   59 Thus, it is incorrect to write, "The point does not move". It should
   60 be, "Point does not move".
   61 
   62 If you see "the point" anywhere in Emacs documentation or comments,
   63 referring to point, please fix it.
   64 
   65 
   66 ** Don't use passive verbs
   67 
   68 https://lists.gnu.org/r/emacs-devel/2008-10/msg00414.html
   69 
   70 Documentation is clearer if it avoids the passive voice whenever
   71 possible.  For example, rather than saying "Point does not move", say
   72 "This does not move point".  If you come across passive verbs in Emacs
   73 documentation or comments, please see if it is possible to make the
   74 text shorter and clearer using the active voice.  Usually that does
   75 make an improvement.  The explicit subject required by the active voice
   76 often provides important information which makes the text clearer, too.
   77 
   78 
   79 ** Antinews nodes
   80 
   81 *** Why Antinews is useful
   82 
   83 https://lists.gnu.org/r/emacs-devel/2008-11/msg00893.html
   84 
   85 The usefulness of Antinews is to help people who buy the printed
   86 manual and are still using the previous Emacs version.  That's why we
   87 focus on the (eliminated) behavior of the old version rather than on
   88 the new features.
   89 
   90 Of course, we try to make it amusing as well.
   91 
   92 *** Don't mention in Antinews too many features absent in old versions
   93 
   94 https://lists.gnu.org/r/emacs-devel/2008-11/msg01054.html
   95 
   96 Since the purpose of Antinews is to help people use the previous Emacs
   97 version, there is usually no need to mention features that are simply
   98 absent in that version.  That situation will be clear enough to users
   99 without help from the manual.
  100 
  101 For instance, this
  102 
  103     @item
  104     Emacs can no longer be started as a daemon.  We decided that having an
  105     Emacs sitting silently in the background with no visual manifestation
  106     anywhere in sight is too confusing.
  107 
  108 may not need mentioning, because --daemon will give an error message
  109 saying it's not implemented, and other cases aren't affected.
  110 
  111 The kind of change for which the user really needs help from Antinews
  112 is where a feature works _differently_ in the previous version.
  113 In those cases, the user might have trouble figuring out how to use
  114 the old version without some sort of help.
  115 
  116 ** To indicate possession, write Emacs's rather than Emacs'.
  117 https://lists.gnu.org/r/emacs-devel/2012-02/msg00649.html