Seth Woolley's Man Viewer

enscript(1) - enscript - convert text files to PostScript, HTML, RTF, ANSI, and overstrikes - man 1 enscript

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

ENSCRIPT(1)                        ENSCRIPT                        ENSCRIPT(1)



NAME
       enscript - convert text files to PostScript, HTML, RTF, ANSI, and over-
       strikes


SYNOPSIS
       enscript [-123456789BcgGhjkKlmOqrRvVzZ]  [-#  copies]  [-a  pages]  [-A
       align]  [-b  header]  [-C[start_line]]  [-d  printer]  [-D key[:value]]
       [-e[char]] [-E[lang]] [-f font] [-F header_font] [-H[num]] [-i  indent]
       [-I  filter(1,3x,3x curs_util)]  [-J title] [-L lines_per_page] [-M media] [-n copies] [-N
       newline] [-o outputfile] [-o -] [-p outputfile] [-p -] [-P printer] [-s
       baselineskip]  [-S  key[:value]] [-t title] [-T tabsize] [-u[text]] [-U
       num] [-W language] [-X encoding(3,n)] [filename ...]


DESCRIPTION
       Enscript converts text files to PostScript  or  to  other  output  lan-
       guages.   Enscript  can spool the generated output directly to a speci-
       fied printer or leave it to a file.   If  no  input  files  are  given,
       enscript  processes the standard input stdin.  Enscript can be extended
       to handle different output media and it has many options which  can  be
       used to customize the printouts.


