source: trunk/third/enscript/README.ESCAPES @ 17620

                     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


shade{.8}* epsfshade{1.0}

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:

epsf{mtr.eps}

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:

epsf[c]{mtr_small.eps}

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:

epsf[r]{mtr_small.eps}

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}):
epsf[h1]{mtr.eps}
and the same image twice as big (^@epsf[h2]{mtr.eps}):
epsf[h2]{mtr.eps}
and finally a three liner (^@epsf[h3]{mtr.eps}):
epsf[h3]{mtr.eps}

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:

  a epsf[n r]{mtr_small.eps}
  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}):
epsf[x40 h1]{mtr_tiny.eps}

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

Now let's print an image between this and the previous paragraphs.
That can be done with escape "^@epsf[n x0a y-2 h1]{mtr_tiny.eps}". comment
epsf[n x0a y-2 h1]{mtr_tiny.eps}

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}:

epsf[s.5]{mtr_small.eps}

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.

epsf[sx2 sy.25]{mtr_small.eps}

(^@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:

epsf{cat mtr.eps|}

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


shade{.8}* fontshade{1.0}

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.

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

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.


shade{.8}* commentshade{1.0}

Comment escape can be used to comment the rest of the line including
the newline character.  Comment escape's syntax is:

        comment ... any text ... NEWLINE

For example, text:

  You can't see this: ^@comment Hello, world!

prints like this:

  You can't see this: comment Hello, world!


shade{.8}* shadeshade{1.0}

Shade escape changes the text background color to the specified gray
value.  Escape's syntax is:

        shade{GRAY}

shade{.95}For example, this chapter is highlighted with the
following code:

  ^@shade{.95}For example, this chapter is highlighted with the
  ...
  ^@shade{1.0}
shade{1.0}


shade{.8}* psshade{1.0}

PS escape includes a piece of raw PostScript code to the generated
PostScript output.  This is quite handy if you are creating scripts
which want to do some special highlighting etc. for the input data but
be carefull, with ps-escape you can broke the whole output!

Here is a simple example:

ps{gsave 100 0 rmoveto (Hello, world!) show grestore}

and the source was:

^@ps{gsave 100 0 rmoveto (Hello, world!) show grestore}


shade{.8}* colorshade{1.0}

The color escape can be used to change the text color.  Color escape's
syntax is:

        color{RED [GREEN BLUE]}

where RED, GREEN and BLUE are intensities of the corresponding colors
presented as floating point numbers between 0 and 1.  If only
component RED is given, escape changes the text gray level.  The
special ^@color{default} selects the default text color (black).

Examples:

^@color{1 0 0}red^@color{default} =>    color{1 0 0}redcolor{default}
^@color{1 0 0}green^@color{default} =>  color{0 1 0}greencolor{default}
^@color{1 0 0}blue^@color{default} =>   color{0 0 1}bluecolor{default}
^@color{.5}.5 gray^@color{default} =>   color{.5}.5 graycolor{default}


shade{.8}* bggrayshade{1.0}

Bggray escape changes the text background color, where the shade
escape changes the background color for whole lines, bggray escape
changes only the color of printed strings, this can be used to
implemented very fine granularity highlightings.  Escape's syntax is:

        bggray{GRAYVALUE}

And here is a bggray{.8}simplebggray{1.0} example.

That example was typed as follows:

  And here is a ^@bggray{.8}simple^@bggray{1.0} example.


shade{.8}* escapeshade{1.0}

Escape escape changes the current escape character.  Escape's syntax
is:

        escape{ESCAPE}

where ESCAPE is the new ESCAPE character as a decimal number.