Re: Info enhancements

[Juri Linkov <juri@jurta.org>]

karl@freefriends.org (Karl Berry) writes:
> As for the xref stuff, I am not at all sure the second arg to xref
> should be treated in a special way; that was not its original intent and
> nothing has ever been documented about it.  I didn't know standalone
> info did any searching based on it.  I'll have to think about that.
>
> I can see that making index entries automatically be xrefable points
> could be useful, in a few circumstances.  But that is a separate feature
> from handling entries in the indexes themselves, so that the menu
> entries there go to the right place.
>
> Luc, my own personal opinion is that the conditional
> file-coding-system-alist xref should be deleted as you were going to
> do.  If it's in the same section, users shouldn't need an xref (or else
> the section should be split, but the section in question seems a
> reasonable length to me).

I agree that references to another part of the same small Info node is
useless.  I used this particular section as an example of enhancements.
But there are many other places in Info documentation where better
references to index entries are needed.  For instance, let's consider the
following excerpt from the Emacs Lisp Manual:

     See also `append' in *Note Building Lists::, `concat' in *Note
     Creating Strings::, and `vconcat' in *Note Vectors::, for other
     ways to copy sequences.

Such kind of references has at least two big drawbacks:

1. Users see too much unimportant information such as node names.
With using function names in reference names users will see only
function names, i.e. only what they need.  Nodes names will be hidden:

     See also append, concat, and vconcat for other ways to copy
     sequences.

2. When a reference contains only a node name, then after going to
   this node user should manually locate a place where needed
   function is described.  Note that nodes `Building Lists' and
   `Creating Strings' are very large, so user must spend a significant
   amount of time to locate this place.  With using index entries
   as reference names, this tedious task will be performed automatically.

   There are two variants of writing index names in references:

     See also *Note append: Building Lists, *Note concat: Creating
     Strings, and *Note vconcat: Vectors, for other ways to copy
     sequences.

   or references to anchors:

     See also *Note append::, *Note concat::, and *Note vconcat::, for
     other ways to copy sequences.

I believe this enhancement can easily be done with the existing Info
format.

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