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: Tue, 21 Jun 2011 13:59:26 -0700 Message-ID: References: <80oc1u26ae.fsf@gmail.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 1308690113 26893 80.91.229.12 (21 Jun 2011 21:01:53 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 21 Jun 2011 21:01:53 +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 Tue Jun 21 23:01:47 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 1QZ84x-0007Hm-IA for ged-emacs-devel@m.gmane.org; Tue, 21 Jun 2011 23:01:47 +0200 Original-Received: from localhost ([::1]:51134 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZ84w-0001A5-83 for ged-emacs-devel@m.gmane.org; Tue, 21 Jun 2011 17:01:46 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:37741) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZ833-0000h9-4n for emacs-devel@gnu.org; Tue, 21 Jun 2011 16:59:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QZ831-0008Ly-Co for emacs-devel@gnu.org; Tue, 21 Jun 2011 16:59:48 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:50580) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QZ831-0008Ls-2G for emacs-devel@gnu.org; Tue, 21 Jun 2011 16:59:47 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by rcsinet10.oracle.com (Switch-3.4.4/Switch-3.4.2) with ESMTP id p5LKxaJE018467 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 21 Jun 2011 20:59:38 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p5LKxZCL003195 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 21 Jun 2011 20:59:35 GMT Original-Received: from abhmt005.oracle.com (abhmt005.oracle.com [141.146.116.14]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p5LKxUBG002175; Tue, 21 Jun 2011 15:59:30 -0500 Original-Received: from dradamslap1 (/10.159.50.205) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 21 Jun 2011 13:59:29 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcwwUNcHQ48HwVrLRXaFbm/easFcXgAAOWaw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090202.4E01063B.0025: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:140807 Archived-At: > It would be good if a docstring could point at some anchor > in a manual... > > It would be better to have some markup to say "hey ! go > the point that correspond to index entry XXX where you find > that index in this index info node", and XXX is the > function/variable/etc... to document and that has some index > entry. I provided a patch to do this recently - see thread "adding manual cross-ref links to *Help*". However, I cannot give you a URL to that thread, because for some reason it is not recorded in the archive! What's up with that? Anyway, I have since improved the code slightly. To give it a try, or to examine the code: http://www.emacswiki.org/emacs/download/help-fns%2b.el Just load the file and try `C-h v', `C-h f', etc. See also user option `help-cross-reference-manuals'. (Juri will soon apply the code or otherwise provide similar behavior to Emacs.) I made `describe-*' commands offer links to the manuals: * `describe-mode' (each mode doc'd gets a link to manuals) * `describe-function' and derivatives, e.g. `describe-key' * `describe-variable' * `describe-face' * `describe-package' I did this for each standard `describe-*' command that I felt could reasonably link to manuals. Others could also be done, in some cases linking to specific manuals - e.g., `describe-character-set', `describe-class' (EIEIO), `describe-generic' (EIEIO). Some `describe-*' commands of course produce output that has nothing that could be linked to a manual - e.g. `describe-bindings'. Obviously anyone can use the code to add manual links for their own describe commands. You just need to add this sexp to the command's code, where THING is the thing to look up (e.g. function, var, face whatever): (Info-make-manuals-xref THING) THING needs to match an index entry exactly (we don't want apropos matching here). So if the index entry has extra stuff then that needs to be taken into account. For example, package names are indexed with " package" after the name (e.g. "Semantic package"), so I use this in `describe-package': (Info-make-manuals-xref (concat (symbol-name package) " package")) > That would also allow to make function/variable documentation > internationalized.