--- Begin Message ---
|
Subject: |
26.0; Emacs manual indexes |
|
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''
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: 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 <address@hidden>
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.
--- End Message ---