standard error not in Elisp manual index

standard error not in Elisp manual index

[Drew Adams]

emacs -Q
C-h i, pick Elisp manual
i standard error => "No `standard error' in index

But:
s  standard error takes you to the top-level menu item Standard Errors

Please add `standard error' to the index. There might be other top-level
menu terms that should also be in the index.

Also, shouldn't the history of input to `i' be added to the search history,
so you could immediately try `s M-p' to get `s standard error'?

The two histories appear to be independent, but I'd think that entries
searched for in the index would also be useful in the search history.

Re: standard error not in Elisp manual index

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 23 Mar 2007 16:22:38 -0700
> 
> emacs -Q
> C-h i, pick Elisp manual
> i standard error => "No `standard error' in index
> 
> But:
> s  standard error takes you to the top-level menu item Standard Errors
> 
> Please add `standard error' to the index.

Thanks, I added "standard errors".

> There might be other top-level menu terms that should also be in the
> index.

Yes, there might, so please tell if you find any.

RE: standard error not in Elisp manual index

[Drew Adams]

> > There might be other top-level menu terms that should also be in the
> > index.
>
> Yes, there might, so please tell if you find any.

1. These terms are not in the index (at least in these forms):

byte compile, byte compilation
customizing
back up (two words)
auto save (two words)
multi-byte
utf-8
abbreviating
user id
system type
gpl
license
general public license
gnu public license
standard keymap(s)
standard buffer-local variable
arithmetic function
cons cell
lookup table, lookup-table
sexp (not found as such)
evaluating (not found as such)
read file
read input
auto-save file
window manager
mouse pointer (not found as such)
cursor (not found as such - e.g. node Window Point)
split(ting) character
abbrev mode (but abbrev-mode is found)
abbrev expansion
picture (mode)
record(ing) input
kill emacs
quit emacs
exit emacs
get out
kill buffer (but kill-buffer is found)
cut (should go to node about killing text)
paste (should go to node about yanking)
copy text (should go to node about kill-ring-save)
x11
abstract display
image cache
font set (but fontset is found)
scroll bar
byte pack(ing)
decode output, decoding output
accept(ing) output
network server
delete process (but deleting process found)
shell argument
(a)synchronous process
replace match, replacing match
search (and) replace
query replace
md 5 (but md5 is found)
delete text (but delete and deletion found)
frame parameter
window parameter
position parameter
size parameter
initial frame
default frame
default face
track mouse
minibuffer frame
frame title
multiple display(s)
window hook
resize window
vertical scroll
window start
display(ing) buffer
cycle window (+ing)
select window, choose window (+ing)
delete window (+ing)
split window (+ing)
unique
visit file (+ing)
create directory (+ing)
delete directory (+ing)
lock file (+ing)
write file (+ing)
read(ing) file
save buffer (+ing)
describe character (+ing)
substitute key (+ing)
access(ing) documentation
font(-)lock multiline
syntactic font(-)lock
font(-)lock face
font(-)lock level
keymap minor mode
auto major mode
major mode convention (but works for minor mode convention)
font-lock(-)mode (but font lock mode works)
mode(-)line format
keyboard menu
mouse menu
define menu (but defining menu works)
translation keymap
lookup key, look(-)up key (but key lookup works)
search(ing) keymap
inherit keymap
format keymap
event input (but input event works)
read(ing) event
access(ing) event
button event
control g
minibuffer completion
recursive minibuffer
yes no
output variable
print variable
search library, find library
autoloading (but autoload works)
define type
type keyword
splice, list splice
customize type (but customization type works)
define variable
define option
define group
customize keyword
indent macro
argument list
frame(-)local variable
file-local variable (but file local variable works)
variable alias
buffer local variable (but buffer-local variable works)
signal error
handle error
iterate (but iteration works)
create symbol, creating symbol
define symbol, defining symbol
create hash, creating hash
define hash, defining hash
list order
modify list
numeric conversion, number conversion, convert number
number predicate
numeric comparison, compare number(s)


2. As a rule of thumb, it would be good for each of the top-level menu items
to be the first or near the first hit for the keywords in that item name, or
keywords closely associated with that item name.

For example, the node addressed by menu item _Functions_ should be among the
first hits if you use `i function'. As it is now, that node is accessed only
after a hundred or so uses of `,' after `i function'. Consider doing this
for these top-level menu items:

