RE: 5x5 documentation

[Drew Adams]

>> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html

First, let me say again that Juri will be adding this to Emacs soon, and he may
choose to implement it differently.  So you might want to wait.  The rest of my
reply assumes you want to use the implementation I provided.

> 1) can you use it if you do not link directly to some
>    manual anchor point, but you make some indirection
>    like "go to the point defined in index entry XXX of
>    info node NNN" ? This is what is really needed for Calc ...

Not sure what you mean by "point defined...".  This feature works with existing
manual indexes.  It creates an Info virtual index that is an Info "menu" of
links to manual sections, those links being, in effect, grabbed from the indexes
of the searched manuals.

So the index entries must already be in the manual indexes.  This just collects
them into an Info page: a virtual index.

This is similar to what commands `Info-apropos-matches' and `Info-virtual-index'
do, with these differences:

a. Unlike `Info-apropos-matches', this does not do apropos matching.  It looks
up a given term in the indexes of the target manuals.  It looks for an exact
match (ignoring case).

b. Unlike `Info-virtual-index', this works across multiple manuals; it does not
look only in the index of the current manual.

c. Unlike `Info-virtual-index', you do not have to be inside Info to use this.

You can specify the manuals to be searched.  The user has control over this with
user option `help-cross-reference-manuals'.  But code can control this as well,
of course.

By default, a link to the manuals is added to the *Help* buffer for a
`describe-*' command, without first checking whether there are in fact any index
entries for the target term (e.g. function, var).  This is to save time, since
the index searching can take time, especially if many manual indexes are
searched.  (Index searching is cached, so it takes longer the first time.)

But you can optionally have the link be added to *Help* only if an index search
is successful.  This too is controlled by option `help-cross-reference-manuals'.

> 2) would it be easy just based on the function name, and
>    assuming that you can find it in some info node index
>    to compute the link --- I am thinking  that all math
>    function could be added this link by one simple macro
>    modification

I don't follow you.  The virtual Info index (aka "menu") is created when the
user clicks the link in *Help*.  Each entry in that virtual index is a direct
link to a manual section describing the target term (e.g. function).

Perhaps describe the use case you are thinking of - give a scenario, so I can
understand better.

> 3) is the method to introduce that new markup futureproof
>    and easily extensible to other kind of markup (like to
>    define other format for docstring, typically some
>    simplified texinfo would be a good choice, so that you
>    can cut and paste with manuals).

Again, I don't follow you; sorry.  

There is no markup.  There is no change to the doc strings - this is not like
using \\[...], for instance.

This represents a change not to the doc strings themselves but to the
`describe-*' commands that print out the doc in *Help*.  It just adds this line
to the printed text, with a link to the manuals:
"For more information check the manuals", with `manuals' being the link.

What happens is that when the link is clicked the indexes of the appropriate
manuals (as determined by `help-cross-reference-manuals') are searched for the
given term (the term that is passed to `Info-make-manuals-xref' in the code for
the `describe-*' command).

For instance, for `describe-variable', the variable is passed:
(Info-make-manuals-xref VARIABLE).  That call in the `describe-variable' code
just adds the "For more information..." text and link to *Help*.  When that link
is clicked, the actual Info lookup takes place: the indexes of the given manuals
are searched for the given VARIABLE.

Give it a try and you will quickly understand.  Then try again to describe your
scenario, what you're looking for.