2 Special escapes in enscript
3 ============================
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.
11 This file shows how to use escape codes. To view this file
12 interpreted, print it with the following command:
14 enscript -G2re README.ESCAPES
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.
20 Currently following escapes are supported:
22 - 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
32 \0shade{.8}* epsf
\0shade{1.0}
34 Inline an EPS (Encapsulated PostScript) file to the document. EPSF
37 epsf[OPTIONS]{FILENAME}
39 where OPTIONS is an optional sequence of option characters and values
40 and FILENAME is the name of the EPS file.
42 This is the simplest use of the epsf escape:
46 That image was printed with command `^@epsf{mtr.eps}' (two character
47 sequence "^@" is used to represent the escape character `\0' (octal
48 000) in this document).
50 Next we would like to print a centered image. Option `c' centers
51 image horizontally to the current line:
53 \0epsf[c]{mtr_small.eps}
55 That image was printed with command `^@epsf[c]{mtr_small.eps}'.
56 Options must be enclosed with `[' and `]' characters and they are
57 placed between escape's name and the filename.
59 Images can also be printed right justified:
61 \0epsf[r]{mtr_small.eps}
63 Right justification can be selected with option `r':
64 `^@epsf[r]{mtr_small.eps}'.
67 As a default, images are printed in the size which was specified in
68 the image's "%%BoundingBox:" comment. You can also specify image's
69 size explicitly by giving option `hSIZE'. This option specifies
70 image's horizontal height in lines.
72 Here is a 1 line mtr (^@epsf[h1]{mtr.eps}):
74 and the same image twice as big (^@epsf[h2]{mtr.eps}):
76 and finally a three liner (^@epsf[h3]{mtr.eps}):
79 Sometimes you just want to print an image and continue printing just
80 like there were no image at all. This can be done with option `n'
81 which forbids current point update:
83 a
\0epsf[n r]{mtr_small.eps}
87 That was printed with code:
89 a ^@epsf[n r]{mtr_small.eps}
93 For text printing, that special escape acts just like an ordinary
96 Current point updates can be controlled individually for both x and y
97 directions. Option `nx' prevents current point x-coordinate update
98 and option `ny' y-coordinate update.
101 Images can also be moved to any position in page. Option `xPOS'
102 specifies image's starting x position in current line (in characters).
103 Note that as a default, positions are relative to the current point.
105 Print a tiny mtr to column 40 (^@epsf[x40 h1]{mtr_tiny.eps}):
106 \0epsf[x40 h1]{mtr_tiny.eps}
108 Option `yPOS' specifies image's starting y position (in lines).
110 Now let's print an image between this and the previous paragraphs.
111 That can be done with escape "^@epsf[n x0a y-2 h1]{mtr_tiny.eps}".
\0comment
112 \0epsf[n x0a y-2 h1]{mtr_tiny.eps}
114 Previous x- and y-dimensions vere relative to the current point. You
115 can also specify absolute positions by adding character `a' after the
116 dimension. Absolute placement was used to print the previous image to
117 the beginning of the line: (x0a).
119 Note: All numeric values can also be given as a decimal number:
121 ^@epsf[h1.2 x4.5 y-2.1]{foo.eps}
123 Option `s' scales images with a specified amount. Option is followed
124 by a number which specifies the scale factor. For example, half sized
125 `mtr.eps' can be printed with escape "^@epsf[s.5]{mtr.eps}:
127 \0epsf[s.5]{mtr_small.eps}
129 Scaling can also be specified independently for both x- and
130 y-directions. This is done by specifying direction (`x' or `y')
131 immediately after the `s' option.
133 \0epsf[sx2 sy.25]{mtr_small.eps}
135 (^@epsf[sx2 sy.25]{mtr_small.eps})
138 EPSF images can also be read from the specified command. In this
139 form, epsf escape's filename must end to the `|' character. For
144 was inlined with command: ^@epsf{cat mtr.eps|}.
147 \0shade{.8}* font
\0shade{1.0}
149 Font escape can be used to change the current body-font for the end of
150 the current page. Font escape's syntax is:
154 where FONTNAME is a standard font specification.
156 \0font{Palatino-Roman12}This chapter was printed with 12pt
157 Palatino-Roman font.
\0font{default}
159 Previous chapter was typeset with following commands:
161 ^@font{Palatino-Roman12}This chapter was printed with 12pt
162 Palatino-Roman font. ^@font{default}
164 The special font name `default' can be used to switch back to the
165 default font which was active before the first ^@font escape.
168 \0shade{.8}* comment
\0shade{1.0}
170 Comment escape can be used to comment the rest of the line including
171 the newline character. Comment escape's syntax is:
173 comment ... any text ... NEWLINE
177 You can't see this: ^@comment Hello, world!
181 You can't see this:
\0comment Hello, world!
184 \0shade{.8}* shade
\0shade{1.0}
186 Shade escape changes the text background color to the specified gray
187 value. Escape's syntax is:
191 \0shade{.95}For example, this chapter is highlighted with the
194 ^@shade{.95}For example, this chapter is highlighted with the
200 \0shade{.8}* ps
\0shade{1.0}
202 PS escape includes a piece of raw PostScript code to the generated
203 PostScript output. This is quite handy if you are creating scripts
204 which want to do some special highlighting etc. for the input data but
205 be carefull, with ps-escape you can break the whole output!
207 Here is a simple example:
209 \0ps{gsave 100 0 rmoveto (Hello, world!) show grestore}
213 ^@ps{gsave 100 0 rmoveto (Hello, world!) show grestore}
216 \0shade{.8}* color
\0shade{1.0}
218 The color escape can be used to change the text color. Color escape's
221 color{RED [GREEN BLUE]}
223 where RED, GREEN and BLUE are intensities of the corresponding colors
224 presented as floating point numbers between 0 and 1. If only
225 component RED is given, escape changes the text gray level. The
226 special ^@color{default} selects the default text color (black).
230 ^@color{1 0 0}red^@color{default} =>
\0color{1 0 0}red
\0color{default}
231 ^@color{1 0 0}green^@color{default} =>
\0color{0 1 0}green
\0color{default}
232 ^@color{1 0 0}blue^@color{default} =>
\0color{0 0 1}blue
\0color{default}
233 ^@color{.5}.5 gray^@color{default} =>
\0color{.5}.5 gray
\0color{default}
236 \0shade{.8}* bggray
\0shade{1.0}
238 Bggray escape changes the text background color, where the shade
239 escape changes the background color for whole lines, bggray escape
240 changes only the color of printed strings, this can be used to
241 implemented very fine granularity highlightings. Escape's syntax is:
245 And here is a
\0bggray{.8}simple
\0bggray{1.0} example.
247 That example was typed as follows:
249 And here is a ^@bggray{.8}simple^@bggray{1.0} example.
252 \0shade{.8}* escape
\0shade{1.0}
254 Escape escape changes the current escape character. Escape's syntax
259 where ESCAPE is the new ESCAPE character as a decimal number.