bug#29888: 26.0; Emacs manual indexes

[Eli Zaretskii]

> Date: Thu, 28 Dec 2017 19:39:21 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>

Thanks, I fixed most of these issues.

> 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)

They should be in Concept Index.

> 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)?

The purpose is to support "i mode TAB".  I don't think Dired belongs
here, because it's primarily a feature, its being a mode is very
secondary.  For the others, I guess the intent was to do this for
modes whose names can be otherwise encountered in many other index
entries.

> 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.

I ma a small change there, but by and large, I don't think this is too
important, as people will rarely look at the descriptions of "Index"
nodes.  And menus are not in the printed manual.

> 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.

It's not an Emacs convention, it's a Texinfo convention.

Most of such index entries are bugs/typos, or should be disambiguated
by qualifying them by their context.  Which is what I did.


> b. Some entries are essentially duplicated, for no good reason.  E.g.:

Some of those were bugs, but most are not duplications, IMO.

> 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)

They are not in quotes in my manual, and not in the official pretest
zip archive.  Not sure how you got them.

> 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)

I don't see what's wrong with these.

> 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)

I fixed "Auto-Revert Mode" and "button down events", the rest seem
okay.

> 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)

Didn't see any problems with those.

> 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).

Thanks.