Re: Documentation for "Clone Buffers" (corrected version)

[Luc Teirlinck]

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
============================================================