From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: automatic anchors for definition commands. Date: Tue, 6 Jan 2004 20:50:19 -0600 (CST) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200401070250.i072oJC09935@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1073444130 10695 80.91.224.253 (7 Jan 2004 02:55:30 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 7 Jan 2004 02:55:30 +0000 (UTC) Cc: Juri Linkov , Karl Berry Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Wed Jan 07 03:55:25 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1Ae3qt-0008LT-00 for ; Wed, 07 Jan 2004 03:55:23 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1Ae3qt-00060l-00 for ; Wed, 07 Jan 2004 03:55:23 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.24) id 1Ae4o7-0000ge-Tu for emacs-devel@quimby.gnus.org; Tue, 06 Jan 2004 22:56:35 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1Ae4mS-0000Af-59 for emacs-devel@gnu.org; Tue, 06 Jan 2004 22:54:52 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1Ae4l1-0007hR-Ji for emacs-devel@gnu.org; Tue, 06 Jan 2004 22:53:55 -0500 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1Ae4jb-0006ux-2Y for emacs-devel@gnu.org; Tue, 06 Jan 2004 22:51:55 -0500 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id i072ouKk009733; Tue, 6 Jan 2004 20:50:56 -0600 (CST) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id i072oJC09935; Tue, 6 Jan 2004 20:50:19 -0600 (CST) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: emacs-devel@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:19063 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:19063 I now have made 22 anchors in the Elisp manual in addition to the four that were already there. This seems about the time to start thinking about whether I should continue to do things exactly like I have been busy doing, or whether at least _some_ things could be done more automatically and systematically. A larger and larger percentage of these anchors is starting to refer to function and variable definitions. There are _many_ nodes (or parts of nodes), say `(elisp)Related Topics', section 12.11 in the printed manual, that are index-like lists of references to function and variable definitions. Unlike the "real" indices, they do not refer to the page numbers _of the definitions_ in the printed manual. (They refer to the beginning of the section, which can be several pages off.) I have not yet started to make @anchors for these types of nodes. If I do, then I believe that a _very large_ percentage of function and variable definitions in the Elisp manual would have @anchors. Take the reference to `mapatoms' in `(elisp)Related Topics' as an example. The definition of `mapatoms' is on line 143 of Info node `(elisp)Creating Symbols' and (using the CVS version of texinfo.tex), on page 114 of the printed manual. The current reference in 12.11 refers to page 111, the beginning of the section, three pages off. (I am sure this is by no means a record, I did definitely not search for the worst example). The index gets page 114 correct. So would it not be possible to make "automatic anchors" for the definition commands, that is to have _some_ special semantics for the arguments (probably for the first argument) of @xref and friends that would refer to the definition commands (using Ref:'s in the .info files) and get the page number right in printed output? I have been using "Definition of VAR" as first argument, which might not be too good as a general automatic semantic, since one symbol can have several definitions and since it could conflict with a node name. What about something like "defun of mapatoms" or "defvr of myvr" as special first argument? These are unlikely to conflict with nodenames. Anyway, if we decide that automatic anchors for definition commands are a good and feasible idea, then we could start thinking about the best naming convention. I have trouble with Juri's Emacs Info emulation of anchors for two reasons: 1. It only applies to Emacs Info, not to the printed manual. 2. It is not necessarily the place intended by the author. It is a guess. So is the current standalone equivalent feature. But a makeinfo-texi2dvi solution could take care of both objections. Sincerely, Luc.