From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: 5x5 documentation Date: Wed, 22 Jun 2011 06:35:33 -0700 Message-ID: References: <80oc1u26ae.fsf@gmail.com>, , , , <56817F7403144461BF148942A69D3689@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1308752857 4616 80.91.229.12 (22 Jun 2011 14:27:37 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 22 Jun 2011 14:27:37 +0000 (UTC) Cc: 'Karl Berry' , pertusus@free.fr, 'emacs-devel' To: "=?iso-8859-1?Q?'Vincent_Bela=EFche'?=" , , "'Jay Belanger'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Jun 22 16:27:32 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 1QZOOw-00084t-GJ for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 16:27:30 +0200 Original-Received: from localhost ([::1]:44251 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZOOv-0001Ub-D4 for ged-emacs-devel@m.gmane.org; Wed, 22 Jun 2011 10:27:29 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:41145) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZNay-0005K9-I4 for emacs-devel@gnu.org; Wed, 22 Jun 2011 09:35:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QZNaw-0006cE-Qp for emacs-devel@gnu.org; Wed, 22 Jun 2011 09:35:52 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:62584) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZNaw-0006c8-EU for emacs-devel@gnu.org; Wed, 22 Jun 2011 09:35:50 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by rcsinet10.oracle.com (Switch-3.4.4/Switch-3.4.2) with ESMTP id p5MDZf4T024984 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 22 Jun 2011 13:35:43 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p5MDZcsV026319 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 22 Jun 2011 13:35:39 GMT Original-Received: from abhmt102.oracle.com (abhmt102.oracle.com [141.146.116.54]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p5MDZXo3028117; Wed, 22 Jun 2011 08:35:33 -0500 Original-Received: from dradamslap1 (/10.159.50.205) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 22 Jun 2011 06:35:32 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcwwlXBYE98BkgRSQH6OacfgGBKeAQARjXSg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090208.4E01EFAF.00CB:SCFMA922111,ss=1,re=-4.000,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 1) X-Received-From: 148.87.113.121 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:140845 Archived-At: >> 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.