Introduction (convention)
Numbers (number, arithmetic)
Strings and Characters (string, character)
Lists (cons)
Sequences Arrays Vectors (array, vector), but sequence works
Hash Tables (hash), but hash table works
Evaluation (eval, Lisp expression, sexp, value)
Functions (function)
Macros (macro)
Control Structures (control, conditional, condition, loop, nonlocal exit)
Customization (customize, customization)
Loading (load, read), but loading works
Byte Compilation (compile, compiling), but compilation works
Advising Functions (advice, advise), but advising works
Debugging (debug, debugger, debugging)
Read and Print (read, print, reading, printing, write, writing)
Minibuffers (read input, reading input)
Keymaps (binding, key binding, key sequence)
Modes (major mode, minor mode)
Documentation (documentation, help, doc string)
File (file, file access)
Backups and Auto-Saving (backup, auto-save)
Windows (window)
Positions (position, point, mark, motion, cursor)
Markers (marker)
Non-ASCII Characters (ascii, character set, coding system, input method,
locale)
Searching and Matching (search, match, matching, regexp, regular
expression), but searching works
Syntax Tables (syntax, parse, category), but syntax table and parsing work
Abbrevs (abbreviation), but abbrev works
Display (display, screen, displaying)
System Interface (system, interface, user, id, environment, environment
variable)
Tips (tip, coding, convention)
GNU Emacs Internals (build, building, dump, dumping)
Standard Errors (error)
Standard Buffer-Local Variables (buffer-local variable, buffer-local, local)
Standard Hooks (hook)
Index (index)


3. These terms have no entries for the nodes in parens:

