Documentation for "Clone Buffers" (corrected version)

[Alan Mackenzie <acm@muc.de>]

Hi, guys!

[Sorry, forgot to include the patch to emacs.texi.  It's here now.
Please ignore my previous post.]

Currently, `clone-buffer' is not documented in the Emacs manual.  The
following patch fixes this.

I've also tidied up and corrected the "Indirect Buffers" section a bit.
In particular, creating an indirect buffer is _not_ a suitable way to get
two indpendent *info* or *help* buffers.  (At least, it isn't for me on
Emacs 21.3.)

Also "cloned buffer" is a most unfortunate term.  It could refer to the
buffer to which the process of cloning has just been applied (i.e. the
original).  It could equally well refer to the buffer just created by the
process of cloning (i.e. the copy).  I've purged it from buffers.texi.

As a matter of interest, is there any reason why `clone-buffer' has no
binding in the pertinent help keymaps (e.g. the one you get with C-h f
<foo>)?  It seems a bit inconsistent that you can use M-n on an info
page, but not a help text.


2004-02-25  Alan Mackenzie  <acm@muc.de>

	* buffers.texi.  New section "Cloning Buffers".  Tidied up
	section "Indirect Buffers"
	* emacs.texi.  Insert menu entry.


*** buffers-1.26.texi	Tue Feb 24 19:34:49 2004
--- buffers-1.26.acm.texi	Wed Feb 25 09:50:41 2004
***************
*** 55,60 ****
--- 55,61 ----
  * Several Buffers::     How to go through the list of all buffers
  			  and operate variously on several of them.
  * Indirect Buffers::    An indirect buffer shares the text of another buffer.
+ * Cloning Buffers::     Cloning a buffer makes a copy of its text.
  * Buffer Convenience::  Convenience and customization features for
                            buffer handling.
  @end menu
***************
*** 438,445 ****
  @cindex base buffer
  
    An @dfn{indirect buffer} shares the text of some other buffer, which
! is called the @dfn{base buffer} of the indirect buffer.  In some ways it
! is the analogue, for buffers, of a symbolic link between files.
  
  @table @kbd
  @findex make-indirect-buffer
--- 439,448 ----
  @cindex base buffer
  
    An @dfn{indirect buffer} shares the text of some other buffer, which
! is called the @dfn{base buffer} of the indirect buffer.  In some ways
! it is the analogue, for buffers, of a symbolic link between files.  (A
! clone buffer, by contrast, is a @emph{copy} of its original.
! @xref{Cloning Buffers}.)
  
  @table @kbd
  @findex make-indirect-buffer
***************
*** 456,462 ****
  select it in another window (@code{clone-indirect-buffer-other-window}).
  @end table
  
!   The text of the indirect buffer is always identical to the text of its
  base buffer; changes made by editing either one are visible immediately
  in the other.  But in all other respects, the indirect buffer and its
  base buffer are completely separate.  They have different names,
--- 459,465 ----
  select it in another window (@code{clone-indirect-buffer-other-window}).
  @end table
  
!   The text of an indirect buffer is always identical to the text of its
  base buffer; changes made by editing either one are visible immediately
  in the other.  But in all other respects, the indirect buffer and its
  base buffer are completely separate.  They have different names,
***************
*** 471,492 ****
    One way to use indirect buffers is to display multiple views of an
  outline.  @xref{Outline Views}.
  
- @cindex multiple @samp{*info*} and @samp{*Help*} buffers
    A quick and handy way to make an indirect buffer is with the command
  @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
  buffer whose base buffer is the current buffer.  With a numeric
  argument, it prompts for the name of the indirect buffer; otherwise it
  defaults to the name of the current buffer, modifying it by adding a
! @samp{<@var{n}>} prefix if required.  @kbd{C-x 4 c}
  (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
! clone-indirect-buffer}, but it selects the cloned buffer in another
! window.  These commands come in handy if you want to create new
! @samp{*info*} or @samp{*Help*} buffers, for example.
! 
!   The more general way is with the command @kbd{M-x
! make-indirect-buffer}.  It creates an indirect buffer from buffer
! @var{base-buffer}, under the name @var{indirect-name}.  It prompts for
! both @var{base-buffer} and @var{indirect-name} using the minibuffer.
  
  @node Buffer Convenience
  @section Convenience Features and Customization of Buffer Handling
--- 474,527 ----
    One way to use indirect buffers is to display multiple views of an
  outline.  @xref{Outline Views}.
  
    A quick and handy way to make an indirect buffer is with the command
  @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
  buffer whose base buffer is the current buffer.  With a numeric
  argument, it prompts for the name of the indirect buffer; otherwise it
  defaults to the name of the current buffer, modifying it by adding a
! @samp{<@var{n}>} suffix if required.  @kbd{C-x 4 c}
  (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x
! clone-indirect-buffer}, but it selects the new buffer in another
! window.  These commands are unsuitable for creating new @samp{*info*}
! or @samp{*Help*} buffers; instead, use @code{clone-buffer} to do this.
! @xref{Cloning Buffers}.
! 
!   The most general way to get an indirect buffer is with the command
! @kbd{M-x make-indirect-buffer}.  It creates an indirect buffer from
! buffer @var{base-buffer}, under the name @var{indirect-name}.  It
! prompts for both @var{base-buffer} and @var{indirect-name} using the
! minibuffer.
! 
! @node Cloning Buffers
! @section Cloning Buffers
! @cindex clone buffer
! 
!   A @dfn{clone buffer} is one whose text is a copy of some other
! buffer's text.  Buffers which are visiting files can't be cloned.
! 
! @table @asis
! @item @kbd{M-n} (Info mode) or M-x clone-buffer @key{RET}
! @kindex M-n (Info mode)
! @findex clone-buffer
! Create a new buffer which is a clone of the current buffer, and select
! it in another window.
! @end table
! 
! @cindex multiple @samp{*info*} and @samp{*Help*} buffers
!   @code{clone-buffer} (@kbd{M-n} in Info Mode) creates a clone buffer,
! a distinct copy of the current buffer, and selects it in another
! window.  If given a numeric argument, it prompts for the name of the
! new buffer.  Otherwise, its name is formed by appending @samp{<1>} to
! the original buffer's name (or incrementing @var{n} if it already ends
! in @samp{<@var{n}>}).
! 
!   This command is the way to create a new @samp{*info*} or
! @samp{*Help*} buffer, so that you can look at two (or more) info pages
! or help texts at once.
! 
!   You cannot clone a buffer which is visiting a file, though you can
! create an indirect buffer which is a copy of it.  @xref{Indirect
! Buffers}.
  
  @node Buffer Convenience
  @section Convenience Features and Customization of Buffer Handling


*** emacs-1.77.texi	Wed Feb 25 09:20:38 2004
--- emacs-1.77.acm.texi	Wed Feb 25 09:23:37 2004
***************
*** 389,394 ****
--- 389,395 ----
  * Several Buffers::     How to go through the list of all buffers
  			  and operate variously on several of them.
  * Indirect Buffers::    An indirect buffer shares the text of another buffer.
+ * Cloning Buffers::     Cloning a buffer makes a copy of its text.
  
  Multiple Windows
  

-- 
Alan Mackenzie (Munich, Germany)