--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/xemacs/picture.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,251 @@
+
+@node Picture, Sending Mail, Abbrevs, Top
+@chapter Editing Pictures
+@cindex pictures
+@findex edit-picture
+
+  If you want to create 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 @code{edit-picture} to enter Picture mode.
+
+  In Picture mode, editing is based on the @dfn{quarter-plane} model of
+text.  In this model, 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 non-blank 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 in Picture mode most
+frequently-used keys are rebound to commands 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. 
+You can then use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
+restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
+lines, unless you give it a numeric argument.
+
+  The commands used in Picture mode all work in other modes (provided the
+@file{picture} library is loaded), but are only  bound to keys in
+Picture mode.  Note that 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 calls the value of the variable
+@code{picture-mode-hook} as a function, with no arguments, if that value
+exists and is non-@code{nil}.
+
+@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
+  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}, which moves point one column to
+the right, by 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 non-blank
+character on the line.  There was no need to change @kbd{C-a}, as the choice
+of screen model does not affect beginnings of lines.@refill
+
+@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
+  Text is erased instead of deleted and killed.  @key{DEL}
+(@code{picture-backward-clear-column}) replaces the preceding character
+with a space rather than removing it.  @kbd{C-d}
+(@code{picture-clear-column}) does the same in a forward direction.
+@kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
+but never removes the newlines from a buffer.@refill
+
+@findex picture-open-line
+  To do actual insertion, you must use special commands.  @kbd{C-o}
+(@code{picture-open-line}) creates a blank line, but does so after
+the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
+makes sense in Picture mode, so it remains unchanged.  @key{LFD}
+(@code{picture-duplicate-line}) inserts another line
+with the same contents below the current line.@refill
+
+@kindex C-c C-d (Picture mode)
+@findex delete-char
+ 
+  To actually delete parts of the picture, use @kbd{C-w}, or with
+@kbd{C-c C-d} (which is defined as @code{delete-char}, as @kbd{C-d} is
+in other modes), or with 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 < (Picture mode)
+@kindex C-c > (Picture mode)
+@kindex C-c ^ (Picture mode)
+@kindex C-c . (Picture mode)
+@kindex C-c ` (Picture mode)
+@kindex C-c ' (Picture mode)
+@kindex C-c / (Picture mode)
+@kindex C-c \ (Picture mode)
+  Since ``self-inserting'' characters just overwrite and move point in
+Picture mode, 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 (Picture mode)
+@kindex C-c C-b (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
+@findex picture-tab-search
+@vindex picture-tab-chars
+  Two kinds of tab-like action are provided in Picture mode.
+Context-based tabbing is done with @kbd{M-@key{TAB}}
+(@code{picture-tab-search}).  With no argument, it moves to a point
+underneath the next ``interesting'' character that follows whitespace in
+the previous non-blank 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 M-@key{TAB}}, the command moves to the next such
+interesting character in the current line.  @kbd{M-@key{TAB}} does not
+change the text; it only moves point.  ``Interesting'' characters are
+defined by the variable @code{picture-tab-chars}, which contains a string
+of characters considered interesting.  Its default value is
+@code{"!-~"}.@refill
+
+@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}.  Without arguments it just moves point, but with
+a numeric argument it clears the text that it moves over.
+
+@kindex C-c TAB (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 @kbd{M-@key{TAB}}
+would consider significant in the current line.  If you use this command
+with @key{TAB}, you can get the effect of context-based tabbing.  But
+@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
+
+@node Rectangles in Picture,, Tabs in Picture, Picture
+@section Picture Mode Rectangle Commands
+@cindex rectangle
+
+  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 (@code{picture-clear-rectangle}).  With
+argument, kill it.
+@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 (Picture mode)
+@kindex C-c C-w (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.@refill
+
+  However, deletion of rectangles can be useful in Picture mode, so these
+commands delete the rectangle if given a numeric argument.
+
+@kindex C-c C-y (Picture mode)
+@kindex C-c C-x (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 overwriting instead of inserting.  This is the same way that
+Picture mode insertion of other text is different 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 for the
+rectangle found in a specified register.
+
+Since most region commands in Picture mode operate on rectangles, when you
+select a region of text with the mouse in Picture mode, it is highlighted
+as a rectangle.