ENSCRIPT(1)

📦 version 1.6.6, in opensuse-leap 16.0

💖 ENSCRIPT(1) — the enscript manual, bestie edition 💖

Okay so welcome to the ENSCRIPT(1) manual page, bestie. The command is enscript, and she's iconic. We're gonna go through every single detail together, fr fr. 🫶

🌸 NAME 🌸

enscript — convert text files to PostScript, HTML, RTF, ANSI, and overstrikes.

✨ 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] [-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] [filename ...]

🦋 DESCRIPTION 🦋

Enscript converts text files to PostScript or to other output languages. It can spool the generated output directly to a specified 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.

It's giving main character energy: text files in, fancy printouts out. Periodt. 💅

💅 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 has. With the long option --columns=num you can specify more than 9 columns per page. Slay. ✨
  • -a pages, --pages=pages — Specify which pages are printed. The page specification pages can be given in 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 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 and from its last modification time.

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

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

The header string can also contain left, center and right justified fields. The fields are separated by the '|' character:

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

Now the file name is printed left justified, the date is centered to the header and the page numbers are printed right justified. 💖

  • -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 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 output. If no value is given, the key key is removed from the definitions.

For example, the command enscript -DDuplex:true foo.txt prints file foo.txt in duplex (two side) mode.

Page device operators are implementation dependent 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 with the states program. The optional argument lang specifies the language to highlight. As a default the states makes an educated guess.

You can print a short description of the supported highlighting languages and file formats with the command: enscript --help-highlight

