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