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 22:27:24 +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="_94876e96-c3bc-429c-83b7-f15e4bb20cd4_" X-Trace: dough.gmane.org 1308774478 16273 80.91.229.12 (22 Jun 2011 20:27:58 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 22 Jun 2011 20:27:58 +0000 (UTC) Cc: Karl Berry , pertusus@free.fr, emacs-devel To: , , Jay Belanger Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 22 22:27:53 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 1QZU1f-00008J-VO for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 22:27:52 +0200 Original-Received: from localhost ([::1]:47086 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZU1e-0002MT-MA for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 16:27:50 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:54635) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZU1J-0002Lu-5M for emacs-devel@gnu.org; Wed, 22 Jun 2011 16:27:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QZU1H-0000P4-6B for emacs-devel@gnu.org; Wed, 22 Jun 2011 16:27:28 -0400 Original-Received: from dub0-omc3-s1.dub0.hotmail.com ([157.55.2.10]:10561) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZU1G-0000OW-Mh for emacs-devel@gnu.org; Wed, 22 Jun 2011 16:27:27 -0400 Original-Received: from DUB102-W3 ([157.55.2.7]) by dub0-omc3-s1.dub0.hotmail.com with Microsoft SMTPSVC(6.0.3790.4675); Wed, 22 Jun 2011 13:27:24 -0700 X-Originating-IP: [92.135.112.55] Importance: Normal In-Reply-To: X-OriginalArrivalTime: 22 Jun 2011 20:27:24.0680 (UTC) FILETIME=[CBE82080:01CC311A] X-detected-operating-system: by eggs.gnu.org: Windows 2000 SP4, XP SP1+ X-Received-From: 157.55.2.10 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:140878 Archived-At: --_94876e96-c3bc-429c-83b7-f15e4bb20cd4_ Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Hello=2C Actually=2C if your describe-* function would take some optional argument t= hat in the case of Calc would be some function calc-strip-leading-calc tha= t=20 stripes the leading `calc-' then the `h f' in calc could be simplified by c= alling your describe-* function with that =20 calc-strip-leading-calc argument.=20 That would commonalize some code.=20 =20 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 d= ocstring --- which was my original idea --- that seems rather inefficient t= o look at many manuals=2C and also as you make some cache it takes memory. =20 I had rather that a markup would explicitely indicate which manuals to insp= ect for the describe-* by using some markup in the docstring=2C or alternat= ively=2C that for each lisp file loaded to memory you can associate one or = several manuals=2C and use the lisp file as a pointer to those manuals.=20 BTW=2C even with knowing the manual to look at=2C how do you know which nod= e contains the appropriate index ?=20 The cost for the docstring markup method would to add a docstring to all th= e calc-... functions=2C that could be made systematic by defining those fun= ction by a specfic macro rather than by defun. Given that docstrings are no= t=2C AFAIK=2C loaded to memory=2C that may make emacs more compact. Also=2C as I mentioned previously=2C the Calc implementation is in my view = a bit outdated=2C as it reads from the index only the node name=2C and not = the line number. This is compensated by searching some language dependent r= egexp=2C which would be bad practice=2C even if the manual was written in F= rench :-P. Besides this way of doing has already proved prone to bugs in th= e past. This is mainly the reason why I got interested in your package. 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 10:55:20 -0700 > CC: pertusus@free.fr=3B emacs-devel@gnu.org=3B karl@freefriends.org >=20 > > It seems that there was a mistunderstanding=2C 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. > =09 > Nope. > =09 > > Here is the use case I was thinking of... >=20 > Yes=2C what I did probably won't help you with that=2C at least not direc= tly. > AFAICT=2C the Calc stuff is pretty much a special case. >=20 > If=2C on the other hand=2C the Calc function `cos' had a doc string=2C th= en the `C-h f > cos' output would=2C with my code=2C include a link to its doc in the Cal= c manual. >=20 > In fact=2C because there is also an Emacs-Lisp function named `cos'=2C `C= -h f cos' > does show *Help*=2C and it does therefore show a link to the manuals. >=20 > When you then click that manuals link=2C and assuming option > `help-cross-reference-manuals' says to check the Calc manual (i.e.=2C if = it has > value `all' or a list containing "calc")=2C you'll get an Info virtual in= dex with > a link to the location in the Calc manual. >=20 > For example=2C with value `all'=2C so that all manuals are searched=2C I = get this > virtual index when I click `manuals': >=20 > * cos [elisp]: (elisp)Math Functions > * cos [calc]: (calc)Trigonometric and Hyperbolic Functions >=20 > That won't work for something like `sinh'=2C however=2C because `C-h f' d= oes not > recognize `sinh' (no match) - there is no doc for that function. >=20 > If calc-math.el has been loaded=2C then `C-h f calc-sinh' does show *Help= * (with > just "Not documented"). But because the Calc manual index entry for this= is > `sinh'=2C not `calc-sinh'=2C no `manuals' link is added to *Help* for thi= s: > `calc-sinh' is indexed. >=20 > See my comment about `describe-package' - this is similar. In the case o= f > package names=2C the index entries have " package" appended to the names= =2C so in > `describe-package' I set up the manuals link to look for the package name= with > that text appended. >=20 > Something similar could be done for Calc perhaps (remove the `calc-' to g= et the > proper index entry)=2C but we probably would not want to do that at the l= evel of > the general command `describe-function' (`C-h f'). It might be appropria= te to > do it for a Calc-specific help command=2C but it seems that Calc already = gives you > everything you could want in this regard. >=20 > In sum=2C what I've done probably won't help you directly=2C and it won't= do what > you describe as the special=2C built-in behavior for looking up stuff in = the Calc > manual. But it could perhaps be leveraged=2C the same as is done for oth= er > `describe-*' functions. >=20 >=20 = --_94876e96-c3bc-429c-83b7-f15e4bb20cd4_ Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
Hello=2C


Actually=2C if your describe-* functio= n would take some optional argument that in the case of Calc would be some = function calc-strip-leading-calc  =3Bthat =3B
stripes the leadin= g `calc-' then the `h f' in calc could be simplified by calling your descri= be-* function with that  =3B calc-strip-leading-calc argument. =3B


