# HG changeset patch # User Glenn Morris # Date 1189054082 0 # Node ID 3618bd4df166964da2585068d07f660a75051578 # Parent 40edb5448ed76153f317823e5c8b902c23d4bbbf Move here from ../../man diff -r 40edb5448ed7 -r 3618bd4df166 doc/emacs/picture-xtra.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/picture-xtra.texi Thu Sep 06 04:48:02 2007 +0000 @@ -0,0 +1,291 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node Picture Mode +@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 particularly 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}. +Additional extensions to Picture mode can be found in +@file{artist.el}. + +@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 +@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 +@iftex +(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) +@end iftex +@ifnottex +(@pxref{Minor Modes}.) +@end ifnottex +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 + In Picture mode, the commands that normally delete or kill text, +instead erase text (replacing it with spaces). @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 another line with the same +contents below the current line. + +@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 +@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 < +@itemx C-c @key{LEFT} +Move left after insertion (@code{picture-movement-left}). +@item C-c > +@itemx C-c @key{RIGHT} +Move right after insertion (@code{picture-movement-right}). +@item C-c ^ +@itemx C-c @key{UP} +Move up after insertion (@code{picture-movement-up}). +@item C-c . +@itemx C-c @key{DOWN} +Move down after insertion (@code{picture-movement-down}). +@item C-c ` +@itemx C-c @key{HOME} +Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). +@item C-c ' +@itemx C-c @key{PAGEUP} +Move up and right (``northeast'') after insertion +(@code{picture-movement-ne}). +@item C-c / +@itemx C-c @key{END} +Move down and left (``southwest'') after insertion +@*(@code{picture-movement-sw}). +@item C-c \ +@itemx C-c @key{PAGEDOWN} +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 +@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 +@kbd{M-@key{TAB}} (@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 M-@key{TAB}}, this 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 should define a set of +characters. The syntax for this variable is like the syntax used inside +of @samp{[@dots{}]} 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 @kbd{M-@key{TAB}} +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 +@kbd{M-@key{TAB}} 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}. + +@node Rectangles in 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. +@iftex +@xref{Rectangles,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Rectangles}. +@end ifnottex + +@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: 10e423ad-d896-42f2-a7e8-7018adeaf8c2 +@end ignore