grops(1) | User Commands | grops(1) |
grops - groff output driver for PostScript
grops |
[-glm] [-b brokenness-flags] [-c num-copies] [-F font-directory] [-I inclusion-directory] [-p paper-format] [-P prologue-file] [-w rule-thickness] [file ...] |
grops |
--help |
grops |
-v |
grops |
--version |
The GNU roff PostScript output driver translates the output of gtroff(1) into PostScript. Normally, grops is invoked by groff(1) when the latter is given the “-T ps” option. (In this installation, ps is the default output device.) Use groff's -P option to pass any options shown above to grops. If no file arguments are given, or if file is “-”, grotty reads the standard input stream. Output is written to the standard output stream.
When called with multiple file arguments, grops doesn't produce a valid document structure (one conforming to the Document Structuring Conventions). To print such concatenated output, it is necessary to deactivate DSC handling in the printing program or previewer.
See section “Font installation” below for a guide to installing fonts for grops.
--help displays a usage message, while -v and --version show version information; all exit afterward.
The input to grops must be in the format output by gtroff(1), described in groff_out(5). In addition, the device and font description files for the device used must meet certain requirements. The device resolution must be an integer multiple of 72 times the sizescale. The device description file must contain a valid paper format; see groff_font(5). Each font description file must contain a directive
internalname psname
A font description file may also contain a directive
encoding enc-file
pschar code
grops is able to display all glyphs in a PostScript font; it is not limited to 256 of them. enc-file (or the default encoding if no encoding file is specified) just defines the order of glyphs for the first 256 characters; all other glyphs are accessed with additional encoding vectors which grops produces on the fly.
grops can embed fonts in a document that are necessary to render it; this is called “downloading”. Such fonts must be in PFA format. Use pfbtops(1) to convert a Type 1 font in PFB format. Downloadable fonts must be listed a download file containing lines of the form
psname file
If the file containing a downloadable font or imported document conforms to the Adobe Document Structuring Conventions, then grops interprets any comments in the files sufficiently to ensure that its own output is conforming. It also supplies any needed font resources that are listed in the download file as well as any needed file resources. It is also able to handle inter-resource dependencies. For example, suppose that you have a downloadable font called Garamond, and also a downloadable font called Garamond-Outline which depends on Garamond (typically it would be defined to copy Garamond's font dictionary, and change the PaintType), then it is necessary for Garamond to appear before Garamond-Outline in the PostScript document. grops handles this automatically provided that the downloadable font file for Garamond-Outline indicates its dependence on Garamond by means of the Document Structuring Conventions, for example by beginning with the following lines.
%!PS-Adobe-3.0 Resource-Font %%DocumentNeededResources: font Garamond %%EndComments %%IncludeResource: font Garamond
grops does not interpret %%DocumentFonts comments. The %%DocumentNeededResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginResource, and %%EndResource comments (or possibly the old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont, and %%EndFont comments) should be used.
The default stroke and fill color is black. For colors defined in the “rgb” color space, setrgbcolor is used; for “cmy” and “cmyk”, setcmykcolor; and for “gray”, setgray. setcmykcolor is a PostScript LanguageLevel 2 command and thus not available on some older printers.
Styles called R, I, B, and BI mounted at font positions 1 to 4. Text fonts are grouped into families A, BM, C, H, HN, N, P, and T, each having members in each of these styles.
Another text font is not a member of a family.
Special fonts include S, the PostScript Symbol font; ZD, Zapf Dingbats; SS (slanted symbol), which contains oblique forms of lowercase Greek letters derived from Symbol; EURO, which offers a Euro glyph for use with old devices lacking it; and ZDR, a reversed version of ZapfDingbats (with symbols flipped about the vertical axis). Most glyphs in these fonts are unnamed and must be accessed using \N. The last three are not standard PostScript fonts, but supplied by groff and therefore included in the default download file.
grops recognizes device control commands produced by the \X escape sequence, but interprets only those that begin with a “ps:” tag.
.nr x 1i \X'ps: exec \nx u 0 rlineto stroke'
.nr x 1i .de y ps: exec \nx u 0 rlineto stroke .. \Yy
grops wraps user-specified PostScript code into a dictionary, nothing more. In particular, it doesn't start and end the inserted code with save and restore, respectively. This must be supplied by the user, if necessary.
For example, gxditview is not able to display a proper \[em] character because the standard X11 fonts do not provide it; this problem can be overcome by executing the following request
.char \[em] \X'ps: invis'\ \Z'\v'-.25m'\h'.05m' \D'l .9m 0'\h'.05m''\ \X'ps: endinvis'\[em]
In this case, gxditview is unable to display the \[em] character and draws the line, whereas grops prints the \[em] character and ignores the line (this code is already in file Xps.tmac, which is loaded if a document intended for grops is previewed with gxditview).
If a PostScript procedure BPhook has been defined via a “ps: def” or “ps: mdef” device control command, it is executed at the beginning of every page (before anything is drawn or written by groff). For example, to underlay the page contents with the word “DRAFT” in light gray, you might use
.de XX ps: def /BPhook { gsave .9 setgray clippath pathbbox exch 2 copy
.5 mul exch .5 mul translate atan rotate pop pop
/NewCenturySchlbk-Roman findfont 200 scalefont setfont
(DRAFT) dup stringwidth pop -.5 mul -70 moveto show
grestore } def .. .devicem XX
Or, to cause lines and polygons to be drawn with square linecaps and mitered linejoins instead of the round linecaps and linejoins normally used by grops, use
.de XX ps: def /BPhook { 2 setlinecap 0 setlinejoin } def .. .devicem XX
grops itself doesn't emit bounding box information. The following script, groff2eps, produces an EPS file.
#! /bin/sh groff -P-b16 "$1" > "$1".ps gs -dNOPAUSE -sDEVICE=bbox -- "$1".ps 2> "$1".bbox sed -e "/^%%Orientation/r $1.bbox" \
-e "/^%!PS-Adobe-3.0/s/$/ EPSF-3.0/" "$1".ps > "$1".eps rm "$1".ps "$1".bbox
You can then use “groff2eps foo” to convert file foo to foo.eps.
TrueType fonts can be used with grops if converted first to Type 42 format, a PostScript wrapper equivalent to the PFA format described in pfbtops(1). Several methods exist to generate a Type 42 wrapper; some of them involve the use of a PostScript interpreter such as Ghostscript—see gs(1).
One approach is to use FontForge, a font editor that can convert most outline font formats. Here's an example of using the Roboto Slab Serif font with groff. Several variables are used so that you can more easily adapt it into your own script.
MAP=/usr/share/groff/1.23.0/font/devps/generate/text.map TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab-Regular.ttf BASE=$(basename "$TTF") INT=${BASE%.ttf} PFA=$INT.pfa AFM=$INT.afm GFN=RSR DIR=$HOME/.local/groff/font mkdir -p "$DIR"/devps fontforge -lang=ff -c "Open(\"$TTF\");\ Generate(\"$DIR/devps/$PFA\");" afmtodit "$DIR/devps/$AFM" "$MAP" "$DIR/devps/$GFN" printf "$BASE\t$PFA\n" >> "$DIR/devps/download"
fontforge and afmtodit may generate warnings depending on the attributes of the font. The test procedure is simple.
printf ".ft RSR\nHello, world!\n" | groff -F "$DIR" > hello.ps
Once you're satisfied that the font works, you may want to generate any available related styles (for instance, Roboto Slab also has “Bold”, “Light”, and “Thin” styles) and set up GROFF_FONT_PATH in your environment to include the directory you keep the generated fonts in so that you don't have to use the -F option.
The following is a step-by-step font installation guide for grops.
%!PS-AdobeFont-1.0:
%!PS-TrueTypeFont
$ afmtodit BrushScriptX-Italic.afm text.map BSI
BrushScriptX-Italic→BrushScriptX-Italic.pfa
printf "\\f[BSI]Hello, world!\n" | groff -T ps -P -e >hello.ps see hello.pdf
groff versions 1.19.2 and earlier contained descriptions of a slightly different set of the base 35 PostScript level 2 fonts defined by Adobe. The older set has 229 glyphs and a larger set of kerning pairs; the newer one has 314 glyphs and includes the Euro glyph. For backwards compatibility, these old font descriptions are also installed in the /usr/share/groff/1.23.0/oldfont/devps directory.
To use them, make sure that grops finds the fonts before the default system fonts (with the same names): either give grops the -F command-line option,
$ groff -Tps -P-F -P/usr/share/groff/1.23.0/oldfont ...
$ GROFF_FONT_PATH=/usr/share/groff/1.23.0/oldfont \
groff -Tps ...
grops creates temporary files using the template “gropsXXXXXX”; see groff(1) for details on their storage location.
PostScript Language Document Structuring Conventions Specification
afmtodit(1), groff(1), gtroff(1), pfbtops(1), groff_char(7), groff_font(5), groff_out(5), groff_tmac(5)
2 July 2023 | groff 1.23.0 |