RE: 5x5 documentation

[Vincent Belaïche]

Hello,


Actually, if your describe-* function 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. 


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


I had rather that a markup would explicitely indicate which manuals to inspect for the describe-* by using some markup in the docstring, 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 ? 


The cost for the docstring markup method would to add a docstring to all the calc-... functions, 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.


   Vincent.

> From: address@hidden
> To: address@hidden; address@hidden; address@hidden
> Subject: RE: 5x5 documentation
> Date: Wed, 22 Jun 2011 10:55:20 -0700
> CC: address@hidden; address@hidden; address@hidden
>
> > 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.
>
> Nope.
>
> > Here is the use case I was thinking of...
>
> Yes, what I did probably won't help you with that, at least not directly.
> AFAICT, the Calc stuff is pretty much a special case.
>
> If, on the other hand, the Calc function `cos' had a doc string, then the `C-h f
> cos' output would, with my code, include a link to its doc in the Calc manual.
>
> In fact, because there is also an Emacs-Lisp function named `cos', `C-h f cos'
> does show *Help*, and it does therefore show a link to the manuals.
>
> When you then click that manuals link, and assuming option
> `help-cross-reference-manuals' says to check the Calc manual (i.e., if it has
> value `all' or a list containing "calc"), you'll get an Info virtual index with
> a link to the location in the Calc manual.
>
> For example, with value `all', so that all manuals are searched, I get this
> virtual index when I click `manuals':
>
> * cos [elisp]: (elisp)Math Functions
> * cos [calc]: (calc)Trigonometric and Hyperbolic Functions
>
> That won't work for something like `sinh', however, because `C-h f' does not
> recognize `sinh' (no match) - there is no doc for that function.
>
> If calc-math.el has been loaded, then `C-h f calc-sinh' does show *Help* (with
> just "Not documented"). But because the Calc manual index entry for this is
> `sinh', not `calc-sinh', no `manuals' link is added to *Help* for this:
> `calc-sinh' is indexed.
>
> See my comment about `describe-package' - this is similar. In the case of
> package names, the index entries have " package" appended to the names, so in
> `describe-package' I set up the manuals link to look for the package name with
> that text appended.
>
> Something similar could be done for Calc perhaps (remove the `calc-' to get the
> proper index entry), but we probably would not want to do that at the level of
> the general command `describe-function' (`C-h f'). It might be appropriate to
> do it for a Calc-specific help command, but it seems that Calc already gives you
> everything you could want in this regard.
>
> In sum, what I've done probably won't help you directly, and it won't do what
> you describe as the special, built-in behavior for looking up stuff in the Calc
> manual. But it could perhaps be leveraged, the same as is done for other
> `describe-*' functions.
>
>