That would commonalize= some code.


 =3B 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 d= ocstring --- which was my original idea --- that seems rather inefficient t= o look at many manuals=2C and also as you make some cache it takes memory.  =3B


I had rather that a markup would explicitely indicate w= hich manuals to inspect for the describe-* by using some markup in the docs= tring=2C or alternatively=2C that for each lisp file loaded to memory you c= an associate one or several manuals=2C and use the lisp file as a pointer t= o those manuals.


BTW=2C even with knowing the manual to look at= =2C how do you know which node contains the appropriate index ? =3B
=

The cost for the docstring markup method would to add a docstring t= o all the calc-... functions=2C that could be made systematic by defining t= hose function by a specfic macro rather than by defun. Given that docstring= s are not=2C AFAIK=2C loaded to memory=2C that may make emacs more compact.=


Also=2C as I mentioned previously=2C the Calc implementation is= in my view a bit outdated=2C as it reads from the index only the node name= =2C and not the line number. This is compensated by searching some language= dependent regexp=2C which would be bad practice=2C even if the manual was = written in French :-P. Besides this way of doing has already proved prone t= o bugs in the past. This is mainly the reason why I got interested in your = package.


 =3B  =3BVincent.



>=3B Fr= om: drew.adams@oracle.com
>=3B To: vincent.b.1@hotmail.fr=3B monnier@i= ro.umontreal.ca=3B jay.p.belanger@gmail.com
>=3B Subject: RE: 5x5 docu= mentation
>=3B Date: Wed=2C 22 Jun 2011 10:55:20 -0700
>=3B CC: p= ertusus@free.fr=3B emacs-devel@gnu.org=3B karl@freefriends.org
>=3B >=3B >=3B It seems that there was a mistunderstanding=2C I thought>=3B >=3B that your module allows to add some addtional markup
>= =3B >=3B into the doctstring itself (similar to \\[...]) to
>=3B >= =3B display some part of some manual instead of the docstring
>=3B >= =3B content.
>=3B
>=3B Nope.
>=3B
>=3B >=3B Here = is the use case I was thinking of...
>=3B
>=3B Yes=2C what I did= probably won't help you with that=2C at least not directly.
>=3B AFAI= CT=2C the Calc stuff is pretty much a special case.
>=3B
>=3B If= =2C on the other hand=2C the Calc function `cos' had a doc string=2C then t= he `C-h f
>=3B cos' output would=2C with my code=2C include a link to = its doc in the Calc manual.
>=3B
>=3B In fact=2C because there i= s also an Emacs-Lisp function named `cos'=2C `C-h f cos'
>=3B does sho= w *Help*=2C and it does therefore show a link to the manuals.
>=3B >=3B When you then click that manuals link=2C and assuming option
>= =3B `help-cross-reference-manuals' says to check the Calc manual (i.e.=2C i= f it has
>=3B value `all' or a list containing "calc")=2C you'll get a= n Info virtual index with
>=3B a link to the location in the Calc manu= al.
>=3B
>=3B For example=2C with value `all'=2C so that all man= uals are searched=2C I get this
>=3B virtual index when I click `manua= ls':
>=3B
>=3B * cos [elisp]: (elisp)Math Functions
>=3B * = cos [calc]: (calc)Trigonometric and Hyperbolic Functions
>=3B
>= =3B That won't work for something like `sinh'=2C however=2C because `C-h f'= does not
>=3B recognize `sinh' (no match) - there is no doc for that = function.
>=3B
>=3B If calc-math.el has been loaded=2C then `C-h= f calc-sinh' does show *Help* (with
>=3B just "Not documented"). But= because the Calc manual index entry for this is
>=3B `sinh'=2C not `c= alc-sinh'=2C no `manuals' link is added to *Help* for this:
>=3B `calc= -sinh' is indexed.
>=3B
>=3B See my comment about `describe-pack= age' - this is similar. In the case of
>=3B package names=2C the inde= x entries have " package" appended to the names=2C so in
>=3B `describ= e-package' I set up the manuals link to look for the package name with
&= gt=3B that text appended.
>=3B
>=3B Something similar could be d= one for Calc perhaps (remove the `calc-' to get the
>=3B proper index = entry)=2C but we probably would not want to do that at the level of
>= =3B the general command `describe-function' (`C-h f'). It might be appropr= iate to
>=3B do it for a Calc-specific help command=2C but it seems th= at Calc already gives you
>=3B everything you could want in this regar= d.
>=3B
>=3B In sum=2C what I've done probably won't help you di= rectly=2C and it won't do what
>=3B you describe as the special=2C bui= lt-in behavior for looking up stuff in the Calc
>=3B manual. But it c= ould perhaps be leveraged=2C the same as is done for other
>=3B `descr= ibe-*' functions.
>=3B
>=3B
= --_94876e96-c3bc-429c-83b7-f15e4bb20cd4_--