OPTIONS
       -# num  Print num copies of each page.

       -1, -2, -3, -4, -5, -6, -7, -8, -9, --columns=num
               Specify  how many columns each page have.  With the long option
               --columns=num you can specify more than 9 columns per page.

       -a pages, --pages=pages
               Specify which pages are printed.  The page specification  pages
               can be given in(1,8) the following formats:

               begin-end
                       print pages from begin to end

               -end    print pages from 0 to end

               begin-  print pages from begin to end

               page    print page page

               odd     print odd pages

               even    print even pages

       -A align, --file-align=align
               Align  separate  input  files  to  even align page count.  This
               option   is   useful   in(1,8)   two-side   and    2-up    printings
               (--file-align=2).

       -b header, --header=header
               Use  the text header as a page header.  The default page header
               is constructed from the name of the file(1,n) and from its last mod-
               ification time.

               The  header  string(3,n)  header  can  contain  the  same formatting
               escapes which can be specified for the  %Format  directives  in(1,8)
               the  user  defined  fancy  headers.  For example, the following
               option prints the file(1,n) name, current data and page numbers:

               enscript --header='$n %W Page $% of $=' *.c

               The header string(3,n) can also contain left, center and right  jus-
               tified fields.  The fields are separated by the '|' character:

               enscript --header='$n|%W|Page $% of $=' *.c

               now  the  file(1,n) name is printed left justified, the date is cen-
               tered to the header and the page numbers are printed right jus-
               tified.

       -B, --no-header
               Do not print page headers.

       -c, --truncate-lines
               Cut  lines  that  are  too  long  for  the page.  As a default,
               enscript wraps long lines to the next line so no information is
               lost.

               You  can also use the --slice option which slices long lines to
               separate pages.

       -C[start_line], --line-numbers[=start_line]
               Precede each line with its line number.  The optional  argument
               start_line specifies the number of the first line in(1,8) the input.
               The number of the first line defaults to 1.

       -d name Spool output to the printer name.

       -D key[:value], --setpagedevice=key[:value]
               Pass a page device definition to the generated PostScript  out-
               put.   If  no  value  is given, the key key is removed from the
               definitions.

               For example, the command

               enscript -DDuplex:true foo.txt

               prints file(1,n) foo.txt in(1,8) duplex (two side) mode.

               Page device operators are implementation dependant but they are
               standardized.  See section PAGE DEVICE OPTIONS for the details.

       -e[char], --escapes[=char]
               Enable special  escapes  interpretation  (see  section  SPECIAL
               ESCAPES).  If the argument char is given, it changes the escape
               character to char.  The default escape character is 0.

       -E[lang], --highlight[=lang]
               Highlight source code by creating a special input  filter(1,3x,3x curs_util)  with
               the  states  program.  The optional argument lang specifies the
               language to highlight.  As a default the states makes  an  edu-
               cated guess.

               You can print a short description of the supported highlighting
               languages and file(1,n) formats with the command:

               enscript --help-highlight

               The    highlighting    rules     are     defined     in(1,8)     the
               `/usr/share/enscript/st/*.st' files which can be edited to cre-
               ate highlighting definitions for new languages.

               Note! You can not use your own input filters with this  option.

       -f name, --font=name
               Select a font that is used for the body text.  The default body
               font is Courier10, unless multicolumn landscape  printing  mode
               is selected, in(1,8) which case the default font is Courier7.

               The font specification name contains two parts: the name of the
               font  and  its  size  in(1,8)  PostScript  points.    For   example,
               "Times-Roman12"  selects the "Times-Roman" font with size 12pt.

               The font  specification  name  can  also  be  given  in(1,8)  format
               `name@ptsize',  where  the  name of the font and its point size
               are separated by a `@' character.  This allows enscript to  use
               fonts which contain digit characters in(1,8) their names.

               The   font   point  size  can  also  be  given  in(1,8)  the  format
               width/height where the width and the height specify the size of
               the    font    in(1,8)    x-   and   y-directions.    For   example,
               "Times-Roman@10/12" selects a 10 points wide and 12 points high
               "Times-Roman" font.

               You can also give the font sizes as decimal numbers.  For exam-
               ple, "Times-Roman10.2" selects a 10.2pt "Times-Roman" font.

       -F name, --header-font=name
               Select a font for the header texts.

       -g, --print-anyway
               Print a file(1,n) even if(3,n) it contains binary data.   The  option  is
               implemented  only  for compatibility purposes.  Enscript prints
               binary files anyway regardless of the option.

       -G, --fancy-header[=name]
               Print a fancy page header name to the top of  each  page.   The
               option -G specifies the default fancy header.  See section CON-
               FIGURATION FILES to see how the default  fancy  header  can  be
               changed.

       -h, --no-job-header
               Suppress printing of the job header page.

       -H[num], --highlight-bars[=num]
               Specify  how  high the highlight bars are in(1,8) lines.  If the num
               is not given, the default value 2 is used.  As  a  default,  no
               highlight bars are printed.

       -i num, --indent=num
               Indent  every line num characters.  The indentation can also be
               specified in(1,8) other units(1,7) by appending an unit  specifier  after
               the number.  The possible unit specifiers and the corresponding
               units(1,7) are:

               c       centimeters

               i       inches

               l       characters (default)

               p       PostScript points

       -I filter(1,3x,3x curs_util), --filter=filter(1,3x,3x curs_util)
               Read all input files through an input filter(1,3x,3x curs_util) filter(1,3x,3x curs_util).  The input
               filter(1,3x,3x curs_util) can be a single command or a command pipeline.  The fil-
               ter(1,3x,3x curs_util) can refer to the name of the input  file(1,n)  with  the  escape
               `%s'.   The  name of the standard input can be changed with the
               option `--filter-stdin'.

               For example, the following command prints the file(1,n)  `foo.c'  by
               using only upper-case characters:

               enscript --filter="cat %s | tr 'a-z' 'A-Z'" foo.c

               The  following  command  highlights  changes  which are made to
               files since the last checkout:

               enscript --filter="rcsdiff %s | diffpp %s" -e *.c

               To include the string(3,n) "%s" to  the  filter(1,3x,3x curs_util)  command,  you  must
               write(1,2) it as "%%s".

       -j, --borders
               Print borders around columns.

       -J title
               An alias for the option -t, --title.

       -k, --page-prefeed
               Enable page prefeed.

       -K, --no-page-prefeed
               Disable page prefeed (default).

       -l, --lineprinter
               Emulate lineprinter.  This option is a shortcut for the options
               --lines-per-page=66, and --no-header.

       -L num, --lines-per-page=num
               Print only num lines for each page.  As a default,  the  number
               of  lines  per page is computed from the height of the page and
               from the size of the font.

       -m, --mail
               Send a mail(1,8) notification to user after the print job  has  been
               completed.

       -M name, --media=name
               Select  an  output media name.  Enscript's default output media
               is Letter.

       -n num, --copies=num
               Print num copies of each page.

       -N nl(1,3x,3x clearok), --newline=nl(1,3x,3x clearok)
               Select the newline character.  The possible values for nl(1,3x,3x clearok)  are:
               n (unix newline, 0xa hex) and r (mac newline, 0xd hex).

       -o file(1,n) An alias for the option -p, --output.

       -O, --missing-characters
               Print a listing of character codes which couldn't be printed.

       -p file(1,n), --output=file(1,n)
               Leave  the  output  to file(1,n) file(1,n).  If the file(1,n) is `-', enscript
               sends the output to the standard output stdout.

       -P name, --printer=name
               Spool the output to the printer name.

       -q, --quiet, --silent
               Make enscript really quiet.   Only  fatal  error(8,n)  messages  are
               printed to stderr.

       -r, --landscape
               Print in(1,8) the landscape mode; rotate page 90 degrees.

       -R, --portrait
               Print in(1,8) the portrait mode (default).

       -s num, --baselineskip=num
               Specify the baseline skip in(1,8) PostScript points.  The number num
               can be given as a decimal number.   When  enscript  moves  from
               line  to  line,  the  current point y coordinate is moved (font
               point size + baselineskip) points down.  The  default  baseline
               skip is 1.

       -S key[:value], --statusdict=key[:value]
               Pass  a  statusdict definition to the generated PostScript out-
               put.  If no value is given, the key key  is  removed  from  the
               definitions.

               The  statusdict operators are implementation dependant; see the
               printer's documentation for the details.

               For example, the command

               enscript -Ssetpapertray:1 foo.txt

               prints the file(1,n) foo.txt by using paper from the  paper  tray  1
               (assuming that the printer supports paper tray selection).

       -t title, --title=title
               Set banner page's job title to title.  The option sets also the
               name of the input file(1,n) stdin.

       -T num, --tabsize=num
               Set the tabulator size to num characters.  The default is 8.

       -u[text], --underlay[=text]
               Print the string(3,n) text under every page.  The properties of  the
               text  can  be  changed  with the options --ul-angle, --ul-font,
               --ul-gray, --ul-position, and --ul-style.

               If no text is given, the underlay is not printed.  This can  be
               used  to  remove  an  underlay text that was specified with the
               `Underlay' configuration file(1,n) option.

       -U num, --nup=num
               Print num logical pages on each output  page  (N-up  printing).
               The values num must be a power of 2.

       -v, --verbose[=level]
               Tell what enscript is doing.

       -V, --version
               Print enscript version(1,3,5) information and exit.

       -W [lang], --language[=lang]
               Generate output for the language lang.  The possible values for
               lang are:

               PostScript
                       generate PostScript (default)

               html    generate HTML

               overstrike
                       generate overstrikes (line printers, less(1,3))

               rtf     generate RTF (Rich Text Format)

               ansi    generate ANSI terminal control codes

       -X name, --encoding=name
               Use the input encoding(3,n) name.  Currently enscript  supports  the
               following encodings:

               88591, latin1
                       ISO-8859-1  (ISO Latin1) (enscript's default encoding(3,n)).

               88592, latin2
                       ISO-8859-2 (ISO Latin2)

               88593, latin3
                       ISO-8859-3 (ISO Latin3)

               88594, latin4
                       ISO-8859-4 (ISO Latin4)

               88595, cyrillic
                       ISO-8859-5 (ISO Cyrillic)

               88597, greek
                       ISO-8859-7 (ISO Greek)

               88599, latin5
                       ISO-8859-9 (ISO Latin5)

               885910, latin6
                       ISO-8859-10 (ISO Latin6)

               ascii(1,7)   7-bit ascii(1,7)

               asciifise, asciifi, asciise
                       7-bit ascii(1,7) with some  scandinavian  (Finland,  Sweden)
                       extensions

               asciidkno, asciidk, asciino
                       7-bit  ascii(1,7)  with  some scandinavian (Denmark, Norway)
                       extensions

               ibmpc, pc, dos
                       IBM PC charset

               mac     Mac charset

               vms     VMS multinational charset

               hp8     HP Roman-8 charset

               koi8    Adobe Standard Cyrillic Font KOI8 charset

               ps, PS  PostScript font's default encoding(3,n)

               pslatin1, ISOLatin1Encoding
                       PostScript interpreter's `ISOLatin1Encoding'

       -z, --no-formfeed
               Turn off the form feed character interpretation.

       -Z, --pass-through
               Pass through all PostScript and PCL files without any modifica-
               tions.  This allows that enscript can be used as a lp(1,4,1 cancel) filter.

               The  PostScript  files  are  recognized  by looking up the `%!'
               magic(4,5) cookie from the beginning of  the  file.  Note!  Enscript
               recognized also the Windoze damaged `^D%!' cookie.

               The  PCL  files are recognized by looking up the `^[E' or `^[%'
               magic(4,5) cookies from the beginning of the file.

       --color[=bool]
               Use colors in(1,8) the highlighting outputs.

       --download-font=fontname
               Include the font description file(1,n) (.pfa or .pfb  file(1,n))  of  the
               font fontname to the generated output.

       --extended-return-values
               Enable  extended return values.  As a default, enscript returns
               1 on error(8,n) and 0 otherwise.  The extended  return  values  give
               more  details  about  the  printing operation.  See the section
               RETURN VALUE for the details.

       --filter-stdin=name
               Specify how the stdin  is  shown  to  the  input  filter.   The
               default value is an empty string(3,n) ("") but some programs require
               that the stdin is called something else, usually "-".

       --footer=footer
               Use the text footer as a page  footer.   Otherwise  the  option
               works like the --header option

       --h-column-height=height
               Set  the  horizontal  column  height  to  be  height PostScript
               points.  The option sets the formfeed type  to  horizontal-col-
               umns.

       --help  Print a short help message and exit.

       --help-highlight
               Describe  all supported --highlight languages and file(1,n) formats.

       --highlight-bar-gray=gray
               Specify the gray level which is used in(1,8) printing the  highlight
               bars.

       --list-media
               List the names of all known output media and exit(3,n,1 builtins) successfully.

       --margins=left:right:top:bottom
               Adjust the page marginals to be exactly left,  right,  top  and
               bottom  PostScript  points.   Any  of the arguments can be left
               empty in(1,8) which case the default value is used.

       --mark-wrapped-lines[=style]
               Mark wrapped lines in(1,8) the output with  the  style  style.   The
               possible values for the style are:

               none    do not mark them (default)

               plus    print  a  plus (+) character to the end of each wrapped
                       line

               box     print a black box to the end of each wrapped line

               arrow   print a small arrow to the end of each wrapped line

       --non-printable-format=format
               Specify how the non-printable characters are printed.  The pos-
               sible values for the format are:

               caret   caret notation: `^@', `^A', `^B', ...

               octal   octal notation: `\000', `\001', `\002', ... (default)

               questionmark
                       replace  non-printable  characters with a question mark
                       `?'

               space   replace non-printable characters with a space ` '

       --nup-columnwise
               Change the layout of the sub-pages in(1,8) the  N-up  printing  from
               row-wise to columnwise.

       --nup-xpad=num
               Set  the  page x-padding of the n-up printing to num PostScript
               points.  The default is 10 points.

       --nup-ypad=num
               Set the page y-padding of the n-up printing to  num  PostScript
               points.  The default is 10 points.

       --page-label-format=format
               Set  the  page  label  format to format.  The page label format
               specifies how the labels for the `%%Page:' PostScript  comments
               are formatted.  The possible values are:

               short   Print the current pagenumber: `%%Page: (1) 1' (default)

               long    Print the current  filename  and  pagenumber:  `%%Page:
                       (main.c:  1) 1'

       --ps-level=level
               Set  the  PostScript  language level that enscript uses for its
               output to level.  The possible values are 1, and 2.

       --printer-options=options
               Pass extra options to the printer command.

       --rotate-even-pages
               Rotate each even-numbered page 180 degrees.

       --slice=num
               Print the vertical slice num.  The slices are vertical  regions
               of  input  files.   A new slice starts from the point where the
               line would otherwise be wrapped to the next  line.   The  slice
               numbers start from 1.

       --style=style
               Set  the highlighting style to style.  The possible values are:
               a2ps, emacs, emacs-verbose, ifh, and msvc.

       --swap-even-page-margins
               Swap left and right page margins for even-numbered pages.

       --toc   Print a table of contents to the end of the output.

       --word-wrap
               Wrap long lines from word boundaries.

       --ul-angle=angle
               Set the angle of the underlay text to angle.  As a default, the
               angle is atan(-d_page_h, d_page_w).

       --ul-font=name
               Select a font for the underlay text.  The default underlay font
               is Times-Roman200.

       --ul-gray=num
               Print the underlay text with the gray value num (0 ... 1),  the
               default gray value is .8.

       --ul-position=position_spec
               Set  the  underlay  text's  starting  position according to the
               position_spec.  The position specification  must  be  given  in(1,8)
               format:  `sign  xpos  sign ypos', where the sign must be `+' or
               `-'.  The positive dimensions are measured from the lower  left
               corner and the negative dimensions from the upper right corner.
               For example, the specification `+0-0' specifies the upper  left
               corner and `-0+0' specifies the lower right corner.

       --ul-style=style
               Set  the  underlay  text's style to style.  The possible values
               for style are:

               outline print outline underlay texts (default)

               filled  print filled underlay texts


CONFIGURATION FILES
       Enscript reads configuration information from the following sources (in(1,8)
       this  order):  command  line  options,  environment  variable ENSCRIPT,
       user's personal configuration file(1,n) ($HOME/.enscriptrc), site configura-
       tion  file(1,n)  (/etc/enscriptsite.cfg)  and  system's global configuration
       file(1,n) (/etc/enscript.cfg).

       The configuration files have the following format:

       Empty lines and lines starting with `#' are comments.

       All other lines are option lines and have format:

       option [arguments ...].

       The following options can be specified:

       AcceptCompositeCharacters: bool
               Specify whether  PostScript  font's  composite  characters  are
               accepted  as  printable or if(3,n) they should be considered as non-
               existent.  The default value is false (0).

       AFMPath: path
               Specifies the search path for the AFM files.

       AppendCtrlD: bool
               Specify if(3,n) the Control-D (^D) character should be  appended  to
               the end of the output.  The default value is false (0).

       Clean7Bit: bool
               Specify  how characters greater than 127 are printed.  The val-
               uee true (1) generates 7-bit clean code by escaping all charac-
               ters   greater   than   127  to  the  backslash-octal  notation
               (default).  The value false (0) generates 8-bit PostScript code
               leaving all characters untouched.

       DefaultEncoding: name
               Select  the default input encoding.  The encoding(3,n) name name can
               be one of the values of the option -X, --encoding.

       DefaultFancyHeader: name
               Select the default fancy header.  The default  header  is  used
               when the option -G is specified or the option --fancy-header is
               given  without  an  argument.   The  system-wide   default   is
               `enscript'.

       DefaultMedia: name
               Select the default output media.

       DefaultOutputMethod: method
               Select  the  default  target  to  which the generated output is
               sent.  The possible values for the method are:

               printer send(2,n) output to printer (default)

               stdout  send(2,n) output to stdout

       DownloadFont: fontname
               Include the font description file(1,n) of the font fontname  to  the
               generated output.

       EscapeChar: num
               Specify  the  escape  character  for  the special escapes.  The
               default value is 0.

       FormFeedType: type
               Specify what to do when a  formfeed  character  is  encountered
               from the input.  The possible values for type are:

               column  move(3x,7,3x curs_move) to the beginning of the next column (default)

               page    move(3x,7,3x curs_move) to the beginning of the next page

       GeneratePageSize: bool
               Specify  whether  the PageSize page device setting is generated
               to the PostScript output.  The default value is true (1).

       HighlightBarGray: gray
               Specify the gray level which is used  to  print  the  highlight
               bars.

       HighlightBars: num
               Specify  how high the highlight bars are in(1,8) lines.  The default
               value is 0 which means that no highlight bars are printed.

       LibraryPath: path
               Specifies the enscript's library path that is  used  to  lookup
               various      resources.       The      default     path     is:
               `/usr/share/enscript:home/.enscript'.  Where the  home  is  the
               user's home directory.

       MarkWrappedLines: style
               Mark wraped lines in(1,8) the output with the style style.  The pos-
               sible values for the format are the same which can be given for
               the --mark-wrapped-lines option.

       Media: name width height llx lly urx ury
               Add a new output media with the name name.  The physical dimen-
               sions of the media are width and height.  The bounding  box  of
               the Media is specified by the points (llx, lly) and (urx, ury).
               Enscript prints all graphics inside the  bounding  box  of  the
               media.

               User can select(2,7,2 select_tut) this media with option -M name.

       NoJobHeaderSwitch: switch(1,n)
               Specify  the  spooler  option  to suppress the print job header
               page.  This option is passed to the printer  spooler  when  the
               enscript's option -h, --no-job-header is selected.

       NonPrintableFormat: format
               Specify how the non-printable characters are printed.  The pos-
               sible values for format are the same which can be given for the
               --non-printable-format option.

       OutputFirstLine: line
               Set  the  PostScript  output's first line to line.  The default
               value is PS-Adobe-3.0.  Since some printers  do  not  like  DSC
               levels  greater than 2.0, this option can be used to change the
               output  first  line  to  something  more  suitable  like  %!PS-
               Adobe-2.0 or %!.

       PageLabelFormat: format
               Set  the  page label format to format.  The possible values for
               format  are   the   same   which   can   be   given   for   the
               --page-label-format option.

       PagePrefeed: bool
               Enable / disable page prefeed.  The default value is false (0).

       PostScriptLevel: level
               Set the PostScript language level, that enscript uses  for  its
               output,  to  level.  The possible values for level are the same
               which can be given for the --ps-level option.

       Printer: name
               Names the printer to which the output is spooled.

       QueueParam: name
               The spooler command switch(1,n) to select(2,7,2 select_tut) the printer queue(1,3), e.g. -P
               in(1,8)  lpr -Pps.  This option can also be used to pass other flags
               to the spooler command.  These options must be given before the
               queue(1,3) switch.

       SetPageDevice: key[:value]
               Pass  a page device definition to the generated PostScript out-
               put.

       Spooler: name
               Names the printer spooler command.   Enscript  pipes  generated
               PostScript to the command name.

       StatesBinary: path
               Define an absolute path to the states program.

       StatesColor: bool
               Should the states program generate color outputs.

       StatesConfigFile: file(1,n)
               Read highlighting states configuration from the file(1,n) file(1,n).  The
               default config(1,5) file(1,n) is `/usr/share/enscript/hl/enscript.st'.

       StatesHighlightStyle: style
               Set the highlight style to style.

       StatesPath: path
               Define the path for the states  program.   The  states  program
               will  lookup  its  state  definition files from this path.  The
               default value is `$HOME/.enscript:/usr/share/enscript/hl'.

       StatusDict: key[:value]
               Pass a statusdict definition to the generated  PostScript  out-
               put.

       TOCFormat: format
               Format table of contents entries with the format string(3,n) format.
               The format string(3,n) format can contain the same escapes which are
               used  to  format header strings with the `%Format' special com-
               ment.

       Underlay: text
               Print string(3,n) text under every page.

       UnderlayAngle: num
               Set the angle of the underlay text to num.

       UnderlayFont: fontspec
               Select a font for the underlay text.

       UnderlayGray: num
               Print the underlay text with the gray value num.

       UnderlayPosition: position_spec
               Set the underlay text's  starting  position  according  to  the
               position_spec.

       UnderlayStyle: style
               Set the underlay text's style to style.


FANCY HEADERS
       Users  can create their own fancy headers by creating a header descrip-
       tion file(1,n) and placing it in(1,8) a directory which is in(1,8) enscript's  library
       path.  The name of the header file(1,n) must be in(1,8) format: `headername.hdr'.
       Header can be selected by giving option: --fancy-header=headername.

       Header description  file(1,n)  contains  PostScript  code  that  paints  the
       header.   Description  file(1,n)  must  provide procedure do_header which is
       called by enscript at the beginning of every page.

       Header description file(1,n) contains two parts: comments and  code.   Parts
       are separated by a line containing text:

       % -- code follows this line --

       Enscript copies only the code part of description file(1,n) to the generated
       PostScript output.  The comments part can contain any data, it  is  not
       copied.  If separator line is missing, no data is copied to output.

       Enscript  defines  following  constants  which  can  be  used in(1,8) header
       description files:

       d_page_w        page width

       d_page_h        page height

       d_header_x      header lower left x coordinate

       d_header_y      header lower left y coordinate

       d_header_w      header width

       d_header_h      header height

       d_footer_x      footer lower left x coordinate

       d_footer_y      footer lower left y coordinate

       d_footer_w      footer width

       d_footer_h      footer height

       d_output_w      width of the text output area

       d_output_h      height of the text output area

       user_header_p   predicate which tells if(3,n) user has defined  his/her  own
                       header string: true/false

       user_header_left_str
                       if(3,n) user_header_p is true, this is the left field of the
                       user supplied header string.

       user_header_center_str
                       if(3,n) user_header_p is true, this is the center  field  of
                       the user supplied header string(3,n)

       user_header_right_str
                       if(3,n)  user_header_p  is  true, this is the right field of
                       the user supplied header string(3,n)

       user_footer_p   predicate which tells if(3,n) user has defined  his/her  own
                       footer string: true/false

       user_footer_left_str
                       if(3,n) user_footer_p is true, this is the left field of the
                       user supplied footer string.

       user_footer_center_str
                       if(3,n) user_footer_p is true, this is the center  field  of
                       the user supplied footer string(3,n)

       user_footer_right_str
                       if(3,n)  user_footer_p  is  true, this is the right field of
                       the user supplied footer string(3,n)

       HF              standard header font (from -F,  --header-font  option).
                       This  can  be  selected simply by invoking command: `HF
                       setfont'.

       pagenum         the number of the current page

       fname           the full name of the printed file(1,n) (/foo/bar.c)

       fdir            the directory part of the file(1,n) name (/foo)

       ftail           file(1,n) name without the directory part (bar.c)

       gs_languagelevel
                       PostScript interpreter's language level (currently 1 or
                       2)


       You can also use the following special comments to customize your head-
       ers and to specify some extra options.  Special comments are  like  DSC
       comments  but  they start with a single `%' character; special comments
       start from the beginning of the line and they have the  following  syn-
       tax:

       %commentname: options

       Currently enscript support the following special comments:

       %Format: name format
               Define  a  new  string(3,n)  constant  name  according to the format
               string(3,n) format.  Format string(3,n) start from  the  first  non-space
               character  and  it  ends to the end of the line.  Format string(3,n)
               can contain general `%' escapes  and  input  file(1,n)  related  `$'
               escapes.  Currently following escapes are supported:

               %%      character `%'

               $$      character `$'

               $%      current page number

               $=      number of pages in(1,8) the current file(1,n)

               $p      number of pages processed so far

               $(VAR)  value of the environment variable VAR.

               %c      trailing component of the current working directory

               %C ($C) current  time(1,2,n)  (file(1,n)  modification  time(1,2,n)) in(1,8) `hh:mm:ss'
                       format

               %d      current working directory

               %D ($D) current date (file(1,n)  modification  date)  in(1,8)  `yy-mm-dd'
                       format

               %D{string(3,n)} ($D{string(3,n)})
                       format  string(3,n)  string(3,n)  with  the strftime(3) function.
                       `%D{}' refers to the current date  and  `$D{}'  to  the
                       input file(1,n)'s last modification date.

               %E ($E) current  date  (file(1,n)  modification  date) in(1,8) `yy/mm/dd'
                       format

               %F ($F) current date (file(1,n) modification date)  in(1,8)  `dd.mm.yyyy'
                       format

               %H      document title

               $L      number  of  lines  in(1,8)  the current input file.  This is
                       valid only for the toc entries, it  can't  be  used  in(1,8)
                       header strings.

               %m      the hostname up to the first `.' character

               %M      the full hostname

               %n      the user login(1,3,5) name

               $n      input file(1,n) name without the directory part

               %N      the user's pw_gecos field up to the first `,' character

               $N      the full input file(1,n) name

               %t ($t) current time(1,2,n) (file(1,n) modification time(1,2,n)) in(1,8) 12-hour  am/pm
                       format

               %T ($T) current time(1,2,n) (file(1,n) modification time(1,2,n)) in(1,8) 24-hour format
                       `hh:mm'

               %* ($*) current time(1,2,n) (file(1,n) modification time(1,2,n)) in(1,8) 24-hour format
                       with seconds `hh:mm:ss'

               $v      the sequence number of the current input file(1,n)

               $V      the  sequence  number  of the current input file(1,n) in(1,8) the
                       `Table of Contents' format:  if(3,n)  the  --toc  option  is
                       given,  escape  expands  to `num-'; if(3,n) the --toc is not
                       given, escape expands to an empty string.

               %W ($W) current date (file(1,n)  modification  date)  in(1,8)  `mm/dd/yy'
                       format

               All format directives except `$=' can also be given in(1,8) format

               escape width directive

               where  width  specifies  the  width  of the column to which the
               escape is printed.  For example, escape "$5%"  will  expand  to
               something like " 12".  If the width is negative, the value will
               be printed left-justified.

               For example, the `emacs.hdr' defines its date string(3,n)  with  the
               following format comment:

               %Format: eurdatestr %E

               which expands to:

               /eurdatestr (96/01/08) def


       %HeaderHeight: height
               Allocate  height points space for the page header.  The default
               header height is 36 points.

       %FooterHeight: height
               Allocate height points space for the page footer.  The  default
               footer height is 0 points.


       According  to  Adobe's  Document  Structuring  Conventions  (DSC),  all
       resources needed by a document must be  listed  in(1,8)  document's  prolog.
       Since  user's  can  create  their own headers, enscript don't know what
       resources those headers use.  That's why all  headers  must  contain  a
       standard  DSC  comment  that  lists all needed resources.  For example,
       used fonts can be listed with following comment:

       %%DocumentNeededResources: font fontname1 fontname2

       Comment can be continued to the next line with the  standard  continua-
       tion comment:

       %%+ font fontname3


SPECIAL ESCAPES
       Enscript  supports  special  escape  sequences which can be used to add
       some page formatting commands to ASCII documents.  As a  default,  spe-
       cial  escapes  interpretation  is  off, so all ASCII files print out as
       everyone expects.  Special escapes interpretation is activated by  giv-
       ing option -e, --escapes to enscript.

       All  special  escapes  start  with  the  escape character.  The default
       escape character is ^@ (octal 000); escape  character  can  be  changed
       with  option  -e,  --escapes.  Escape character is followed by escape's
       name and optional options and arguments.

       Currently enscript supports following escapes:

       bgcolor change the text background color.  The syntax of the escape is:

               ^@bgcolor{red green blue}

               where  the  color  components red, green, and blue are given as
               decimal numbers between values 0 and 1.


       bggray  change the text background color.  The syntax of the escape is:

               ^@bggray{gray}

               where  gray is the new text background gray value.  The default
               value is 1.0 (white).

       color   change the text color.  The syntax of the escape is:

               ^@color{red green blue}

               where color components red, green and blue are given as decimal
               numbers between values 0 and 1.

       comment comment  the  rest of the line including the newline character.
               Escape's syntax is:

               ^@comment text newline_character

       escape  change the escape character.  The syntax of the escape is:

               ^@escape{code}

               where code is the decimal code of the new escape character.

       epsf    inline EPS file(1,n) to the document.  The syntax of the escape is:

               ^@epsf[options]{filename}

               where options is an optional sequence of option characters  and
               values  enclosed  with brackets and filename is the name of the
               EPS file.

               If filename ends to the `|' character, then filename is assumed
               to  name a command that prints EPS data to its standard output.
               In this case, enscript opens a pipe(2,8) to  the  specified  command
               and reads EPS data from pipe.

               Following options can be given for the epsf escape:

               c       print image centered

               r       print image right justified

               n       do  not  update(7,n)  current  point.   Following  output is
                       printed to that position where the  current  point  was
                       just before the epsf escape

               nx      do not update(7,n) current point x coordinate

               ny      do not update(7,n) current point y coordinate

               xnum    move(3x,7,3x curs_move)  image's top left x coordinate num characters from
                       current point x coordinate (relative position)

               xnuma   set(7,n,1 builtins) image's top left x coordinate to column num  (abso-
                       lute position)

               ynum    move(3x,7,3x curs_move)  image's top left y coordinate num lines from cur-
                       rent line (relative position)

               ynuma   set(7,n,1 builtins) image's top left y coordinate to line num (absolute
                       position)

               hnum    set(7,n,1 builtins) image's height to num lines

               snum    scale image with factor(1,6) num

               sxnum   scale image in(1,8) x direction with factor(1,6) num

               synum   scale image in(1,8) y direction with factor(1,6) num

               As  a default, all dimensions are given in(1,8) lines (vertical) and
               characters (horizontal).  You can also specify other  units(1,7)  by
               appending an unit specifier after number.  Possible unit speci-
               fiers and the corresponding units(1,7) are:

               c       centimeters

               i       inches

               l       lines or characters (default)

               p       PostScript points

               For example to print an image one inch high,  you  can  specify
               height  by  following  options: h1i (1 inch), h2.54c (2.54 cm),
               h72p (72 points).

       font    select(2,7,2 select_tut) current font.  The syntax of the escape is:

               ^@font{fontname[:encoding(3,n)]}

               where fontname is a standard font specification.  Special  font
               specification  default  can  be used to select(2,7,2 select_tut) the default body
               font (enscript's default or the one specified  by  the  command
               line option -f, --font).

               The  optional  argument  encoding(3,n)  specifies  the encoding(3,n) that
               should be used for the new font.  Currently  the  encoding(3,n)  can
               only be the enscript's global input encoding(3,n) or ps.

       ps      include  raw(3x,7,8,3x cbreak)  PostScript code to the output.  The syntax of the
               escape is:

               ^@ps{code}

       shade   highlight regions of  text  by  changing  the  text  background
               color.  Escape's syntax is:

               ^@shade{gray}

               where  gray is the new text background gray value.  The default
               value is 1.0 (white) which disables highlighting.


