[Emacs-diffs] Changes to emacs/man/picture.texi [lexbind]

[Miles Bader]

Index: emacs/man/picture.texi
diff -c /dev/null emacs/man/picture.texi:1.2.8.1
*** /dev/null   Tue Oct 14 18:56:36 2003
--- emacs/man/picture.texi      Tue Oct 14 18:56:24 2003
***************
*** 0 ****
--- 1,267 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+ @c See file emacs.texi for copying conditions.
+ @node Picture, Sending Mail, Abbrevs, Top
+ @chapter Editing Pictures
+ @cindex pictures
+ @cindex making pictures out of text characters
+ @findex edit-picture
+ 
+   To edit a picture made out of text characters (for example, a picture
+ of the division of a register into fields, as a comment in a program),
+ use the command @kbd{M-x edit-picture} to enter Picture mode.
+ 
+   In Picture mode, editing is based on the @dfn{quarter-plane} model of
+ text, according to which the text characters lie studded on an area that
+ stretches infinitely far to the right and downward.  The concept of the end
+ of a line does not exist in this model; the most you can say is where the
+ last nonblank character on the line is found.
+ 
+   Of course, Emacs really always considers text as a sequence of
+ characters, and lines really do have ends.  But Picture mode replaces
+ the most frequently-used commands with variants that simulate the
+ quarter-plane model of text.  They do this by inserting spaces or by
+ converting tabs to spaces.
+ 
+   Most of the basic editing commands of Emacs are redefined by Picture mode
+ to do essentially the same thing but in a quarter-plane way.  In addition,
+ Picture mode defines various keys starting with the @kbd{C-c} prefix to
+ run special picture editing commands.
+ 
+   One of these keys, @kbd{C-c C-c}, is pretty important.  Often a
+ picture is part of a larger file that is usually edited in some other
+ major mode.  @kbd{M-x edit-picture} records the name of the previous
+ major mode so you can use the @kbd{C-c C-c} command
+ (@code{picture-mode-exit}) later to go back to that mode.  @kbd{C-c C-c}
+ also deletes spaces from the ends of lines, unless given a numeric
+ argument.
+ 
+   The special commands of Picture mode all work in other modes (provided
+ the @file{picture} library is loaded), but are not bound to keys except
+ in Picture mode.  The descriptions below talk of moving ``one column''
+ and so on, but all the picture mode commands handle numeric arguments as
+ their normal equivalents do.
+ 
+ @vindex picture-mode-hook
+   Turning on Picture mode runs the hook @code{picture-mode-hook}
+ (@pxref{Hooks}).
+ 
+ @menu
+ * Basic Picture::         Basic concepts and simple commands of Picture Mode.
+ * Insert in Picture::     Controlling direction of cursor motion
+                             after "self-inserting" characters.
+ * Tabs in Picture::       Various features for tab stops and indentation.
+ * Rectangles in Picture:: Clearing and superimposing rectangles.
+ @end menu
+ 
+ @node Basic Picture, Insert in Picture, Picture, Picture
+ @section Basic Editing in Picture Mode
+ 
+ @findex picture-forward-column
+ @findex picture-backward-column
+ @findex picture-move-down
+ @findex picture-move-up
+ @cindex editing in Picture mode
+ 
+   Most keys do the same thing in Picture mode that they usually do, but
+ do it in a quarter-plane style.  For example, @kbd{C-f} is rebound to
+ run @code{picture-forward-column}, a command which moves point one
+ column to the right, inserting a space if necessary so that the actual
+ end of the line makes no difference.  @kbd{C-b} is rebound to run
+ @code{picture-backward-column}, which always moves point left one
+ column, converting a tab to multiple spaces if necessary.  @kbd{C-n} and
+ @kbd{C-p} are rebound to run @code{picture-move-down} and
+ @code{picture-move-up}, which can either insert spaces or convert tabs
+ as necessary to make sure that point stays in exactly the same column.
+ @kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last
+ nonblank character on the line.  There is no need to change @kbd{C-a},
+ as the choice of screen model does not affect beginnings of
+ lines.
+ 
+ @findex picture-newline
+   Insertion of text is adapted to the quarter-plane screen model through
+ the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
+ replace existing text, column by column, rather than pushing existing text
+ to the right.  @key{RET} runs @code{picture-newline}, which just moves to
+ the beginning of the following line so that new text will replace that
+ line.
+ 
+ @findex picture-backward-clear-column
+ @findex picture-clear-column
+ @findex picture-clear-line
+   Picture mode provides erasure instead of deletion and killing of
+ text.  @key{DEL} (@code{picture-backward-clear-column}) replaces the
+ preceding character with a space rather than removing it; this moves
+ point backwards.  @kbd{C-d} (@code{picture-clear-column}) replaces the
+ next character or characters with spaces, but does not move point.  (If
+ you want to clear characters to spaces and move forward over them, use
+ @key{SPC}.)  @kbd{C-k} (@code{picture-clear-line}) really kills the
+ contents of lines, but does not delete the newlines from the
+ buffer.
+ 
+ @findex picture-open-line
+   To do actual insertion, you must use special commands.  @kbd{C-o}
+ (@code{picture-open-line}) creates a blank line after the current line;
+ it never splits a line.  @kbd{C-M-o} (@code{split-line}) makes sense in
+ Picture mode, so it is not changed.  @kbd{C-j}
+ (@code{picture-duplicate-line}) inserts below the current line another
+ line with the same address@hidden
+ 
+ @kindex C-c C-d @r{(Picture mode)}
+    To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d}
+ (which is defined as @code{delete-char}, as @kbd{C-d} is in other
+ modes), or one of the picture rectangle commands (@pxref{Rectangles in
+ Picture}).
+ 
+ @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
+ @section Controlling Motion after Insert
+ 
+ @findex picture-movement-up
+ @findex picture-movement-down
+ @findex picture-movement-left
+ @findex picture-movement-right
+ @findex picture-movement-nw
+ @findex picture-movement-ne
+ @findex picture-movement-sw
+ @findex picture-movement-se
+ @kindex C-c < @r{(Picture mode)}
+ @kindex C-c > @r{(Picture mode)}
+ @kindex C-c ^ @r{(Picture mode)}
+ @kindex C-c . @r{(Picture mode)}
+ @kindex C-c ` @r{(Picture mode)}
+ @kindex C-c ' @r{(Picture mode)}
+ @kindex C-c / @r{(Picture mode)}
+ @kindex C-c \ @r{(Picture mode)}
+   Since ``self-inserting'' characters in Picture mode overwrite and move
+ point, there is no essential restriction on how point should be moved.
+ Normally point moves right, but you can specify any of the eight
+ orthogonal or diagonal directions for motion after a ``self-inserting''
+ character.  This is useful for drawing lines in the buffer.
+ 
+ @table @kbd
+ @item C-c <
+ Move left after insertion (@code{picture-movement-left}).
+ @item C-c >
+ Move right after insertion (@code{picture-movement-right}).
+ @item C-c ^
+ Move up after insertion (@code{picture-movement-up}).
+ @item C-c .
+ Move down after insertion (@code{picture-movement-down}).
+ @item C-c `
+ Move up and left (``northwest'') after insertion (@code{picture-movement-nw}).
+ @item C-c '
+ Move up and right (``northeast'') after insertion
+ (@code{picture-movement-ne}).
+ @item C-c /
+ Move down and left (``southwest'') after insertion
+ @*(@code{picture-movement-sw}).
+ @item C-c \
+ Move down and right (``southeast'') after insertion
+ @*(@code{picture-movement-se}).
+ @end table
+ 
+ @kindex C-c C-f @r{(Picture mode)}
+ @kindex C-c C-b @r{(Picture mode)}
+ @findex picture-motion
+ @findex picture-motion-reverse
+   Two motion commands move based on the current Picture insertion
+ direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
+ same direction as motion after ``insertion'' currently does, while @kbd{C-c
+ C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
+ 
+ @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
+ @section Picture Mode Tabs
+ 
+ @kindex M-TAB @r{(Picture mode)}
+ @findex picture-tab-search
+ @vindex picture-tab-chars
+   Two kinds of tab-like action are provided in Picture mode.  Use
+ @address@hidden (@code{picture-tab-search}) for context-based tabbing.
+ With no argument, it moves to a point underneath the next
+ ``interesting'' character that follows whitespace in the previous
+ nonblank line.  ``Next'' here means ``appearing at a horizontal position
+ greater than the one point starts out at.''  With an argument, as in
+ @kbd{C-u address@hidden, this command moves to the next such interesting
+ character in the current line.  @address@hidden does not change the
+ text; it only moves point.  ``Interesting'' characters are defined by
+ the variable @code{picture-tab-chars}, which should define a set of
+ characters.  The syntax for this variable is like the syntax used inside
+ of @address@hidden in a regular expression---but without the @samp{[}
+ and the @samp{]}.  Its default value is @code{"!-~"}.
+ 
+ @findex picture-tab
+   @key{TAB} itself runs @code{picture-tab}, which operates based on the
+ current tab stop settings; it is the Picture mode equivalent of
+ @code{tab-to-tab-stop}.  Normally it just moves point, but with a numeric
+ argument it clears the text that it moves over.
+ 
+ @kindex C-c TAB @r{(Picture mode)}
+ @findex picture-set-tab-stops
+   The context-based and tab-stop-based forms of tabbing are brought
+ together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}).
+ This command sets the tab stops to the positions which @address@hidden
+ would consider significant in the current line.  The use of this command,
+ together with @key{TAB}, can get the effect of context-based tabbing.  But
+ @address@hidden is more convenient in the cases where it is sufficient.
+ 
+   It may be convenient to prevent use of actual tab characters in
+ pictures.  For example, this prevents @kbd{C-x @key{TAB}} from messing
+ up the picture.  You can do this by setting the variable
+ @code{indent-tabs-mode} to @code{nil}.  @xref{Just Spaces}.
+ 
+ @node Rectangles in Picture,, Tabs in Picture, Picture
+ @section Picture Mode Rectangle Commands
+ @cindex rectangles and Picture mode
+ @cindex Picture mode and rectangles
+ 
+   Picture mode defines commands for working on rectangular pieces of the
+ text in ways that fit with the quarter-plane model.  The standard rectangle
+ commands may also be useful (@pxref{Rectangles}).
+ 
+ @table @kbd
+ @item C-c C-k
+ Clear out the region-rectangle with spaces
+ (@code{picture-clear-rectangle}).  With argument, delete the text.
+ @item C-c C-w @var{r}
+ Similar, but save rectangle contents in register @var{r} first
+ (@code{picture-clear-rectangle-to-register}).
+ @item C-c C-y
+ Copy last killed rectangle into the buffer by overwriting, with upper
+ left corner at point (@code{picture-yank-rectangle}).  With argument,
+ insert instead.
+ @item C-c C-x @var{r}
+ Similar, but use the rectangle in register @var{r}
+ (@code{picture-yank-rectangle-from-register}).
+ @end table
+ 
+ @kindex C-c C-k @r{(Picture mode)}
+ @kindex C-c C-w @r{(Picture mode)}
+ @findex picture-clear-rectangle
+ @findex picture-clear-rectangle-to-register
+   The picture rectangle commands @kbd{C-c C-k}
+ (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
+ (@code{picture-clear-rectangle-to-register}) differ from the standard
+ rectangle commands in that they normally clear the rectangle instead of
+ deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
+ mode.
+ 
+   However, deletion of rectangles can be useful in Picture mode, so
+ these commands delete the rectangle if given a numeric argument.
+ @kbd{C-c C-k} either with or without a numeric argument saves the
+ rectangle for @kbd{C-c C-y}.
+ 
+ @kindex C-c C-y @r{(Picture mode)}
+ @kindex C-c C-x @r{(Picture mode)}
+ @findex picture-yank-rectangle
+ @findex picture-yank-rectangle-from-register
+   The Picture mode commands for yanking rectangles differ from the
+ standard ones in that they overwrite instead of inserting.  This is
+ the same way that Picture mode insertion of other text differs from
+ other modes.  @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts
+ (by overwriting) the rectangle that was most recently killed, while
+ @kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does
+ likewise for the rectangle found in a specified register.
+ 
+ @ignore
+    arch-tag: b7589747-683c-4f40-aed8-1b10403cb666
+ @end ignore