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: Re: Info enhancements Date: Sun, 7 Dec 2003 23:46:57 -0600 (CST) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200312080546.hB85kvD13204@raven.dms.auburn.edu> References: <878ylrbbk4.fsf@mail.jurta.org> <200312051827.hB5IRfk17741@f7.net> <87isku20s6.fsf@mail.jurta.org> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1070863036 21895 80.91.224.253 (8 Dec 2003 05:57:16 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 8 Dec 2003 05:57:16 +0000 (UTC) Cc: juri@jurta.org, bob@rattlesnake.com, karl@freefriends.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Mon Dec 08 06:57:12 2003 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1ATEOO-00057c-00 for ; Mon, 08 Dec 2003 06:57:12 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1ATEOO-0001bH-00 for ; Mon, 08 Dec 2003 06:57:12 +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 1ATFK0-0007aB-3r for emacs-devel@quimby.gnus.org; Mon, 08 Dec 2003 01:56:44 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.24) id 1ATFJN-0007Gd-Iy for emacs-devel@gnu.org; Mon, 08 Dec 2003 01:56:05 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.24) id 1ATFIq-0006mV-BP for emacs-devel@gnu.org; Mon, 08 Dec 2003 01:56:03 -0500 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.24) id 1ATFIH-00068D-FW; Mon, 08 Dec 2003 01:54:57 -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 hB85rgKk018453; Sun, 7 Dec 2003 23:53:42 -0600 (CST) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id hB85kvD13204; Sun, 7 Dec 2003 23:46:57 -0600 (CST) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Sun, 07 Dec 2003 12:19:29 -0500) 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:18536 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:18536 It might be useful to split up some nodes and, as I already said, I am willing to help do so. However, I believe that we might also have to increase the number of @anchor's in the elisp manual from the current four. The two efforts could complement each other. I believe that, for instance, a node like `(elisp)Documentation Tips' (216 lines) is best kept together and, at the same time, large enough to be a nuisance to wade through to find the correct item. I CC the following proposed change to Emacs devel because I believe that it is relevant to the discussion we are having. The somewhat strange name of the anchor is deliberate, to avoid interfering with present or, especially, future, anchor or node names, and to avoid problems with `g' completion. It is overridden by the third argument to @xref anyway. It could, of course be changed. (The [Tips] refers to tips.texi.) I propose to systematically rely on @anchor rather than on Juri's feature, because it is more reliable, more flexible and because it is an existing Texinfo feature, that does not require a departure from current Texinfo style and conventions. I believe that the @anchor in the diffs below could save the user quite a bit of searching and confusion. To me, it seems very helpful to the user in both Info and the printed manual. If desired, I could commit when Savannah starts working again. We could start making more of these @anchor's, in similar situations. ===File ~/tips-diff========================================= *** tips.texi.~1.53.~ Mon Oct 20 14:37:21 2003 --- tips.texi Sun Dec 7 19:28:58 2003 *************** *** 647,652 **** --- 647,653 ---- This prevents the open-parenthesis from being treated as the start of a defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). + @anchor{doc-hyperlinks [Tips]} @item @iftex When a documentation string refers to a Lisp symbol, write it as it ============================================================ ===File ~/displaydiff======================================= *** display.texi.~1.106.~ Sun Nov 2 12:23:12 2003 --- display.texi Sun Dec 7 20:03:32 2003 *************** *** 805,812 **** so that it is still Help mode at the end of their execution, then @code{with-output-to-temp-buffer} makes this buffer read-only at the end, and also scans it for function and variable names to make them ! into clickable cross-references. @xref{Documentation Tips, , Tips for ! Documentation Strings}. The string @var{buffer-name} specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. --- 805,813 ---- so that it is still Help mode at the end of their execution, then @code{with-output-to-temp-buffer} makes this buffer read-only at the end, and also scans it for function and variable names to make them ! into clickable cross-references. @xref{doc-hyperlinks [Tips], , Tips ! for Documentation Strings}, more particularly the item on hyperlinks ! in documentation strings, for more details. The string @var{buffer-name} specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. ============================================================ Appendix: Exhaustive list (grep) of all current @anchor's in the Elisp manual (four total): @anchor{modifier bits} in (elisp)Character Type, 165 lines. @anchor{Display Face Attribute Testing} in (elisp)Display Feature Testing, 133 lines. @anchor{Text help-echo} and @anchor{Help display}, both in (elisp)Special Properties, 224 lines.