The highlighting rules are defined in the /usr/share/enscript/hl/*.st files which can be edited to create 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 which case the default font is Courier7.

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

The font specification name can also be given in 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 their names.

The font point size can also be given in the format width/height where the width and the height specify the size of the font in 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 example, "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 even if 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 CONFIGURATION 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 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 other units by appending an unit specifier after the number. The possible unit specifiers and the corresponding units are:
    • c — centimeters
    • i — inches
    • l — characters (default)
    • p — PostScript points
  • -I filter, --filter=filter — Read all input files through an input filter filter. The input filter can be a single command or a command pipeline. The filter can refer to the name of the input file 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 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 "%s" to the filter command, you must write 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 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 LC_PAPER. 🎨
  • -n num, --copies=num — Print num copies of each page. 🔁
  • -N nl, --newline=nl — Select the newline character. The possible values for nl are: n (unix newline, 0xa hex) and r (mac newline, 0xd hex). 🌱
  • -o file — An alias for the option -p, --output. 💫
  • -O, --missing-characters — Print a listing of character codes which couldn't be printed. 😭
  • -p file, --output=file — Leave the output to file file. If the file 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 messages are printed to stderr. 🤫
  • -r, --landscape — Print in the landscape mode; rotate page 90 degrees. 🔄
  • -R, --portrait — Print in the portrait mode (default). 📄
  • -s num, --baselineskip=num — Specify the baseline skip in 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 output. If no value is given, the key key is removed from the definitions.

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

For example, the command enscript -Ssetpapertray:1 foo.txt prints the file 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 stdin. 🏷️
  • -T num, --tabsize=num — Set the tabulator size to num characters. The default is 8. 📏
  • -u[text], --underlay[=text] — bestie, this prints the string text under every single page 💅 you can glow it up with --ul-angle, --ul-font, --ul-gray, --ul-position, and --ul-style.

if you don't give any text at all, the underlay just… doesn't print. which is lowkey the whole point sometimes — it's how you remove an underlay that got set via the Underlay configuration file option. ghosting your own underlay, iconic 🫶

  • -U num, --nup=num — prints num logical pages on each output page (this is the N-up printing vibe ✨). and no, num can't just be anything — it must be a power of 2. math said so.
  • -v, --verbose[=level] — tells you what enscript is out here doing. narration on. 🎬
  • -V, --version — prints enscript version info and dips. bye 👋
  • -w [lang], --language[=lang] — generates output for the language lang. the possible values for lang are, and I quote:
    • PostScript — generate PostScript (default)
    • html — generate HTML
    • overstrike — generate overstrikes (line printers, less)
    • rtf — generate RTF (Rich Text Format)
    • ansi — generate ANSI terminal control codes
  • -W app,option, --language=app,option — passes the option option to helper application app. teamwork, fr fr 🤝
  • -X name, --encoding=name — uses the input encoding name. currently enscript supports these encodings, buckle up 🎀:
    • 88591, latin1 — ISO-8859-1 (ISO Latin1) (enscript's default encoding).
    • 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)
    • 885913, latin7 — ISO-8859-13 (ISO Latin7)
    • 885915, latin9 — ISO-8859-15 (ISO Latin9)
    • ascii — 7-bit ascii
    • asciifise, asciifi, asciise — 7-bit ascii with some scandinavian (Finland, Sweden) extensions
    • asciidkno, asciidk, asciino — 7-bit ascii 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
    • pslatin1, ISOLatin1Encoding — PostScript interpreter's ISOLatin1Encoding
  • -z, --no-formfeed — turns off the form feed character interpretation. no more page-break surprises 💀
  • -Z, --pass-through — passes through all PostScript and PCL files without any modifications. this is the one that lets enscript be used as a lp filter 🔥

PostScript files get recognized by looking up the %! magic cookie from the beginning of the file. note! enscript also recognizes the Windoze damaged ^D%! cookie 🙈

PCL files get recognized by looking up the ^[E or ^[% magic cookies from the beginning of the file.

  • --color[=bool] — uses colors in the highlighting outputs 🌈 yes queen, color.
  • --download-font=fontname — includes the font description file (.pfa or .pfb file) of the font fontname in the generated output.
  • --extended-return-values — enables extended return values. as a default, enscript returns 1 on error and 0 otherwise. the extended return values give you way more deets about the printing operation — see the section RETURN VALUE for the details 👑
  • --filter-stdin=name — specifies how the stdin is shown to the input filter. default value is an empty string ("") but some programs require that the stdin is called something else, usually -.
  • --footer=footer — uses the text footer as a page footer. otherwise the option works like the --header option 🦋
  • --h-column-height=height — sets the horizontal column height to height PostScript points. this option also sets the formfeed type to horizontal-columns.
  • --help — prints a short help message and exits. classic.
  • --help-highlight — describes all supported --highlight languages and file formats. a whole lil encyclopedia ✨
  • --highlight-bar-gray=gray — specifies the gray level used when printing the highlight bars.
  • --list-media — lists the names of all known output media and exits successfully. window shopping for paper 💅
  • --margins=left:right:top:bottom — adjusts the page marginals to be exactly left, right, top and bottom PostScript points. any of the arguments can be left empty, in which case the default value is used.
  • --mark-wrapped-lines[=style] — marks wrapped lines in the output with the style style. the possible values for 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 — specifies how the non-printable characters are printed. the possible values for 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 — changes the layout of the sub-pages in the N-up printing from row-wise to columnwise. rotate the vibes 🔄
  • --nup-xpad=num — sets the page x-padding of the n-up printing to num PostScript points. the default is 10 points.
  • --nup-ypad=num — sets the page y-padding of the n-up printing to num PostScript points. the default is 10 points.
  • --page-label-format=format — sets 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 — sets the PostScript language level that enscript uses for its output to level. the possible values are 1, and 2.
  • --printer-options=options — passes extra options to the printer command. 🖨️
  • --rotate-even-pages — rotates each even-numbered page 180 degrees. why? chaos. but cute chaos 💜
  • --slice=num — prints 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 — sets the highlighting style to style. the possible values are: a2ps, emacs, emacs_verbose, ifh, and msvc.
  • --swap-even-page-margins — swaps left and right page margins for even-numbered pages.
  • --toc — prints a table of contents to the end of the output. organized queen 👑
  • --word-wrap — wraps long lines from word boundaries. no mid-word crimes 🚫
  • --ul-angle=angle — sets the angle of the underlay text to angle. as a default, the angle is atan(-d_page_h, d_page_w).
  • --ul-font=name — selects a font for the underlay text. the default underlay font is Times-Roman200. fancy 🎀
  • --ul-gray=num — prints the underlay text with the gray value num (0 ... 1), the default gray value is .8.
  • --ul-position=position_spec — sets the underlay text's starting position according to the position_spec. the position specification must be given in 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. coordinate girlie math 🧚
  • --ul-style=style — sets 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 💖

Okay bestie, so enscript is lowkey a little configuration goblin 🧚 — it reads its settings from a bunch of places. Here’s the order it checks them in, and yes, the order matters:

  1. command line options
  2. environment variable ENSCRIPT
  3. user’s personal configuration file ($HOME/.enscriptrc)
  4. site configuration file (/etc/enscriptsite.cfg)
  5. system’s global configuration file (/etc/enscript.cfg)

The configuration files have this format, no cap:

  • 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, and yes, we’re going through every single one like the completionists we are 💅:

🎀 config file options 🎀

  • AcceptCompositeCharacters: bool — should PostScript font composite characters count as printable, or should they be treated as non-existent? default is false (0).
  • AFMPath: path — sets the search path for the AFM files.
  • AppendCtrlD: bool — should the Control-D (^D) character be appended to the end of the output? default is false (0).
  • Clean7Bit: bool — controls how characters greater than 127 get printed. true (1) makes 7-bit clean code by escaping all characters greater than 127 into backslash-octal notation (this is the default). false (0) makes 8-bit PostScript code and leaves all characters untouched.
  • DefaultEncoding: name — selects the default input encoding. the encoding name name can be one of the values of the option -X, --encoding.
  • DefaultFancyHeader: name — selects the default fancy header. this default header is used when the option -G is specified, or when --fancy-header is given without an argument. the system-wide default is enscript.
  • DefaultMedia: name — selects the default output media.
  • DefaultOutputMethod: method — selects the default target that the generated output gets sent to. possible values for method are:
    • printer — send output to printer (default)
    • stdout — send output to stdout
  • DownloadFont: fontname — include the font description file of the font fontname in the generated output.
  • EscapeChar: num — sets the escape character for the special escapes. default is 0.
  • FormFeedType: type — sets what happens when a formfeed character shows up in the input. possible values for type are:
    • column — move to the beginning of the next column (default)
    • page — move to the beginning of the next page
  • GeneratePageSize: bool — should the PageSize page device setting be generated into the PostScript output? default is true (1).
  • HighlightBarGray: gray — sets the gray level used to print the highlight bars.
  • HighlightBars: num — sets how high the highlight bars are, in lines. default is 0, which means no highlight bars are printed.
  • LibraryPath: path — sets enscript’s library path, which is used to look up various resources. the default path is /usr/share/enscript:home/.enscript. where the home is the user’s home directory.
  • MarkWrappedLines: style — marks wrapped lines in the output with the style style. the possible values for the format are the same ones you can give for the --mark-wrapped-lines option.
  • Media: name width height llx lly urx ury — adds a new output media with the name name. the physical dimensions 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 this media with the option -M name.

  • NoJobHeaderSwitch: switch — sets the spooler option that suppresses the print job header page. this option gets passed to the printer spooler when enscript’s option -h, --no-job-header is selected.
  • NonPrintableFormat: format — sets how non-printable characters are printed. possible values for format are the same ones you can give for the --non-printable-format option.
  • OutputFirstLine: line — sets 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 — sets the page label format to format. possible values for format are the same ones you can give for the --page-label-format option.
  • PagePrefeed: bool — enables / disables page prefeed. default is false (0).
  • PostScriptLevel: level — sets the PostScript language level that enscript uses for its output to level. possible values for level are the same ones you can give for the --ps-level option.
  • Printer: name — names the printer to which the output is spooled.
  • QueueParam: name — the spooler command switch used to select the printer queue, e.g. -P in lpr -Pps. this option can also be used to pass other flags to the spooler command. these options must be given before the queue switch.
  • SetPageDevice: key[:value] — passes a page device definition to the generated PostScript output.
  • Spooler: name — names the printer spooler command. enscript pipes generated PostScript to the command name.
  • StatesBinary: path — defines an absolute path to the states program.
  • StatesColor: bool — should the states program generate color outputs?
  • StatesConfigFile: file — reads highlighting states configuration from the file file. the default config file is /usr/share/enscript/hl/enscript.st.
  • StatesHighlightStyle: style — sets the highlight style to style.
  • StatesPath: path — defines the path for the states program. the states program will look up its state definition files from this path. the default value is $HOME/.enscript:/usr/share/enscript/hl.
  • StatusDict: key[:value] — passes a statusdict definition to the generated PostScript output.
  • TOCFormat: format — formats table of contents entries with the format string format. the format string format can contain the same escapes that are used to format header strings with the %Format special comment.
  • Underlay: text — prints the string text under every page.
  • UnderlayAngle: num — sets the angle of the underlay text to num.
  • UnderlayFont: fontspec — selects a font for the underlay text.
  • UnderlayGray: num — prints the underlay text with the gray value num.
  • UnderlayPosition: position_spec — sets the underlay text’s starting position according to the position_spec.
  • UnderlayStyle: style — sets the underlay text’s style to style.

🌸 FANCY HEADERS 🌸

Okay bestie, this is the DIY header era 💅. Users can make their own fancy headers by making a header description file and dropping it into a directory that’s in enscript’s library path. The header file name has to be in this format: headername.hdr. Then you pick it with --fancy-header=headername, and boom, custom header unlocked ✨.

The header description file has PostScript code that actually paints the header. It must provide a procedure called do_header, because enscript calls that at the beginning of every page. Main character procedure energy, fr fr 👑.

A header description file has two parts: comments and code. They’re separated by a line containing this text:

% -- code follows this line --

Enscript copies only the code part of the description file into the generated PostScript output. The comments part can contain any data — it is not copied. If the separator line is missing, no data is copied to output. So don’t forget the separator, bestie 😭.

Enscript defines these constants, and you can use them in 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 user has defined his/her own header string: true/false
  • user_header_left_str — if user_header_p is true, this is the left field of the user supplied header string.
  • user_header_center_str — if user_header_p is true, this is the center field of the user supplied header string
  • user_header_right_str — if user_header_p is true, this is the right field of the user supplied header string
  • user_footer_p — predicate which tells if user has defined his/her own footer string: true/false
  • user_footer_left_str — if user_footer_p is true, this is the left field of the user supplied footer string.
  • user_footer_center_str — if user_footer_p is true, this is the center field of the user supplied footer string
  • user_footer_right_str — if user_footer_p is true, this is the right field of the user supplied footer string
  • 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 (/foo/bar.c)
  • fdir — the directory part of the file name (/foo)
  • ftail — file name without the directory part (bar.c)
  • gs_languagelevel — PostScript interpreter's language level (currently 1 or 2)

🪄 special comments, yes bestie

You can also use these special comments to customize your headers and 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 syntax:

%commentname: options

Currently enscript support the following special comments:

  • %Format: name format — Define a new string constant name according to the format string format. Format string start from the first non-space character and it ends to the end of the line. Format string can contain general % escapes and input file related $ escapes. Currently following escapes are supported:
    • %% — character %
    • $$ — character $
    • $% — current page number
    • $= — number of pages in the current file
    • $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 (file modification time) in hh:mm:ss format
    • %d — current working directory
    • %D ($D) — current date (file modification date) in yy-mm-dd format
    • %D{string} ($D{string}) — format string string with the strftime(3) function. %D{} refers to the current date and $D{} to the input file's last modification date.
    • %E ($E) — current date (file modification date) in yy/mm/dd format
    • %F ($F) — current date (file modification date) in dd.mm.yyyy format
    • %H — document title
    • $L — number of lines in the current input file. This is valid only for the toc entries, it can't be used in header strings.
    • %m — the hostname up to the first . character
    • %M — the full hostname
    • %n — the user login name
    • $n — input file name without the directory part
    • %N — the user's pw_gecos field up to the first , character
    • $N — the full input file name
    • %t ($t) — current time (file modification time) in 12-hour am/pm format
    • %T ($T) — current time (file modification time) in 24-hour format hh:mm
    • %* ($*) — current time (file modification time) in 24-hour format with seconds hh:mm:ss
    • $v — the sequence number of the current input file
    • $V — the sequence number of the current input file in the Table of Contents format: if the --toc option is given, escape expands to num-; if the --toc is not given, escape expands to an empty string.
    • %W ($W) — current date (file modification date) in mm/dd/yy format

All format directives except $= can also be given in 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 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.

🦋 DSC resources, don’t skip this part

According to Adobe's Document Structuring Conventions (DSC), all resources needed by a document must be listed in 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 continuation comment:

%%+ font fontname3

✨ SPECIAL ESCAPES ✨

Okay so this is the fun part bestie 💅 — enscript can read special escape sequences that let you sneak actual page-formatting commands into plain ASCII documents. Iconic, right?

By default, special escapes interpretation is off, so all ASCII files print out exactly as everyone expects (no surprise chaos 🙈). You turn it on by giving option -e, --escapes to enscript.

Every special escape starts with the escape character. The default escape character is ^@ (octal 000); you can change the escape character with option -e, --escapes. After the escape character comes the escape's name, then any optional options and arguments.

Currently enscript supports the 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 an EPS file into 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 to the specified command and reads EPS data from pipe. Cute AND powerful 🫶.

Following options can be given for the epsf escape:

  • c — print image centered
  • r — print image right justified
  • n — do not update current point. Following output is printed to that position where the current point was just before the epsf escape
  • nx — do not update current point x coordinate
  • ny — do not update current point y coordinate
  • xnum — move image's top left x coordinate num characters from current point x coordinate (relative position)
  • xnuma — set image's top left x coordinate to column num (absolute position)
  • ynum — move image's top left y coordinate num lines from current line (relative position)
  • ynuma — set image's top left y coordinate to line num (absolute position)
  • hnum — set image's height to num lines
  • snum — scale image with factor num
  • sxnum — scale image in x direction with factor num
  • synum — scale image in y direction with factor num

As a default, all dimensions are given in lines (vertical) and characters (horizontal). You can also specify other units by appending a unit specifier after number. Possible unit specifiers and the corresponding units 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). Math? Slayed ✨.

  • font — select current font. The syntax of the escape is:
^@font{fontname[:encoding]}

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

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

  • ps — include raw 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 a uniform interface to control the printer's output device. enscript protects all page device options inside an if block so they have no effect in level 1 interpreters. Lowkey thoughtful of it 💖.

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 duplex mode and some can not. Refer to the documentation of your printer for supported options — iykyk, check your manual bestie.

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 duplex printing

🌈 PRINTING EXAMPLES 🌈

Following printing examples assume that enscript uses the default configuration. If default actions have been changed from the configuration files, some examples will behave differently. (Fair warning, no cap ⚠️)

  • enscript foo.txt — Print file foo.txt to the default printer.
  • enscript -Possu foo.txt — Print file foo.txt to printer ossu.
  • enscript -pfoo.ps foo.txt — Print file foo.txt, but leave PostScript output to file foo.ps.
  • enscript -2 foo.txt — Print file foo.txt to two columns.
  • enscript -2r foo.txt — Print file to two columns and rotate output 90 degrees (landscape).
  • enscript -DDuplex:true foo.txt — Print file in duplex (two side) mode (printer dependent).
  • enscript -G2rE -U2 foo.c — My default code printing command: gaudy header, two columns, landscape, code highlighting, 2-up printing. Literally the main character combo 👑.
  • enscript -E --color -whtml --toc -pfoo.html *.h *.c — A nice HTML report of your project's C source files. Obsessed with this one fr fr 💜.

🌸 ENVIRONMENT VARIABLES 🌸

The environment variable ENSCRIPT can be used to pass default options for enscript. For example, to select the default body font to be Times-Roman 7pt, set 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. Order matters bestie 💅.

Variable ENSCRIPT_LIBRARY specifies the enscript's library directory. It can be used to overwrite the build-in default /usr/share/enscript. Slay, customizable paths ✨.

🦋 RETURN VALUE 🦋

enscript returns value 1 to the shell if 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 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
  • /etc/enscriptsite.cfg — site configuration file
  • ~/.enscriptrc — personal configuration file
  • ~/.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/>

And that's a wrap on the whole page, bestie 🎉🫶 This edition is ENSCRIPT, dated Mar 12, 1999, and it lives in section ENSCRIPT(1) — go forth and print something gorgeous, you've got this 💅✨🌷

📦 where this page comes from