Re: Manual: indexes are missing links

[Juri Linkov]

>> From: Juri Linkov <address@hidden>
>> Cc: address@hidden
>> Date: Sun, 07 Jan 2007 11:52:54 +0200
>> 
>> > Why do you think it's more important to see the node names in the
>> > index than it is in any other menu?
>> 
>> Menu item names in any other menu are often just a modified version
>> of the node name, so it makes sense to hide node names as e.g. in:
>> 
>> * Format: Outline Format.       What the text of an outline looks like.
>> * Motion: Outline Motion.       Special commands for moving through outlines.
>> * Visibility: Outline Visibility.  Commands to control what is visible.
>> * Views: Outline Views.            Outlines and multiple views.
>> 
>> Unlike this, index entry names contain no information about node names
>> to which they belong, and it is helpful to see them, e.g.:
>
> I asked why it is more important in an index, and your response is
> that it's ``helpful to see'', which doesn't really explain anything.

See my answer above.  IOW, often the node name can be deduced from the
menu item name.

> Suppose that a regular menu item did not have a resemblance to its
> node--would you still say then that it is more important to show nodes
> in the index, and why?

Because looking at node names in a large index node helps to make a
decision about visiting the node to which the index entry refers to.

>> * face-background:                       Attribute Functions.
>> * face-bold-p:                           Attribute Functions.
>> * face-differs-from-default-p:           Face Functions.
>> * face-documentation <1>:                Face Functions.
>> * face-documentation:                    Accessing Documentation.
>> 
>> It is especially important to see node names with the same index names
>> like in the two last lines above.
>
> The last two lines are actually a case of less than optimal indexing:
> the two index entries should have had different qualifiers, to tell
> the reader which aspects are described in each referenced place.

In the above example two duplicate index entries `face-documentation'
are fine: they are disambiguated by the node name.

> I will fix this when I have time, unless someone beats me to it.

You can't fix all duplicate index entries in all manuals.

>> There is enough horizontal space in the index menus to leave node
>> names displayed where they were displayed for many years so far
>> without complaints from users.
>
> The same can be said about hiding node names in general.

No, menu entries have the description part which helps to understand
to where the reference leads, but this part is missing on index entries.

-- 
Juri Linkov
http://www.jurta.org/emacs/