RE: 5x5 documentation

["Vincent Belaïche" <vincent.b.1@hotmail.fr>]

[-- Attachment #1: Type: text/plain, Size: 5874 bytes --]



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: drew.adams@oracle.com
> To: vincent.b.1@hotmail.fr; monnier@iro.umontreal.ca; jay.p.belanger@gmail.com
> Subject: RE: 5x5 documentation
> Date: Wed, 22 Jun 2011 06:35:33 -0700
> CC: karl@freefriends.org; pertusus@free.fr; emacs-devel@gnu.org
> 
> >> 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.
> 
> 
 		 	   		  

[-- Attachment #2: Type: text/html, Size: 6685 bytes --]