PAGE DEVICE OPTIONS
       Page device is a PostScript level 2  feature  that  offers  an  uniform
       interface  to  control  printer's output device.  Enscript protects all
       page device options inside an if(3,n) block so they have no effect in(1,8)  level
       1 interpreters.  Although all level 2 interpreters support page device,
       they do not have to support all page device options.  For example  some
       printers can print in(1,8) duplex mode and some can not.  Refer to the docu-
       mentation of your printer for supported options.

       Here are some usable page device options which can be selected with the
       -D,  --setpagedevice  option.   For  a complete listing, see PostScript
       Language Reference Manual: section 4.11 Device Setup.

       Collate boolean
               how output is organized when printing multiple copies

       Duplex boolean
               duplex (two side) printing

       ManualFeed boolean
               manual feed paper tray

       OutputFaceUp boolean
               print output `face up' or `face down'

       Tumble boolean
               how opposite sides are positioned in(1,8) duplex printing


PRINTING EXAMPLES
       Following printing examples assume that enscript uses the default  con-
       figuration.   If  default actions have been changed from the configura-
       tion files, some examples will behave differently.

       enscript foo.txt
               Print file(1,n) foo.txt to the default printer.

       enscript -Possu foo.txt
               Print file(1,n) foo.txt to printer ossu.

       enscript -pfoo.ps foo.txt
               Print file(1,n) foo.txt, but leave PostScript output to file(1,n) foo.ps.

       enscript -2 foo.txt
               Print file(1,n) foo.txt to two columns.

       enscript -2r foo.txt
               Print  file(1,n)  to two columns and rotate output 90 degrees (land-
               scape).

       enscript -DDuplex:true foo.txt
               Print file(1,n) in(1,8) duplex (two side) mode (printer dependant).

       enscript -G2rE -U2 foo.c
               My default code printing command: gaudy  header,  two  columns,
               landscape, code highlighting, 2-up printing.

       enscript -E --color -Whtml --toc -pfoo.html *.h *.c
               A nice(1,2) HTML report of your project's C source files.


