[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#29888: 26.0; Emacs manual indexes
From: |
Eli Zaretskii |
Subject: |
bug#29888: 26.0; Emacs manual indexes |
Date: |
Fri, 29 Dec 2017 18:13:14 +0200 |
> 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.