Subject: bug#29888: 26.0; Emacs manual indexes

From: Drew Adams <[email-masked]>
Date: Thu, 28 Dec 2017 19:39:21 -0800 (PST)

1. In `Command Index':

Why these "mode, *" entries?  Please consider removing these or adding
(many) others.

 * mode, Glasses:                         MixedCase Words.     (line  12)
 * mode, Org:                             Org Mode.            (line   6)
 * mode, thumbs:                          File Conveniences.   (line  60)

2. In `Concept Index':

There are lots of "mode, *" entries?  Why only these?  Is this supposed
to be complete (all modes mentioned in the manual)?  It doesn't even
include basic and longstanding modes such as Dired.  What's the purpose
of these entries (why these)?

3. In node `Top', the indexes are listed, with descriptions.

 * Key Index::           An item for each standard Emacs key sequence.
 * Option Index::        An item for every command-line option.
 * Command Index::       An item for each command name.
 * Variable Index::      An item for each documented variable.
 * Concept Index::       An item for each concept.

Each of the descriptions says that the relevant index contains an
(index) item "for each" whatever.  Nope.  It should say that it contains
an item for the whatevers that are mentioned in the Emacs manual.

What's more, the entry in `Top' for `Variable Index', unlike the others,
adds "documented" to the description: "for each documented variable".
That confuses things even more.  It really gives the impression that, at
least for variables, each Emacs variable that has a doc string has an
entry in this index.

It would be much clearer to say only that the given index has entries
for whatevers:

 * Key Index::           Standard Emacs key sequences.
 * Option Index::        Command-line options.
 * Command Index::       Commands.
 * Variable Index::      Variables.
 * Concept Index::      Concepts.

4. In the Concept index:

a. There are some entries that end with `<1>'.

This convention should be explained (e.g. at the top).  A short sentence
should suffice.

b. Some entries are essentially duplicated, for no good reason.  E.g.:
 
 * 7z:                                    File Archives.       (line  38)
 * '7z':                                  File Archives.       (line  38)

 * 'Alt' key (MS-Windows):                Windows Keyboard.    (line  17)
 * 'Alt' key invokes menu (Windows):      Windows Keyboard.    (line  79)

 * arc:                                   File Archives.       (line  38)
 * 'arc':                                 File Archives.       (line  38)

 * case in completion:                    Completion Options.  (line   6)
 * case-sensitivity and completion:       Completion Options.  (line   6)
 * cvs:                                   VC Directory Mode.   (line  24)
 * CVS:                                   Version Control Systems.
                                                               (line  25)
 * echo area:                             Echo Area.           (line   6)
 * echo area message:                     Echo Area.           (line  19)
 * echoing:                               Echo Area.           (line   9)

 * Emacs Lisp package:                    Packages.            (line   6)
 * Emacs Lisp package archive:            Packages.            (line   6)

c. Why are all of the files in quotes except `~/.emacs'?

 * '_emacs' init file, MS-Windows:        Windows HOME.        (line  43)
 * ~/.emacs file:                         Init File.           (line   6)
 * '~/.emacs.d/gtkrc' file:               GTK resources.       (line   6)
 * '~/.gtkrc-2.0' file:                   GTK resources.       (line   6)
 * '~/.Xdefaults' file:                   Resources.           (line   6)
 * '~/.Xresources' file:                  Resources.           (line   6)

d. Some of the entries are not good, and seem arbitrary.  A bad verb is
one problem.  Examples:

 * adding to the kill ring in Dired:      Misc Dired Features. (line  19)
 * adjust buffer face height:             Text Scale.          (line   6)
 * aggressive scrolling:                  Auto Scrolling.      (line  29)
 * attached frame (of speedbar):          Speedbar.            (line   6)
 * boredom:                               Amusements.          (line   6)
 * buffer definitions index:              Imenu.               (line   6)
 * buttons at buffer position:            Editing Format Info. (line  20)
 * compressing files (in Dired):          Operating on Files.  (line 106)
 * compression:                           Compressed Files.    (line   6)
 * converting text to upper or lower case: Case.               (line  20)
 * drastic changes:                       Reverting.           (line   6)
 * emergency escape:                      Emergency Escape.    (line   6)

e. Hyphenation is inconsistent or wrong.  Examples:

 * Auto Fill mode:                        Auto Fill.           (line   6)
 * Auto Save mode:                        Auto Save.           (line   6)
 * Auto-Revert mode:                      Reverting.           (line  37)

 * auto-save for remote files:            Auto Save Files.     (line  26)
 * autoload:                              Lisp Libraries.      (line  62)

 * button down events:                    Mouse Buttons.       (line   6)

f. Some entries are not specific enough.  E.g.:

 * binding:                               Commands.            (line   6)

g. Some entries don't seem to correspond to their targets.  E.g.:

 * blank lines in programs:               Multi-Line Comments. (line   6)

I looked only at entries from A to E.  Any improvements you want to make
are OK by me.  If you make none, that's OK too (feel free to close).

In GNU Emacs 26.0.90 (build 3, x86_64-w64-mingw32)
 of 2017-10-13
Repository revision: 906224eba147bdfc0514090064e8e8f53160f1d4
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''