memory (Memory Usage)
documentation (Documentation Tips)
warning (Warning Tips)
key binding (Key Binding Conventinos)
run time (Processor Run Time)
get out, exit, quit (Getting Out)
display message (Displaying Messages)
truncation (Truncation)
force redisplay (Forcing Redisplay), but forcing redisplay works
text property (Text Properties)
deleting (Deletion)
inserting (Insertion)
near point (Near Point)
region (Region) - there is an entry, but it is far from the first
move marker, moving marker (Moving Markers)
skip character (Skipping Characters), but skipping character works
buffer end (Buffer End Motion)
word motion, move word (Word Motion)
character motion, move character (Character Motion)
position parameter (Position Parameters)
size parameter (Size Parameters)
layout parameter (Layout Parameters)
track(ing) mouse (Mouse Tracking)
raise frame, lower frame, frame stack, frame order (Raising and Lowering)
find frame (Finding All Frames)
frame title (Frame Titles)
multiple display(s) (Multiple Displays)
window hook (Window Hooks)
resize window, resizing window (Resizing Windows)
vertical scroll (Vertical Scrolling), but horizontal scroll is found
window start (Window Start)
choose window, choosing window (Choosing Window)
display(ing) buffer (Displaying Buffers)
window cycle (Cyclic Window Ordering)
select window, choose window (Selecting Windows)
delete window (+ing) (Deleting Windows)
split window (+ing) (Splitting Windows)
buffer gap (Buffer Gap)
refresh, reload (Reverting)
complete file(-name or name), completing same (File-Name Completion)
unique (Unique File Names)
expand(ing) file name (File Name Expansion)
file(-)name component (File Name Components)
true name (Truenames), but truename works
file type (Kinds of Files)
visit file (Visiting Functions)
convert format (Format Conversion)
create directory, delete directory (+ing) (Create/Delete Dirs)
file information (Information about Files)
lock(ing) file (File Locks)
write file, writing file (Writing to Files)
read(ing) file (Reading from Files)
save buffer (+ing) (Saving Buffers)
describe character (+ing) (Describing Characters)
substitute key (+ing) (Keys in Documentation)
access(ing) documentation (Accessing Documentation)
font(-)lock multiline (Font Lock Multiline, Multiline Font Lock) - BTW, why
have two nodes with such similar names?
syntactic font(-)lock (Syntactic Font Lock)
font(-)lock face (Faces for Font Lock)
font(-)lock level (Levels of Font Lock)
keymap minor mode (Keymaps and Minor Modes)
mode hook (Mode Hooks)
auto major mode (Auto Major Mode)
major mode convention (Major Mode Convention)
font-lock(-)mode (Font Lock Mode) (but font lock mode works)
mode(-)line format (Mode Line Format)
alias (Alias Menu Items)
keyboard menu (Keyboard Menus)
mouse menu (Mouse Menus)
define menu (Defining Menus) (but defining menu works)
key binding (Key Binding Commands)
translation keymap (Translation Keymaps)
lookup key, look(-)up key (Key Lookup)
search(ing) keymap (Searching Keymaps)
inherit keymap (Inheritance and Keymaps)
format keymap (Format of Keymaps) (but keymap format works)
modify event, event modification (Event Mod)
read(ing) event (Reading One Event)
key input (Key Sequence Input)
event string (Strings of Events)
access(ing) event (Accessing Events)
button event (Button-Down Events, Click Events, Mouse Events)
mouse event (Mouse Events)
keyboard event (Keyboard Events)
disable command (Disabling Commands) (but disable works)
prefix command (Prefix Command Arguments)
control g (Quitting)
adjust point (Adjusting Point)
minibuffer completion (Minibuffer Completion)
complete (Completion, Basic Completion, Minibuffer Completion) (but
completing works)
recursive minibuffer (Recursive Mini)
yes no (Yes-or-No Queries)
minibuffer window (Minibuffer Windows)
output variable, print variable (Output Variables)
(open|closed) parenthesis (Excess Open, Excess Closed)
compilation error (Compilation Errors)
advise (+ing) primitive (Advising Primitives)
activate advice (Activation of Advice) (but activating advice works)
around advice (Around-Advice) (should be no hyphen, BTW)
computed advice (Computed Advice)
load suffix (Load Suffixes)
search library, find library (Library Search)
load hook (Hooks for Loading) (but loading hook works)
repeat load, load again (Repeated Loading)
define type (Defining New Types)
type keyword (Type Keywords)
splice, list splice (Splicing into Lists)
customize type (Customization Types) (but customization type works)
define variable, define option (Variable Definitions)
define group (Group Definitions)
customize keyword (Common Keywords)
macro local variable (Surprising Local Vars)
indent macro (Indenting Macros)
document function (Function Documentation)
argument list (Argument List)
variable scope (Scope, Variable Scoping) (but scope works)
define (+ing) function (Defining Functions)
call(ing) function (Calling Functions)
access(ing) variable (Accessing Variables)
constant variable (Constant Variables)
frame(-)local variable (Frame-Local Variables)
variable alias (Variable Aliases)
signal error (Signaling Errors)
handle error (Handling Errors)
iterate (Iteration)
autoload (Autoloading)
list type (Classifying Lists)
plist, alist (Plists and Alists)
create symbol, creating symbol (Creating Symbols)
define symbol, defining symbol (Definitions) - a bad node name, BTW
create hash, creating hash (Creating Hash)
define hash, defining hash (Defining Hash)
bool vector (Bool-Vectors) (but bool-vector works)
char table (Char-Tables) (but char-table works)
list order (Rearrangement)
list variable (List Variables)
list structure (Building Lists)
modify list (Modifying Lists)
list predicate (List-related Predicates)
convert case, change case (Case Conversion)
printf (Formatting Strings)
modify string (Modifying Strings)
string predicate (Predicates for Strings)
arithmetic (Arithmetic Operations)
numeric conversion, number conversion, convert number (Numeric Conversions)
number predicate (Predicates on Numbers)
numeric comparison, compare number(s) (Comparison of Numbers)
buffer type (Buffer Type)
marker type (Marker Type)
window type (Window Type)
frame type (Frame Type)
process type (Process Type)
keymap type (Keymap Type)
overlay type (Overlay Type)
string syntax (Syntax for Strings)
nonprinting character (Nonprinting Characters)
integer type (Integer Type)
floating point type (Floating Point Type)
character type (Character Type)
array type (Array Type)
symbol type (Symbol Type)
cons cell type (Cons Cell Type)
string type (String Type)
vector type (Vector Type)
char-table type (Char-Table Type)
bool-vector type (Bool-Vector Type)
hash table type (Hash Table Type)
function type (Function type)
macro type (Macro Type)
byte-code type (Byte-Code Type)
autoload type (Autoload Type)
circular list (Circular Objects) (but circular works)
t (nil and t) - should be first entry found


