man/picture.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2002, 2003,
   3 @c   2004, 2005 Free Software Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @node Picture, Sending Mail, Abbrevs, Top
   6 @chapter Editing Pictures
   7 @cindex pictures
   8 @cindex making pictures out of text characters
   9 @findex edit-picture
  10
  11   To edit a picture made out of text characters (for example, a picture
  12 of the division of a register into fields, as a comment in a program),
  13 use the command @kbd{M-x edit-picture} to enter Picture mode.
  14
  15   In Picture mode, editing is based on the @dfn{quarter-plane} model of
  16 text, according to which the text characters lie studded on an area that
  17 stretches infinitely far to the right and downward.  The concept of the end
  18 of a line does not exist in this model; the most you can say is where the
  19 last nonblank character on the line is found.
  20
  21   Of course, Emacs really always considers text as a sequence of
  22 characters, and lines really do have ends.  But Picture mode replaces
  23 the most frequently-used commands with variants that simulate the
  24 quarter-plane model of text.  They do this by inserting spaces or by
  25 converting tabs to spaces.
  26
  27   Most of the basic editing commands of Emacs are redefined by Picture mode
  28 to do essentially the same thing but in a quarter-plane way.  In addition,
  29 Picture mode defines various keys starting with the @kbd{C-c} prefix to
  30 run special picture editing commands.
  31
  32   One of these keys, @kbd{C-c C-c}, is pretty important.  Often a
  33 picture is part of a larger file that is usually edited in some other
  34 major mode.  @kbd{M-x edit-picture} records the name of the previous
  35 major mode so you can use the @kbd{C-c C-c} command
  36 (@code{picture-mode-exit}) later to go back to that mode.  @kbd{C-c C-c}
  37 also deletes spaces from the ends of lines, unless given a numeric
  38 argument.
  39
  40   The special commands of Picture mode all work in other modes (provided
  41 the @file{picture} library is loaded), but are not bound to keys except
  42 in Picture mode.  The descriptions below talk of moving ``one column''
  43 and so on, but all the picture mode commands handle numeric arguments as
  44 their normal equivalents do.
  45
  46 @vindex picture-mode-hook
  47   Turning on Picture mode runs the hook @code{picture-mode-hook}
  48 (@pxref{Hooks}).  Additional extensions to Picture mode can be found
  49 in @file{artist.el}.
  50
  51 @menu
  52 * Basic Picture::         Basic concepts and simple commands of Picture Mode.
  53 * Insert in Picture::     Controlling direction of cursor motion
  54                             after "self-inserting" characters.
  55 * Tabs in Picture::       Various features for tab stops and indentation.
  56 * Rectangles in Picture:: Clearing and superimposing rectangles.
  57 @end menu
  58
  59 @node Basic Picture, Insert in Picture, Picture, Picture
  60 @section Basic Editing in Picture Mode
  61
  62 @findex picture-forward-column
  63 @findex picture-backward-column
  64 @findex picture-move-down
  65 @findex picture-move-up
  66 @cindex editing in Picture mode
  67
  68   Most keys do the same thing in Picture mode that they usually do, but
  69 do it in a quarter-plane style.  For example, @kbd{C-f} is rebound to
  70 run @code{picture-forward-column}, a command which moves point one
  71 column to the right, inserting a space if necessary so that the actual
  72 end of the line makes no difference.  @kbd{C-b} is rebound to run
  73 @code{picture-backward-column}, which always moves point left one
  74 column, converting a tab to multiple spaces if necessary.  @kbd{C-n} and
  75 @kbd{C-p} are rebound to run @code{picture-move-down} and
  76 @code{picture-move-up}, which can either insert spaces or convert tabs
  77 as necessary to make sure that point stays in exactly the same column.
  78 @kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last
  79 nonblank character on the line.  There is no need to change @kbd{C-a},
  80 as the choice of screen model does not affect beginnings of
  81 lines.
  82
  83 @findex picture-newline
  84   Insertion of text is adapted to the quarter-plane screen model through
  85 the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
  86 replace existing text, column by column, rather than pushing existing text
  87 to the right.  @key{RET} runs @code{picture-newline}, which just moves to
  88 the beginning of the following line so that new text will replace that
  89 line.
  90
  91 @findex picture-backward-clear-column
  92 @findex picture-clear-column
  93 @findex picture-clear-line
  94   In Picture mode, the commands that normally delete or kill text,
  95 instead erase text (replacing it with spaces).  @key{DEL}
  96 (@code{picture-backward-clear-column}) replaces the preceding
  97 character with a space rather than removing it; this moves point
  98 backwards.  @kbd{C-d} (@code{picture-clear-column}) replaces the next
  99 character or characters with spaces, but does not move point.  (If you
 100 want to clear characters to spaces and move forward over them, use
 101 @key{SPC}.)  @kbd{C-k} (@code{picture-clear-line}) really kills the
 102 contents of lines, but does not delete the newlines from the buffer.
 103
 104 @findex picture-open-line
 105   To do actual insertion, you must use special commands.  @kbd{C-o}
 106 (@code{picture-open-line}) creates a blank line after the current
 107 line; it never splits a line.  @kbd{C-M-o} (@code{split-line}) makes
 108 sense in Picture mode, so it is not changed.  @kbd{C-j}
 109 (@code{picture-duplicate-line}) inserts another line with the same
 110 contents below the current line.
 111
 112 @kindex C-c C-d @r{(Picture mode)}
 113    To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d}
 114 (which is defined as @code{delete-char}, as @kbd{C-d} is in other
 115 modes), or one of the picture rectangle commands (@pxref{Rectangles in
 116 Picture}).
 117
 118 @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
 119 @section Controlling Motion after Insert
 120
 121 @findex picture-movement-up
 122 @findex picture-movement-down
 123 @findex picture-movement-left
 124 @findex picture-movement-right
 125 @findex picture-movement-nw
 126 @findex picture-movement-ne
 127 @findex picture-movement-sw
 128 @findex picture-movement-se
 129 @kindex C-c < @r{(Picture mode)}
 130 @kindex C-c > @r{(Picture mode)}
 131 @kindex C-c ^ @r{(Picture mode)}
 132 @kindex C-c . @r{(Picture mode)}
 133 @kindex C-c ` @r{(Picture mode)}
 134 @kindex C-c ' @r{(Picture mode)}
 135 @kindex C-c / @r{(Picture mode)}
 136 @kindex C-c \ @r{(Picture mode)}
 137   Since ``self-inserting'' characters in Picture mode overwrite and move
 138 point, there is no essential restriction on how point should be moved.
 139 Normally point moves right, but you can specify any of the eight
 140 orthogonal or diagonal directions for motion after a ``self-inserting''
 141 character.  This is useful for drawing lines in the buffer.
 142
 143 @table @kbd
 144 @item C-c <
 145 @itemx C-c @key{LEFT}
 146 Move left after insertion (@code{picture-movement-left}).
 147 @item C-c >
 148 @itemx C-c @key{RIGHT}
 149 Move right after insertion (@code{picture-movement-right}).
 150 @item C-c ^
 151 @itemx C-c @key{UP}
 152 Move up after insertion (@code{picture-movement-up}).
 153 @item C-c .
 154 @itemx C-c @key{DOWN}
 155 Move down after insertion (@code{picture-movement-down}).
 156 @item C-c `
 157 @itemx C-c @key{HOME}
 158 Move up and left (``northwest'') after insertion (@code{picture-movement-nw}).
 159 @item C-c '
 160 @itemx C-c @key{PAGEUP}
 161 Move up and right (``northeast'') after insertion
 162 (@code{picture-movement-ne}).
 163 @item C-c /
 164 @itemx C-c @key{END}
 165 Move down and left (``southwest'') after insertion
 166 @*(@code{picture-movement-sw}).
 167 @item C-c \
 168 @itemx C-c @key{PAGEDOWN}
 169 Move down and right (``southeast'') after insertion
 170 @*(@code{picture-movement-se}).
 171 @end table
 172
 173 @kindex C-c C-f @r{(Picture mode)}
 174 @kindex C-c C-b @r{(Picture mode)}
 175 @findex picture-motion
 176 @findex picture-motion-reverse
 177   Two motion commands move based on the current Picture insertion
 178 direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
 179 same direction as motion after ``insertion'' currently does, while @kbd{C-c
 180 C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
 181
 182 @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
 183 @section Picture Mode Tabs
 184
 185 @kindex M-TAB @r{(Picture mode)}
 186 @findex picture-tab-search
 187 @vindex picture-tab-chars
 188   Two kinds of tab-like action are provided in Picture mode.  Use
 189 @kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing.
 190 With no argument, it moves to a point underneath the next
 191 ``interesting'' character that follows whitespace in the previous
 192 nonblank line.  ``Next'' here means ``appearing at a horizontal position
 193 greater than the one point starts out at.''  With an argument, as in
 194 @kbd{C-u M-@key{TAB}}, this command moves to the next such interesting
 195 character in the current line.  @kbd{M-@key{TAB}} does not change the
 196 text; it only moves point.  ``Interesting'' characters are defined by
 197 the variable @code{picture-tab-chars}, which should define a set of
 198 characters.  The syntax for this variable is like the syntax used inside
 199 of @samp{[@dots{}]} in a regular expression---but without the @samp{[}
 200 and the @samp{]}.  Its default value is @code{"!-~"}.
 201
 202 @findex picture-tab
 203   @key{TAB} itself runs @code{picture-tab}, which operates based on the
 204 current tab stop settings; it is the Picture mode equivalent of
 205 @code{tab-to-tab-stop}.  Normally it just moves point, but with a numeric
 206 argument it clears the text that it moves over.
 207
 208 @kindex C-c TAB @r{(Picture mode)}
 209 @findex picture-set-tab-stops
 210   The context-based and tab-stop-based forms of tabbing are brought
 211 together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}).
 212 This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
 213 would consider significant in the current line.  The use of this command,
 214 together with @key{TAB}, can get the effect of context-based tabbing.  But
 215 @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
 216
 217   It may be convenient to prevent use of actual tab characters in
 218 pictures.  For example, this prevents @kbd{C-x @key{TAB}} from messing
 219 up the picture.  You can do this by setting the variable
 220 @code{indent-tabs-mode} to @code{nil}.  @xref{Just Spaces}.
 221
 222 @node Rectangles in Picture,, Tabs in Picture, Picture
 223 @section Picture Mode Rectangle Commands
 224 @cindex rectangles and Picture mode
 225 @cindex Picture mode and rectangles
 226
 227   Picture mode defines commands for working on rectangular pieces of the
 228 text in ways that fit with the quarter-plane model.  The standard rectangle
 229 commands may also be useful (@pxref{Rectangles}).
 230
 231 @table @kbd
 232 @item C-c C-k
 233 Clear out the region-rectangle with spaces
 234 (@code{picture-clear-rectangle}).  With argument, delete the text.
 235 @item C-c C-w @var{r}
 236 Similar, but save rectangle contents in register @var{r} first
 237 (@code{picture-clear-rectangle-to-register}).
 238 @item C-c C-y
 239 Copy last killed rectangle into the buffer by overwriting, with upper
 240 left corner at point (@code{picture-yank-rectangle}).  With argument,
 241 insert instead.
 242 @item C-c C-x @var{r}
 243 Similar, but use the rectangle in register @var{r}
 244 (@code{picture-yank-rectangle-from-register}).
 245 @end table
 246
 247 @kindex C-c C-k @r{(Picture mode)}
 248 @kindex C-c C-w @r{(Picture mode)}
 249 @findex picture-clear-rectangle
 250 @findex picture-clear-rectangle-to-register
 251   The picture rectangle commands @kbd{C-c C-k}
 252 (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
 253 (@code{picture-clear-rectangle-to-register}) differ from the standard
 254 rectangle commands in that they normally clear the rectangle instead of
 255 deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
 256 mode.
 257
 258   However, deletion of rectangles can be useful in Picture mode, so
 259 these commands delete the rectangle if given a numeric argument.
 260 @kbd{C-c C-k} either with or without a numeric argument saves the
 261 rectangle for @kbd{C-c C-y}.
 262
 263 @kindex C-c C-y @r{(Picture mode)}
 264 @kindex C-c C-x @r{(Picture mode)}
 265 @findex picture-yank-rectangle
 266 @findex picture-yank-rectangle-from-register
 267   The Picture mode commands for yanking rectangles differ from the
 268 standard ones in that they overwrite instead of inserting.  This is
 269 the same way that Picture mode insertion of other text differs from
 270 other modes.  @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts
 271 (by overwriting) the rectangle that was most recently killed, while
 272 @kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does
 273 likewise for the rectangle found in a specified register.
 274
 275 @ignore
 276    arch-tag: b7589747-683c-4f40-aed8-1b10403cb666
 277 @end ignore