From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: =?iso-8859-1?B?VmluY2VudCBCZWxh72NoZQ==?= Newsgroups: gmane.emacs.devel Subject: RE: 5x5 documentation Date: Wed, 22 Jun 2011 18:26:54 +0200 Message-ID: References: <80oc1u26ae.fsf@gmail.com>, , , , , , , <56817F7403144461BF148942A69D3689@us.oracle.com>, , NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="_c6915996-4d6d-432a-8d52-3f3d5b21f80b_" X-Trace: dough.gmane.org 1308760606 23990 80.91.229.12 (22 Jun 2011 16:36:46 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 22 Jun 2011 16:36:46 +0000 (UTC) Cc: pertusus@free.fr, emacs-devel , Karl Berry To: , , Jay Belanger Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 22 18:36:41 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QZQPw-0008HH-2e for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 18:36:40 +0200 Original-Received: from localhost ([::1]:48369 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZQPv-00009J-7Q for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 12:36:39 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:54374) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZQGa-0006LR-48 for emacs-devel@gnu.org; Wed, 22 Jun 2011 12:27:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QZQGX-0005AX-RJ for emacs-devel@gnu.org; Wed, 22 Jun 2011 12:26:59 -0400 Original-Received: from dub0-omc3-s29.dub0.hotmail.com ([157.55.2.38]:28632) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZQGX-0005AG-16 for emacs-devel@gnu.org; Wed, 22 Jun 2011 12:26:57 -0400 Original-Received: from DUB102-W40 ([157.55.2.7]) by dub0-omc3-s29.dub0.hotmail.com with Microsoft SMTPSVC(6.0.3790.4675); Wed, 22 Jun 2011 09:26:55 -0700 X-Originating-IP: [92.135.112.55] Importance: Normal In-Reply-To: X-OriginalArrivalTime: 22 Jun 2011 16:26:55.0054 (UTC) FILETIME=[332DEEE0:01CC30F9] X-detected-operating-system: by eggs.gnu.org: Windows 2000 SP4, XP SP1+ X-Received-From: 157.55.2.38 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:140862 Archived-At: --_c6915996-4d6d-432a-8d52-3f3d5b21f80b_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Hello=2C It seems that there was a mistunderstanding=2C I thought that your module a= llows to add some addtional markup into the doctstring itself (similar to \= \[...]) to display some part of some manual instead of the docstring conten= t. Here is the use case I was thinking of. Type `C-x * *' to enter the calculator. Then type `h f cos ' that wil= l direct you to line 45 of info node`(Calc) Trigonometric and Hyperbolic Fu= nctions'. What I am wondering is that it be possible to have such kind of a= mechanism generalized=2C so that when I type `C-h C-f calc-cos' I would re= ach the same place of the same manual. And this would just be achieved=2C b= y just adding some docstring to function calc-cos which would contain a spe= cial markup telling "search info about `calc-cos' in manual `calc'". Note that calc-cos=2C as well as all the other Calc function are not docume= nted=2C and that the `h' (calling calc-help-prefix function) make some cust= om search in the Calc manual that could be generalized --- the current impl= ementation does not use that index field also contains some line number=2C= instead is looks for some string in the corresponding node=2C which makes = it local dependent. Vincent. > From: drew.adams@oracle.com > To: vincent.b.1@hotmail.fr=3B monnier@iro.umontreal.ca=3B jay.p.belanger@= gmail.com > Subject: RE: 5x5 documentation > Date: Wed=2C 22 Jun 2011 06:35:33 -0700 > CC: karl@freefriends.org=3B pertusus@free.fr=3B emacs-devel@gnu.org >=20 > >> http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html >=20 > First=2C let me say again that Juri will be adding this to Emacs soon=2C = 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. >=20 > > 1) can you use it if you do not link directly to some > > manual anchor point=2C 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 ... >=20 > Not sure what you mean by "point defined...". This feature works with ex= isting > manual indexes. It creates an Info virtual index that is an Info "menu" = of > links to manual sections=2C those links being=2C in effect=2C grabbed fro= m the indexes > of the searched manuals. >=20 > So the index entries must already be in the manual indexes. This just co= llects > them into an Info page: a virtual index. >=20 > This is similar to what commands `Info-apropos-matches' and `Info-virtual= -index' > do=2C with these differences: >=20 > a. Unlike `Info-apropos-matches'=2C this does not do apropos matching. I= t looks > up a given term in the indexes of the target manuals. It looks for an ex= act > match (ignoring case). >=20 > b. Unlike `Info-virtual-index'=2C this works across multiple manuals=3B i= t does not > look only in the index of the current manual. >=20 > c. Unlike `Info-virtual-index'=2C you do not have to be inside Info to us= e this. >=20 > You can specify the manuals to be searched. The user has control over th= is with > user option `help-cross-reference-manuals'. But code can control this as= well=2C > of course. >=20 > By default=2C a link to the manuals is added to the *Help* buffer for a > `describe-*' command=2C without first checking whether there are in fact = any index > entries for the target term (e.g. function=2C var). This is to save time= =2C since > the index searching can take time=2C especially if many manual indexes ar= e > searched. (Index searching is cached=2C so it takes longer the first tim= e.) >=20 > 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-ma= nuals'. >=20 > > 2) would it be easy just based on the function name=2C 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 >=20 > 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 di= rect > link to a manual section describing the target term (e.g. function). >=20 > Perhaps describe the use case you are thinking of - give a scenario=2C so= I can > understand better. >=20 > > 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=2C typically some > > simplified texinfo would be a good choice=2C so that you > > can cut and paste with manuals). >=20 > Again=2C I don't follow you=3B sorry. =20 >=20 > There is no markup. There is no change to the doc strings - this is not = like > using \\[...]=2C for instance. >=20 > 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 thi= s line > to the printed text=2C with a link to the manuals: > "For more information check the manuals"=2C with `manuals' being the link= . >=20 > What happens is that when the link is clicked the indexes of the appropri= ate > manuals (as determined by `help-cross-reference-manuals') are searched fo= r the > given term (the term that is passed to `Info-make-manuals-xref' in the co= de for > the `describe-*' command). >=20 > For instance=2C for `describe-variable'=2C 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 th= at link > is clicked=2C the actual Info lookup takes place: the indexes of the give= n manuals > are searched for the given VARIABLE. >=20 > Give it a try and you will quickly understand. Then try again to describ= e your > scenario=2C what you're looking for. >=20 >=20 = --_c6915996-4d6d-432a-8d52-3f3d5b21f80b_ Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
Hello=2C


It seems that there was a mistunderstanding=2C I though= t 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 o= f.


Type `C-x  =3B* *' to enter the calculator. Then type `h = f cos <=3Bret>=3B' 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=2C so that when I typ= e `C-h C-f calc-cos' I would reach the same place of the same manual. And t= his would just be achieved=2C by just adding some docstring to function cal= c-cos which would contain a special markup telling "search info about `calc= -cos' in manual `calc'".


Note that calc-cos=2C as well as all th= e other Calc function are not documented=2C 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 fiel= d also contains =3B some line number=2C instead is looks for some strin= g in the corresponding node=2C which makes it local dependent.


&= nbsp=3B  =3BVincent.


>=3B From: drew.adams@oracle.com=
>=3B To: vincent.b.1@hotmail.fr=3B monnier@iro.umontreal.ca=3B jay.p.= belanger@gmail.com
>=3B Subject: RE: 5x5 documentation
>=3B Date:= Wed=2C 22 Jun 2011 06:35:33 -0700
>=3B CC: karl@freefriends.org=3B pe= rtusus@free.fr=3B emacs-devel@gnu.org
>=3B
>=3B >=3B>=3B htt= p://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html
>=3B =
>=3B First=2C let me say again that Juri will be adding this to Emacs= soon=2C and he may
>=3B choose to implement it differently. So you m= ight want to wait. The rest of my
>=3B reply assumes you want to use = the implementation I provided.
>=3B
>=3B >=3B 1) can you use i= t if you do not link directly to some
>=3B >=3B manual anchor poi= nt=2C but you make some indirection
>=3B >=3B like "go to the poi= nt defined in index entry XXX of
>=3B >=3B info node NNN" ? This = is what is really needed for Calc ...
>=3B
>=3B Not sure what yo= u mean by "point defined...". This feature works with existing
>=3B m= anual indexes. It creates an Info virtual index that is an Info "menu" of<= br>>=3B links to manual sections=2C those links being=2C in effect=2C gra= bbed from the indexes
>=3B of the searched manuals.
>=3B
>= =3B So the index entries must already be in the manual indexes. This just = collects
>=3B them into an Info page: a virtual index.
>=3B
&= gt=3B This is similar to what commands `Info-apropos-matches' and `Info-vir= tual-index'
>=3B do=2C with these differences:
>=3B
>=3B a.= Unlike `Info-apropos-matches'=2C this does not do apropos matching. It lo= oks
>=3B up a given term in the indexes of the target manuals. It loo= ks for an exact
>=3B match (ignoring case).
>=3B
>=3B b. Un= like `Info-virtual-index'=2C this works across multiple manuals=3B it does = not
>=3B look only in the index of the current manual.
>=3B
&= gt=3B c. Unlike `Info-virtual-index'=2C you do not have to be inside Info t= o use this.
>=3B
>=3B You can specify the manuals to be searched= . The user has control over this with
>=3B user option `help-cross-re= ference-manuals'. But code can control this as well=2C
>=3B of course= .
>=3B
>=3B By default=2C a link to the manuals is added to the = *Help* buffer for a
>=3B `describe-*' command=2C without first checkin= g whether there are in fact any index
>=3B entries for the target term= (e.g. function=2C var). This is to save time=2C since
>=3B the index= searching can take time=2C especially if many manual indexes are
>=3B= searched. (Index searching is cached=2C so it takes longer the first time= .)
>=3B
>=3B But you can optionally have the link be added to *H= elp* only if an index search
>=3B is successful. This too is controll= ed by option `help-cross-reference-manuals'.
>=3B
>=3B >=3B 2)= would it be easy just based on the function name=2C and
>=3B >=3B = assuming that you can find it in some info node index
>=3B >=3B = to compute the link --- I am thinking that all math
>=3B >=3B f= unction could be added this link by one simple macro
>=3B >=3B mo= dification
>=3B
>=3B I don't follow you. The virtual Info index= (aka "menu") is created when the
>=3B user clicks the link in *Help*.= Each entry in that virtual index is a direct
>=3B link to a manual s= ection describing the target term (e.g. function).
>=3B
>=3B Per= haps describe the use case you are thinking of - give a scenario=2C so I ca= n
>=3B understand better.
>=3B
>=3B >=3B 3) is the method= to introduce that new markup futureproof
>=3B >=3B and easily ex= tensible to other kind of markup (like to
>=3B >=3B define other = format for docstring=2C typically some
>=3B >=3B simplified texin= fo would be a good choice=2C so that you
>=3B >=3B can cut and pa= ste with manuals).
>=3B
>=3B Again=2C I don't follow you=3B sorr= y.
>=3B
>=3B There is no markup. There is no change to the do= c strings - this is not like
>=3B using \\[...]=2C for instance.
&g= t=3B
>=3B This represents a change not to the doc strings themselves = but to the
>=3B `describe-*' commands that print out the doc in *Help*= . It just adds this line
>=3B to the printed text=2C with a link to t= he manuals:
>=3B "For more information check the manuals"=2C with `man= uals' being the link.
>=3B
>=3B What happens is that when the li= nk is clicked the indexes of the appropriate
>=3B manuals (as determin= ed by `help-cross-reference-manuals') are searched for the
>=3B given = term (the term that is passed to `Info-make-manuals-xref' in the code for>=3B the `describe-*' command).
>=3B
>=3B For instance=2C fo= r `describe-variable'=2C the variable is passed:
>=3B (Info-make-manua= ls-xref VARIABLE). That call in the `describe-variable' code
>=3B jus= t adds the "For more information..." text and link to *Help*. When that li= nk
>=3B is clicked=2C the actual Info lookup takes place: the indexes = of the given manuals
>=3B are searched for the given VARIABLE.
>= =3B
>=3B Give it a try and you will quickly understand. Then try aga= in to describe your
>=3B scenario=2C what you're looking for.
>= =3B
>=3B
= --_c6915996-4d6d-432a-8d52-3f3d5b21f80b_--