4. BTW, "Postscript" should be "PostScript" everywhere (compare
http://en.wikipedia.org/wiki/PostScript and
http://en.wikipedia.org/wiki/Postscript)

Re: standard error not in Elisp manual index

[Richard Stallman]

    C-h i, pick Elisp manual
    i standard error => "No `standard error' in index

    But:
    s  standard error takes you to the top-level menu item Standard Errors

I do not see why every node topic should be in the index.

RE: standard error not in Elisp manual index

[Drew Adams]

>     C-h i, pick Elisp manual
>     i standard error => "No `standard error' in index
>
>     But:
>     s  standard error takes you to the top-level menu item Standard Errors
>
> I do not see why every node topic should be in the index.

Certainly not; who claimed the contrary? What should be in the index are
terms that users are likely to look to the index for. Some nodes will need
no index entry; some nodes will need multiple entries.

I would look in the index for a list of standard errors (types or messages),
wouldn't you? In a conventional index, which has a small degree of
hierarchy, I would expect entries such as this:

  errors
    handling
    messages
    standard
    types
    ...

In the case of an Info index, I would expect the keywords "error" and
"standard", together but in either order, to hit an index entry for the
passage that presents the standard error types or the most important error
messages.

Re: standard error not in Elisp manual index

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 24 Mar 2007 13:54:26 -0700
> 
> 4. BTW, "Postscript" should be "PostScript" everywhere

Done.

Re: standard error not in Elisp manual index

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 24 Mar 2007 13:54:26 -0700
> 
> > > There might be other top-level menu terms that should also be in the
> > > index.
> >
> > Yes, there might, so please tell if you find any.
> 
> 1. These terms are not in the index (at least in these forms):

I added some of these (about half of what you suggested).  Some
reasons for not adding the others:

  . Minor differences wrt to existing entries (e.g., "do something"
    when "doING something" already exists).

  . Entries that might be suitable for the user manual, not for the
    ELisp manual, whose readers are programmers looking for Lisp
    features.  Examples: copy text, cut, FOO mode, utf-8.

  . Entries for issues that people are unlikely to look up in this
    specific manual.  Example: gpl.

> 2. As a rule of thumb, it would be good for each of the top-level menu items
> to be the first or near the first hit for the keywords in that item name, or
> keywords closely associated with that item name.
> 
> For example, the node addressed by menu item _Functions_ should be among the
> first hits if you use `i function'. As it is now, that node is accessed only
> after a hundred or so uses of `,' after `i function'. Consider doing this
> for these top-level menu items:

While I agree with the feature you suggest, I don't think that its
implementation should by by tweaking index entries in the manual.
More likely, this is something Info should do when it sorts hits for
display.

So I didn't use the suggestions in this group.

> 3. These terms have no entries for the nodes in parens:
> 
> memory (Memory Usage)
> documentation (Documentation Tips)
> warning (Warning Tips)
> key binding (Key Binding Conventinos)

I'm not sure what you meant by these.  Please explain.

Thanks again for taking time to write these suggestions.

RE: standard error not in Elisp manual index

[Drew Adams]

> > 1. These terms are not in the index (at least in these forms):
> 
> I added some of these (about half of what you suggested).

That's much more than I expected. Thanks.

> Some reasons for not adding the others:
>   . Minor differences wrt to existing entries (e.g., "do something"
>     when "doING something" already exists).
> 
>   . Entries that might be suitable for the user manual, not for the
>     ELisp manual, whose readers are programmers looking for Lisp
>     features.  Examples: copy text, cut, FOO mode, utf-8.
> 
>   . Entries for issues that people are unlikely to look up in this
>     specific manual.  Example: gpl.

Sounds good to me.

> > 2. As a rule of thumb, it would be good for each of the 
> >    top-level menu items to be the first or near the first hit
> >    for the keywords in that item name, or
> >    keywords closely associated with that item name.
> 
> While I agree with the feature you suggest, I don't think that its
> implementation should by by tweaking index entries in the manual.
> More likely, this is something Info should do when it sorts hits for
> display.

I agree.

> So I didn't use the suggestions in this group.
> 
> > 3. These terms have no entries for the nodes in parens:
> > 
> > memory (Memory Usage)
> > documentation (Documentation Tips)
> > warning (Warning Tips)
> > key binding (Key Binding Conventinos)
> 
> I'm not sure what you meant by these.  Please explain.

I meant that `i memory' will not find node "Memory Usage", and so on.

Thanks.

Re: standard error not in Elisp manual index

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-devel@gnu.org>
> Date: Sat, 31 Mar 2007 08:06:35 -0700
> 
> > > 3. These terms have no entries for the nodes in parens:
> > > 
> > > memory (Memory Usage)
> > > documentation (Documentation Tips)
> > > warning (Warning Tips)
> > > key binding (Key Binding Conventinos)
> > 
> > I'm not sure what you meant by these.  Please explain.
> 
> I meant that `i memory' will not find node "Memory Usage", and so on.

I added some of these.