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: Documentation for "Clone Buffers" (corrected version) Date: Sun, 14 Mar 2004 12:17:05 -0600 (CST) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200403141817.i2EIH5M03101@raven.dms.auburn.edu> References: <200403121634.i2CGYrZ04201@f7.net> <200403140232.i2E2WUT01565@raven.dms.auburn.edu> NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1079288662 7837 80.91.224.253 (14 Mar 2004 18:24:22 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 14 Mar 2004 18:24:22 +0000 (UTC) Cc: acm@muc.de, karl@freefriends.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Mar 14 19:24:13 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 1B2aHU-000494-00 for ; Sun, 14 Mar 2004 19:24: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 1B2aHU-0004ie-00 for ; Sun, 14 Mar 2004 19:24:12 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1B2aDE-0006M3-BU for emacs-devel@quimby.gnus.org; Sun, 14 Mar 2004 13:19:48 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B2aCo-0006Je-Hd for emacs-devel@gnu.org; Sun, 14 Mar 2004 13:19:22 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B2aCD-0006BE-VL for emacs-devel@gnu.org; Sun, 14 Mar 2004 13:19:18 -0500 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.30) id 1B2aCD-0006BA-Lw for emacs-devel@gnu.org; Sun, 14 Mar 2004 13:18:45 -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 i2EIIYKt021810; Sun, 14 Mar 2004 12:18:34 -0600 (CST) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.6+Sun/8.11.6) id i2EIH5M03101; Sun, 14 Mar 2004 12:17:05 -0600 (CST) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: eliz@elta.co.il In-reply-to: (message from Eli Zaretskii on 14 Mar 2004 09:36:05 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 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:20464 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20464 Eli Zaretskii wrote: > + @unnumberedsubsec @kbd{M-n} creates a cloned Info buffer in Emacs Do we really need a new section for this? and Karl Berry wrote: It is wrong to use @unnumberedsubsec in this way, incidentally. @subheading is the thing to use, except in this case I doubt any heading is necessary. Especially if m/g get moved. I believe the M-n stuff belongs in (info)Advanced. A new section seems clearly needed because I do not believe that the M-n stuff belongs in any of the three other sections in that node. I was not the one who divided (info)Advanced up into @unnumberedsubsec the way it is done. It struck me as very unusual when I noticed it, but apparently whoever wrote it thought that it looked better than the alternatives in Info. I ran texi2dvi on info.texi. Reading info.texi in hardcopy just makes no sense and it seems impossible to change info.texi to make reading it in hardcopy useful. So I believe the Info version is what we have to worry about (for this particular file). Clearly we could change the structure of (info)Advanced. In particular, we could replace @unnumberedsubsec with @subheading. I do not know whether that makes any difference _in Info_. If @subheading looks better, just let me know and I will replace all four occurrences of @unnumberedsubsec in (info)Advanced. (The revised patch below does not yet do that, just in case the original author had some reason to use it.) Eli Zaretskii wrote: Even in its ``advanced'' sections, this manual assumes a user who is not really ``advanced'' by the Emacs standards. The material on manually editing .info files looks pretty advanced to me. Such a user might not know what buffer cloning means. Hence, I think we should explain this term before we use it. In any case, the first use of "cloned" should be in @dfn (and without the quotes, as @dfn takes care of that). We should also have an xref to the section in the Emacs manual that describes cloned buffers, I think. There is no such section. That is exactly what started this thread. Richard believes that it is not important enough to be documented in the Emacs manual. It is not documented in the Elisp manual either. (Maybe it should be?) The only documentation is the docstring of `clone-buffer', which right now is very incomplete and does not even mention the interactive use. I proposed a patch to simple.el that would at least provide complete documentation in that docstring, on Thursday. I got no reaction. I do not know whether that means that it is OK to apply it now. I just used "cloned" as a jargon word, not as a technical term. In the revised patch below, I removed all references to the word. I think this description should be copied (copied, not moved) into the part that describes `g' and `m', and then the @kindex entries should be removed. To the best of my knowledge, no other place in the Emacs manuals indexes commands starting with the prefix argument; we always document the command itself and describe there the effect of the argument. `g' is _already_ described in the same node. I briefly mention `C-u m' in (info)Help-M in the revised patch below. I deleted the @kindex entries for C-u {g,m}. So what about this revised patch: ===File ~/info.texi-diff==================================== *** info.texi.~1.39.~ Mon Mar 8 18:17:14 2004 --- info.texi Sun Mar 14 10:58:32 2004 *************** *** 614,619 **** --- 614,624 ---- stands for the subtopic of the line you are on. You can also click the middle mouse button directly on the subtopic line to go there. + As a more advanced feature, if you type @kbd{C-u m}, everything + works exactly as if you just typed @kbd{m}, except that the command + goes to the node in a new independent Info buffer, which it selects in + another window. The current Info node remains visible in its window. + Here is a menu to give you a chance to practice. This menu gives you three ways of going to one place, Help-FOO: *************** *** 1004,1009 **** --- 1009,1031 ---- edit the Info file, so typing @kbd{e} there goes to the end of the current node. + @unnumberedsubsec @kbd{M-n} creates a new independent Info buffer in Emacs + + @kindex M-n @r{(Info mode)} + @findex clone-buffer + @cindex creating multiple Info buffers + If you are reading Info in Emacs, you can select a new independent + Info buffer in another window by typing @kbd{M-n}. The new buffer + starts out as an exact copy of the old one, but you will be able to + move independently between nodes in the two buffers. (In Info mode, + @kbd{M-n} runs the Emacs command @code{clone-buffer}.) + + In Emacs Info, you can also produce new Info buffers by giving a + numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u + m} and @kbd{C-u g} go to a new node in exactly the same way that + @kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they + select in another window. + @node Info Search, Add, Advanced, Expert Info @comment node-name, next, previous, up @section How to search Info documents for specific subjects ============================================================