RE: 5x5 documentation

[Vincent Belaïche]

Hello,


It seems that there was a mistunderstanding, I thought that your module allows to add some addtional markup into the doctstring itself (similar to \\[...]) to display some part of some manual instead of the docstring content.



Here is the use case I was thinking of.


Type `C-x  * *' to enter the calculator. Then type `h f cos <ret>' that will direct you to line 45 of info node`(Calc) Trigonometric and Hyperbolic Functions'. What I am wondering is that it be possible to have such kind of a mechanism generalized, so that when I type `C-h C-f calc-cos' I would reach the same place of the same manual. And this would just be achieved, by just adding some docstring to function calc-cos which would contain a special markup telling "search info about `calc-cos' in manual `calc'".


Note that calc-cos, as well as all the other Calc function are not documented, and that the `h' (calling calc-help-prefix function) make some custom search in the Calc manual that could be generalized --- the current implementation does not use that index field also contains  some line number, instead is looks for some string in the corresponding node, which makes it local dependent.


   Vincent.

> From: address@hidden
> To: address@hidden; address@hidden; address@hidden
> Subject: RE: 5x5 documentation
> Date: Wed, 22 Jun 2011 06:35:33 -0700
> CC: address@hidden; address@hidden; address@hidden
>
> >> 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.
>
>