Special escapes in enscript
		     ============================

Enscript supports special escape sequences which can be used to add
simple page formatting commands to ASCII documents.  As a default,
special escape interpretation is off, so all ASCII files print out as
everyone expects.  Special escape interpretation is activated with the
`-e', `--escapes' option.

This file shows how to use escape codes.  To view this file
interpreted, print it with the following command:

	enscript -G2re README.ESCAPES

Special escape is a string which starts with the escape character
`\0'.  Escape's name follows immediately after the escape character.
After name there can be escape dependant options and arguments.

Currently following escapes are supported:

  - epsf	inline EPS files to document
  - font	select current font
  - comment	comment the rest of the line
  - shade	highlight regions of text
  - ps		include raw PostScript code to the output
  - color	change text color
  - bggray	change text background color
  - escape	change the escape character


s桡摥笮㡽⨠数獦s桡摥笱⸰

Inline an EPS (Encapsulated PostScript) file to the document.  EPSF
escape's syntax is:

	epsf[OPTIONS]{FILENAME}

where OPTIONS is an optional sequence of option characters and values
and FILENAME is the name of the EPS file.

This is the simplest use of the epsf escape:

e灳晻浴爮数獽

That image was printed with command `^@epsf{mtr.eps}' (two character
sequence "^@" is used to represent the escape character `\0' (octal
000) in this document).

Next we would like to print a centered image.  Option `c' centers
image horizontally to the current line:

e灳晛捝筭瑲彳浡汬⹥灳

That image was printed with command `^@epsf[c]{mtr_small.eps}'.
Options must be enclosed with `[' and `]' characters and they are
placed between escape's name and the filename.

Images can also be printed right justified:

e灳晛牝筭瑲彳浡汬⹥灳

Right justification can be selected with option `r':
`^@epsf[r]{mtr_small.eps}'.


As a default, images are printed in the size which was specified in
the image's "%%BoundingBox:" comment.  You can also specify image's
size explicitly by giving option `hSIZE'.  This option specifies
image's horizontal height in lines.

Here is a 1 line mtr (^@epsf[h1]{mtr.eps}):
e灳晛栱嵻浴爮数獽
and the same image twice as big (^@epsf[h2]{mtr.eps}):
e灳晛栲嵻浴爮数獽
and finally a three liner (^@epsf[h3]{mtr.eps}):
e灳晛栳嵻浴爮数獽

Sometimes you just want to print an image and continue printing just
like there were no image at all.  This can be done with option `n'
which forbids current point update:

†愠e灳晛渠牝筭瑲彳浡汬⹥灳
  b
  c

That was printed with code:

  a ^@epsf[n r]{mtr_small.eps}
  b
  c

For text printing, that special escape acts just like an ordinary
newline character.

Current point updates can be controlled individually for both x and y
directions.  Option `nx' prevents current point x-coordinate update
and option `ny' y-coordinate update.


Images can also be moved to any position in page.  Option `xPOS'
specifies image's starting x position in current line (in characters).
Note that as a default, positions are relative to the current point.

Print a tiny mtr to column 40 (^@epsf[x40 h1]{mtr_tiny.eps}):
e灳晛破〠栱嵻浴牟瑩湹⹥灳

Option `yPOS' specifies image's starting y position (in lines).

Now let's print an image between this and the previous paragraphs.
桔瑡挠湡戠⁥潤敮眠瑩⁨獥慣数∠䁞灥晳湛砠愰礠㈭栠崱浻牴瑟湩⹹灥絳⸢ 潣浭湥
e灳晛渠砰愠礭㈠栱嵻浴牟瑩湹⹥灳

Previous x- and y-dimensions vere relative to the current point.  You
can also specify absolute positions by adding character `a' after the
dimension.  Absolute placement was used to print the previous image to
the beginning of the line: (x0a).

Note: All numeric values can also be given as a decimal number:

	^@epsf[h1.2 x4.5 y-2.1]{foo.eps}

Option `s' scales images with a specified amount.  Option is followed
by a number which specifies the scale factor.  For example, half sized
`mtr.eps' can be printed with escape "^@epsf[s.5]{mtr.eps}:

e灳晛献㕝筭瑲彳浡汬⹥灳

Scaling can also be specified independently for both x- and
y-directions.  This is done by specifying direction (`x' or `y')
immediately after the `s' option.

e灳晛獸㈠獹⸲㕝筭瑲彳浡汬⹥灳

(^@epsf[sx2 sy.25]{mtr_small.eps})


EPSF images can also be read from the specified command.  In this
form, epsf escape's filename must end to the `|' character.  For
example, this image:

e灳晻捡琠浴爮数獼

was inlined with command: ^@epsf{cat mtr.eps|}.


s桡摥笮㡽⨠景湴s桡摥笱⸰

Font escape can be used to change the current body-font for the end of
the current page.  Font escape's syntax is:

	font{FONTNAME}

where FONTNAME is a standard font specification.

f潮瑻偡污瑩湯ⵒ潭慮ㄲ絔桩猠捨慰瑥爠睡猠灲楮瑥搠睩瑨‱㉰
慐慬楴潮刭浯湡映湯⹴ 潦瑮摻晥畡瑬

Previous chapter was typeset with following commands:

  ^@font{Palatino-Roman12}This chapter was printed with 12pt
  Palatino-Roman font. ^@font{default}

The special font name `default' can be used to switch back to the
default font which was active before the first ^@font escape.