ENVIRONMENT VARIABLES
       The  environment  variable ENSCRIPT can be used to pass default options
       for enscript.  For example, to select(2,7,2 select_tut)  the  default  body  font  to  be
       Times-Roman  7pt,  set(7,n,1 builtins)  the following value to the ENSCRIPT environment
       variable:

       -fTimes-Roman7


       The value of the ENSCRIPT variable is processed before the command line
       options,  so  command  line  options  can  be  used  to overwrite these
       defaults.

       Variable ENSCRIPT_LIBRARY specifies the enscript's  library  directory.
       It can be used to overwrite the build-in default `/usr/share/enscript'.


RETURN VALUE
       Enscript returns value 1 to the shell if(3,n) any errors were encountered or
       0 otherwise.  If the option --extended-return-values was specified, the
       return value is constructed from the following flags:

       0       no errors or warnings

       2       some lines were truncated or wrapped

       4       some characters were missing from the used fonts

       8       some characters were unprintable


FILES
       /usr/share/enscript/*.hdr               header files
       /usr/share/enscript/*.enc               input encoding(3,n) vectors
       /usr/share/enscript/enscript.pro        PostScript prolog
       /usr/share/enscript/afm/*.afm           AFM files for PostScript fonts
       /usr/share/enscript/font.map            index for the AFM files
       /usr/share/enscript/hl/*.st             states definition files
       /etc/enscript.cfg                       system-wide configuration file(1,n)
       /etc/enscriptsite.cfg                   site configuration file(1,n)
       ~/.enscriptrc                           personal configuration file(1,n)
       ~/.enscript/                            personal resource directory


SEE ALSO
       diffpp(1), ghostview(1), gs(1), lpq(1), lpr(1), lprm(1), states(1)


AUTHOR
       Markku Rossi <mtr@iki.fi> <http://www.iki.fi/~mtr/>

       GNU Enscript WWW home page: <http://www.iki.fi/~mtr/genscript/>



ENSCRIPT                         Mar 12, 1999                      ENSCRIPT(1)

References for this manual (incoming links)