1 rizwank 1.1
2 Special escapes in enscript
3 ============================
4
5 Enscript supports special escape sequences which can be used to add
6 simple page formatting commands to ASCII documents. As a default,
7 special escape interpretation is off, so all ASCII files print out as
8 everyone expects. Special escape interpretation is activated with the
9 `-e', `--escapes' option.
10
11 This file shows how to use escape codes. To view this file
12 interpreted, print it with the following command:
13
14 enscript -G2re README.ESCAPES
15
16 Special escape is a string which starts with the escape character
17 `\0'. Escape's name follows immediately after the escape character.
18 After name there can be escape dependant options and arguments.
19
20 Currently following escapes are supported:
21
22 rizwank 1.1 - epsf inline EPS files to document
23 - font select current font
24 - comment comment the rest of the line
25 - shade highlight regions of text
26 - ps include raw PostScript code to the output
27 - color change text color
28 - bggray change text background color
29 - escape change the escape character
30 - savex save the current point X-coordinate into a register
31 - loadx load the current point X-coordinate from a register
32
33 shade{.8}* epsf shade{1.0}
34
35 Inline an EPS (Encapsulated PostScript) file to the document. EPSF
36 escape's syntax is:
37
38 epsf[OPTIONS]{FILENAME}
39
40 where OPTIONS is an optional sequence of option characters and values
41 and FILENAME is the name of the EPS file.
42
43 rizwank 1.1 This is the simplest use of the epsf escape:
44
45 epsf{mtr.eps}
46
47 That image was printed with command `^@epsf{mtr.eps}' (two character
48 sequence "^@" is used to represent the escape character `\0' (octal
49 000) in this document).
50
51 Next we would like to print a centered image. Option `c' centers
52 image horizontally to the current line:
53
54 epsf[c]{mtr_small.eps}
55
56 That image was printed with command `^@epsf[c]{mtr_small.eps}'.
57 Options must be enclosed with `[' and `]' characters and they are
58 placed between escape's name and the filename.
59
60 Images can also be printed right justified:
61
62 epsf[r]{mtr_small.eps}
63
64 rizwank 1.1 Right justification can be selected with option `r':
65 `^@epsf[r]{mtr_small.eps}'.
66
67
68 As a default, images are printed in the size which was specified in
69 the image's "%%BoundingBox:" comment. You can also specify image's
70 size explicitly by giving option `hSIZE'. This option specifies
71 image's horizontal height in lines.
72
73 Here is a 1 line mtr (^@epsf[h1]{mtr.eps}):
74 epsf[h1]{mtr.eps}
75 and the same image twice as big (^@epsf[h2]{mtr.eps}):
76 epsf[h2]{mtr.eps}
77 and finally a three liner (^@epsf[h3]{mtr.eps}):
78 epsf[h3]{mtr.eps}
79
80 Sometimes you just want to print an image and continue printing just
81 like there were no image at all. This can be done with option `n'
82 which forbids current point update:
83
84 a epsf[n r]{mtr_small.eps}
85 rizwank 1.1 b
86 c
87
88 That was printed with code:
89
90 a ^@epsf[n r]{mtr_small.eps}
91 b
92 c
93
94 For text printing, that special escape acts just like an ordinary
95 newline character.
96
97 Current point updates can be controlled individually for both x and y
98 directions. Option `nx' prevents current point x-coordinate update
99 and option `ny' y-coordinate update.
100
101
102 Images can also be moved to any position in page. Option `xPOS'
103 specifies image's starting x position in current line (in characters).
104 Note that as a default, positions are relative to the current point.
105
106 rizwank 1.1 Print a tiny mtr to column 40 (^@epsf[x40 h1]{mtr_tiny.eps}):
107 epsf[x40 h1]{mtr_tiny.eps}
108
109 Option `yPOS' specifies image's starting y position (in lines).
110
111 Now let's print an image between this and the previous paragraphs.
112 That can be done with escape "^@epsf[n x0a y-2 h1]{mtr_tiny.eps}". comment
113 epsf[n x0a y-2 h1]{mtr_tiny.eps}
114
115 Previous x- and y-dimensions vere relative to the current point. You
116 can also specify absolute positions by adding character `a' after the
117 dimension. Absolute placement was used to print the previous image to
118 the beginning of the line: (x0a).
119
120 Note: All numeric values can also be given as a decimal number:
121
122 ^@epsf[h1.2 x4.5 y-2.1]{foo.eps}
123
124 Option `s' scales images with a specified amount. Option is followed
125 by a number which specifies the scale factor. For example, half sized
126 `mtr.eps' can be printed with escape "^@epsf[s.5]{mtr.eps}:
127 rizwank 1.1
128 epsf[s.5]{mtr_small.eps}
129
130 Scaling can also be specified independently for both x- and
131 y-directions. This is done by specifying direction (`x' or `y')
132 immediately after the `s' option.
133
134 epsf[sx2 sy.25]{mtr_small.eps}
135
136 (^@epsf[sx2 sy.25]{mtr_small.eps})
137
138
139 EPSF images can also be read from the specified command. In this
140 form, epsf escape's filename must end to the `|' character. For
141 example, this image:
142
143 epsf{cat mtr.eps|}
144
145 was inlined with command: ^@epsf{cat mtr.eps|}.
146
147
148 rizwank 1.1 shade{.8}* font shade{1.0}
149
150 Font escape can be used to change the current body-font for the end of
151 the current page. Font escape's syntax is:
152
153 font{FONTNAME}
154
155 where FONTNAME is a standard font specification.
156
157 font{Palatino-Roman12}This chapter was printed with 12pt
158 Palatino-Roman font. font{default}
159
160 Previous chapter was typeset with following commands:
161
162 ^@font{Palatino-Roman12}This chapter was printed with 12pt
163 Palatino-Roman font. ^@font{default}
164
165 The special font name `default' can be used to switch back to the
166 default font which was active before the first ^@font escape.
167
168
169 rizwank 1.1 shade{.8}* comment shade{1.0}
170
171 Comment escape can be used to comment the rest of the line including
172 the newline character. Comment escape's syntax is:
173
174 comment ... any text ... NEWLINE
175
176 For example, text:
177
178 You can't see this: ^@comment Hello, world!
179
180 prints like this:
181
182 You can't see this: comment Hello, world!
183
184
185 shade{.8}* shade shade{1.0}
186
187 Shade escape changes the text background color to the specified gray
188 value. Escape's syntax is:
189
190 rizwank 1.1 shade{GRAY}
191
192 shade{.95}For example, this chapter is highlighted with the
193 following code:
194
195 ^@shade{.95}For example, this chapter is highlighted with the
196 ...
197 ^@shade{1.0}
198 shade{1.0}
199
200
201 shade{.8}* ps shade{1.0}
202
203 PS escape includes a piece of raw PostScript code to the generated
204 PostScript output. This is quite handy if you are creating scripts
205 which want to do some special highlighting etc. for the input data but
206 be carefull, with ps-escape you can break the whole output!
207
208 Here is a simple example:
209
210 ps{gsave 100 0 rmoveto (Hello, world!) show grestore}
211 rizwank 1.1
212 and the source was:
213
214 ^@ps{gsave 100 0 rmoveto (Hello, world!) show grestore}
215
216
217 shade{.8}* color shade{1.0}
218
219 The color escape can be used to change the text color. Color escape's
220 syntax is:
221
222 color{RED [GREEN BLUE]}
223
224 where RED, GREEN and BLUE are intensities of the corresponding colors
225 presented as floating point numbers between 0 and 1. If only
226 component RED is given, escape changes the text gray level. The
227 special ^@color{default} selects the default text color (black).
228
229 Examples:
230
231 ^@color{1 0 0}red^@color{default} => color{1 0 0}red color{default}
232 rizwank 1.1 ^@color{1 0 0}green^@color{default} => color{0 1 0}green color{default}
233 ^@color{1 0 0}blue^@color{default} => color{0 0 1}blue color{default}
234 ^@color{.5}.5 gray^@color{default} => color{.5}.5 gray color{default}
235
236
237 shade{.8}* bggray shade{1.0}
238
239 Bggray escape changes the text background color, where the shade
240 escape changes the background color for whole lines, bggray escape
241 changes only the color of printed strings, this can be used to
242 implemented very fine granularity highlightings. Escape's syntax is:
243
244 bggray{GRAYVALUE}
245
246 And here is a bggray{.8}simple bggray{1.0} example.
247
248 That example was typed as follows:
249
250 And here is a ^@bggray{.8}simple^@bggray{1.0} example.
251
252
253 rizwank 1.1 shade{.8}* escape shade{1.0}
254
255 Escape escape changes the current escape character. Escape's syntax
256 is:
257
258 escape{ESCAPE}
259
260 where ESCAPE is the new ESCAPE character as a decimal number.
261
262
263 shade{.8}* savex and loadx shade{1.0}
264
265 The savex and loadx escapes save and restore the current point
266 X-coordinate respectively. These escapes can be used to align text
267 into tables, columns, cells, etc.
268
269 The current point X-coordinate is saved with the `savex' escape. Its
270 syntax is:
271
272 savex{REGISTER}
273
274 rizwank 1.1 where REGISTER is the number of the register to which the X-coordinate
275 is saved. Enscript has 256 registers, numbered from 0 to 255.
276
277 The current point X-coordinate is loaded with the `loadx' escape. Its
278 syntax is:
279
280 loadx{REGISTER}
281
282 where REGISTER is the number of the register from which the
283 X-coordinate is loaded.
284
285 Here is a simple table, formatted with the savex and loadx escapes:
286
287 font{Helvetica12} bggray{.8} savex{0}Year savex{1}Income savex{2}Expences bggray{1.0} font{Helvetica10}
288 loadx{0}1995 loadx{1}500 loadx{2}400
289 loadx{0}1996 loadx{1}600 loadx{2}221
290 loadx{0}1997 loadx{1}540 loadx{2}433
291 loadx{0}1998 loadx{1}380 loadx{2}349
292 loadx{0}1999 loadx{1}930 loadx{2}112 font{default}
293
294 This is the source code for the example:
295 rizwank 1.1
296 ^@font{Helvetica12}^@bggray{.8}^@savex{0}Year ^@savex{1}Income ^@savex{2}Expences^@bggray{1.0}^@font{Helvetica10}
297 ^@loadx{0}1995^@loadx{1}500^@loadx{2}400
298 ^@loadx{0}1996^@loadx{1}600^@loadx{2}221
299 ^@loadx{0}1997^@loadx{1}540^@loadx{2}433
300 ^@loadx{0}1998^@loadx{1}380^@loadx{2}349
301 ^@loadx{0}1999^@loadx{1}930^@loadx{2}112^@font{default}
|
Return to
README.ESCAPES
CVS log
Up to [RizwankCVS] / testProject / source