RE: 5x5 documentation

["Drew Adams" <drew.adams@oracle.com>]

> Actually, if your describe-* function

To be clear, I don't have a `describe-*' function.  I was using that name as an
abbreviation for all of the various `describe-<SOMETHING>' commands that are in
Emacs.

To use the feature that I added, you just need to add a sexp,
(Info-make-manuals-xref...), to the code for such a command.

That needs to be done for each such command that you want to take advantage of
the feature (or to a command that gets called by that command - e.g. doing it to
`describe-function' took care of `describe-key' too, since the latter calls the
former).

> would take some optional argument that in the case of
> Calc would be some function calc-strip-leading-calc  that 
> stripes the leading `calc-' then the `h f' in calc could be
> simplified by calling your describe-* function with that
> calc-strip-leading-calc argument.

Again, there is no `describe-*' function.  In this case, the relevant describe
command (if there is one) would probably be `describe-function' (bound to `C-h
f').

If Calc made use of `describe-function', perhaps by stripping `calc-' from
function names first, then yes, perhaps the feature could be leveraged without
explicitly modifying Calc to use `Info-make-manuals-xref'.

But it's perhaps as bothersome to make Calc use `describe-function' as it would
be to make it use (Info-make-manuals-xref...).  Dunno.
	
> That would commonalize some code. 
>	
> Something that I did not understand: it seems that you
> look at all manuals in some variable rather than some
> manual pointed at by some markup in the docstring

`Info-make-manuals-xref', which you call to create the link to manuals, takes
these arguments:

a. the thing (index entry) to be looked up (e.g. `forward-char')

b. optionally, a flag about extra newlines after the link

c. optionally, the manuals to search and whether to also look search them before
creating the link

If (c) is nil then a user option is used for deciding which manuals to use.
That is, if a describing command doesn't specify which manuals to search then
the user decides.

In this approach, nothing is keyed off of the doc string for the thing being
described.  It is instead the help command that creates the link to the manuals.
That describing command can link to whatever manuals it likes.  It could even
accept an argument (e.g. interactively a prefix arg) to determine which manuals
to search.

> --- which was my original idea --- that seems rather
> inefficient to look at many manuals, and also as you
> make some cache it takes memory.

You can search any number of manuals you want to.

If you know that for your particular term to look up you want to look in only
one manual, then you invoke `Info-make-manuals-xref' passing it only that one
manual along with the term.  When the user clicks the resulting link, only that
one manual is searched for the term.

Searching multiple manuals is optional.  It has a cost, but it can be useful if
that's really what you want/need.

In the case of the very general, standard `describe-*' commands (e.g.
`describe-variable'), which manuals should be searched by default?  

Dunno.  I chose the Emacs and Elisp manuals as the default value for the user
option, and I chose the user option's value as the default value for these
commands.

But any set of manuals can be used for any command.  It is the describing
command that specifies the manuals to use.

In this approach it is not up to the individual doc string to choose the manual
- that would be a different approach, with certain advantages and disadvantages,
no doubt.
	
> I had rather that a markup would explicitely indicate
> which manuals to inspect for the describe-* by using
> some markup in the docstring,

Feel free to implement it.

> or alternatively, that for each lisp file loaded to
> memory you can associate one or several manuals, and
> use the lisp file as a pointer to those manuals.
>	
> BTW, even with knowing the manual to look at, how do
> you know which node contains the appropriate index?

Not sure I understand the question.  Example:

The Elisp manual has one index, which has many index entries (for functions,
variables, keymaps, etc.).  When you click a *Help* link that searches the Elisp
manual, the search looks up the term you're looking for in the index.

In effect, it just grabs that index entry, with its link to a node, and pastes
it onto a virtual index page.  When you click the *Help* link you are put into
Info looking at that virual index page.  It will have one or more links to the
nodes that discuss the thing you're looking up.  Click one of those links et
voila.

This is no different from clicking the links in the manual's index itself.  All
that has happened is that you've been presented with a subset of that index,
which covers only the one term you're looking for.  But if more than one manual
is searched then you get the matching entries from each of those manuals, all on
the same virtual-index page.
	
> The cost for the docstring markup method would to add a
> docstring to all the calc-... functions,

If you do that then you can already take advantage of what I've done, I think,
as I said earlier.

Consider the example of `cos': that one works, because there is a doc string for
function `cos' - in the _Elisp_ manual (a different `cos' function from Calc's).

If you do not load Calc, then when you click the `manuals' link for `cos' in
*Help* you see only one index entry: for the Elisp manual.  If you do load Calc
(e.g. do `C-x * *') then when you click the link you see two index entries: one
for the Elisp manual, one for the Calc manual.

This is in spite of the fact that the Calc function `cos' has no doc string.
But it works because there is _some_ function `cos' that does have a doc string.
Give a doc string to each of the Calc commands and this should work for them all
(once Calc is loaded).

> that could be made systematic by defining those function
> by a specfic macro rather than by defun. Given that
> docstrings are not, AFAIK, loaded to memory, that may make
> emacs more compact.
>
> Also, as I mentioned previously, the Calc implementation
> is in my view a bit outdated, as it reads from the index
> only the node name, and not the line number. This is
> compensated by searching some language dependent regexp,
> which would be bad practice, even if the manual was
> written in French :-P. Besides this way of doing has
> already proved prone to bugs in the past. This is mainly
> the reason why I got interested in your package.

To be clear - I am not trying to propose this manual-links feature for use by
Calc or as a solution to anything beyond what it does already.  If someone wants
to try to use it for something like Calc it might - or it might not - be
appropriate.  I don't know.

And as I mentioned a couple of times, Juri Linkov will soon be doing something
like this for Emacs itself.  It's not clear that what he will do will be similar
to what I did - he spoke of using "Help templates" instead etc.  I know nothing
about that.  I'm sure he'll take a look at what I did before deciding what to
do, but that's all I know.

I'm just saying that if you wait a bit you might have something in Emacs that
you could use to do what you want, and it might fit what you need better than
what I've done.  If not then you can always try using what I've done or roll
your own.  HTH.