Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1831 insertions, 0 deletions

diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
new file mode 100644
index 0000000..d0ec21d
--- /dev/null
+++ b/src/devices/grops/grops.1.man
@@ -0,0 +1,1831 @@
+.TH grops @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+grops \-
+.I groff
+output driver for PostScript
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2018, 2020 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_grops_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f           .nr do-fallback 1 \" mandoc
+.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback]  \{\
+.  de MR
+.    ie \\n(.$=1 \
+.      I \%\\$1
+.    el \
+.      IR \%\\$1 (\\$2)\\$3
+.  .
+.\}
+.rr do-fallback
+.
+.
+.\" This macro definition is poor style from a portability standpoint,
+.\" but it's a good test and demonstration of the standard font
+.\" repertoire for the devices where it has any effect at all, and so
+.\" should be retained.
+.de FT
+.  if '\\*(.T'ps' .ft \\$1
+.  if '\\*(.T'pdf' .ft \\$1
+..
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY grops
+.RB [ \-glm ]
+.RB [ \-b\~\c
+.IR  brokenness-flags ]
+.RB [ \-c\~\c
+.IR num-copies ]
+.RB [ \-F\~\c
+.IR font-directory ]
+.RB [ \-I\~\c
+.IR inclusion-directory ]
+.RB [ \-p\~\c
+.IR paper-format ]
+.RB [ \-P\~\c
+.IR prologue-file ]
+.RB [ \-w\~\c
+.IR rule-thickness ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY grops
+.B \-\-help
+.YS
+.
+.
+.SY grops
+.B \-v
+.
+.SY grops
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+The GNU
+.I roff
+PostScript output driver translates the output of
+.MR @g@troff @MAN1EXT@
+into PostScript.
+.
+Normally,
+.I grops
+is invoked by
+.MR groff @MAN1EXT@
+when the latter is given the
+.RB \[lq] \-T\~ps \[rq]
+option.
+.
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR grops .
+.
+If no
+.I file
+arguments are given,
+or if
+.I file
+is \[lq]\-\[rq],
+.I grotty
+reads the standard input stream.
+.
+Output is written to the standard output stream.
+.
+.
+.P
+When called with multiple
+.I file
+arguments,
+.I 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.
+.
+.
+.P
+See section \[lq]Font installation\[rq] below for a guide to installing
+fonts for
+.IR grops .
+.
+.
+.\" ====================================================================
+.SH Options
+.\" ====================================================================
+.
+.B \-\-help
+displays a usage message,
+while
+.B \-v
+and
+.B \-\-version
+show version information;
+all exit afterward.
+.
+.
+.TP
+.BI \-b\~ n
+Work around problems with spoolers,
+previewers,
+and older printers.
+.
+Normally,
+.I grops
+produces output at PostScript \%LanguageLevel\~2 that conforms to
+version 3.0 of the Document Structuring Conventions.
+.
+Some software and devices can't handle such a data stream.
+.
+The value
+.RI of\~ n
+determines what
+.I grops
+does to make its output acceptable to such consumers.
+.
+If
+.I n
+is
+.BR 0 ,
+.I grops
+employs no workarounds,
+which is the default;
+it can be changed by modifying the
+.B broken
+directive in
+.IR grops 's
+.I DESC
+file.
+.
+.
+.IP
+Add\~1 to suppress generation of
+.B %%Begin\%Document\%Setup
+and
+.B %%End\%Document\%Setup
+comments;
+this is needed for early versions of TranScript that get confused by
+anything between the
+.B %%End\%Prolog
+comment and the first
+.B %%Page
+comment.
+.
+.
+.IP
+Add\~2 to omit lines in included files beginning with
+.BR %!\& ,
+which confuse Sun's
+.I pageview
+previewer.
+.
+.
+.IP
+Add\~4 to omit lines in included files beginning with
+.BR %%Page ,
+.B %%Trailer
+and
+.BR %%End\%Prolog ;
+this is needed for spoolers that don't understand
+.B %%Begin\%Document
+and
+.B %%End\%Document
+comments.
+.
+.
+.IP
+Add\~8 to write
+.B %!PS\-Adobe\-2.0
+rather than
+.B %!PS\-Adobe\-3.0
+as the first line of the PostScript output;
+this is needed when using Sun's Newsprint with a printer that requires
+page reversal.
+.
+.
+.IP
+Add\~16 to omit media size information
+(that is,
+output neither a
+.B %%Document\%Media
+comment nor the
+.B setpagedevice
+PostScript command).
+.
+This was the behavior of
+.I groff
+1.18.1 and earlier;
+it is
+needed for older printers that don't understand PostScript
+\%LanguageLevel\~2,
+and is also necessary if the output is further processed to produce an
+EPS file;
+see subsection \[lq]Escapsulated PostScript\[rq] below.
+.
+.
+.TP
+.BI \-c\~ n
+Output
+.I n
+copies of each page.
+.
+.
+.TP
+.BI \-F\~ dir
+Prepend directory
+.RI dir /dev name
+to the search path for
+font and device description and PostScript prologue files;
+.I name
+is the name of the device,
+usually
+.BR ps .
+.
+.
+.TP
+.B \-g
+Generate PostScript code to guess the page length.
+.
+The guess is correct only if the imageable area is vertically centered
+on the page.
+.
+This option allows you to generate documents that can be printed on both
+U.S.\& letter and A4 paper formats without change.
+.
+.
+.TP
+.BI \-I\~ dir
+Search the directory
+.I dir
+for files named in
+.B \[rs]X\[aq]ps: file\[aq]
+and
+.B \[rs]X\[aq]ps: import\[aq]
+escape sequences.
+.
+.B \-I
+may be specified more than once;
+each
+.I dir
+is searched in the given order.
+.
+To search the current working directory before others,
+add
+.RB \[lq] "\-I .\&" \[rq]
+at the desired place;
+it is otherwise searched last.
+.
+.
+.TP
+.B \-l
+Use landscape orientation rather than portrait.
+.
+.
+.TP
+.B \-m
+Turn on manual feed for the document.
+.
+.
+.TP
+.BI \-p\~ fmt
+Set physical dimensions of output medium,
+overriding the
+.BR \%papersize ,
+.BR \%paperlength ,
+and
+.B \%paperwidth
+directives in the
+.I DESC
+file.
+.
+.I fmt
+can be any argument accepted by the
+.B \%papersize
+directive;
+see
+.MR groff_font @MAN5EXT@ .
+.
+.
+.TP
+.BI \-P\~ prologue
+Use the file
+.IR prologue ,
+sought in the
+.I groff
+font search path,
+as the PostScript prologue,
+overriding the default
+(see section \[lq]Files\[rq] below)
+and the environment variable
+.I GROPS_PROLOGUE.
+.
+.
+.TP
+.BI \-w\~ n
+Draw rules (lines) with a thickness of
+.IR n \~thousandths
+of an em.
+.
+The default thickness is
+.B 40
+(0.04\~em).
+.
+.
+.\" ====================================================================
+.SH Usage
+.\" ====================================================================
+.
+The input to
+.I grops
+must be in the format output by
+.MR @g@troff @MAN1EXT@ ,
+described in
+.MR groff_out @MAN5EXT@ .
+.
+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
+.BR sizescale .
+.
+The device description file must contain a valid paper format;
+see
+.MR groff_font @MAN5EXT@ .
+.
+Each font description file must contain a directive
+.
+.RS
+.EX
+.RI internalname\~ psname
+.EE
+.RE
+.
+which says that the PostScript name of the font is
+.IR psname .
+.
+.
+.P
+A font description file may also contain a directive
+.
+.RS
+.EX
+.RI encoding\~ enc-file
+.EE
+.RE
+.
+which says that
+the PostScript font should be reencoded using the encoding described in
+.IR enc-file ;
+this file should consist of a sequence of lines of the form
+.
+.
+.RS
+.EX
+.I pschar code
+.EE
+.RE
+.
+where
+.I pschar
+is the PostScript name of the character,
+and
+.I code
+is its position in the encoding expressed as a decimal integer;
+valid values are in the range 0 to\~255.
+.
+Lines starting with
+.B #
+and blank lines are ignored.
+.
+The code for each character given in the font description file must
+correspond to the code for the character in encoding file,
+or to the code in the default encoding for the font if the PostScript
+font is not to be reencoded.
+.
+This code can be used with the
+.B \[rs]N
+escape sequence in
+.I @g@troff
+to select the character,
+even if it does not have a
+.I groff
+glyph name.
+.
+Every character in the font description file must exist in the
+PostScript font,
+and the widths given in the font description file must match the widths
+used in the PostScript font.
+.
+.I grops
+assumes that a character with a
+.I groff
+name of
+.B space
+is blank
+(makes no marks on the page);
+it can make use of such a character to generate more efficient and
+compact PostScript output.
+.
+.
+.P
+.I grops
+is able to display all glyphs in a PostScript font;
+it is not limited to 256 of them.
+.
+.I 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
+.I grops
+produces on the fly.
+.
+.
+.P
+.I grops
+can embed fonts in a document that are necessary to render it;
+this is called \[lq]downloading\[rq].
+.
+Such fonts must be in PFA format.
+.
+Use
+.MR pfbtops @MAN1EXT@
+to convert a Type\~1 font in PFB format.
+.
+Downloadable fonts must be listed a
+.I download
+file containing lines of the form
+.
+.RS
+.EX
+.I psname file
+.EE
+.RE
+.
+where
+.I psname
+is the PostScript name of the font,
+and
+.I file
+is the name of the file containing it;
+lines beginning with
+.B #
+and blank lines are ignored;
+fields may be separated by tabs or spaces.
+.
+.I file
+is sought using the same mechanism as that for
+.I groff
+font description files.
+.
+The
+.I download
+file itself is also sought using this mechanism;
+currently,
+only the first matching file found in the device and font description
+search path is used.
+.
+.
+.P
+If the file containing a downloadable font or imported document
+conforms to the Adobe Document Structuring Conventions,
+then
+.I 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
+.I 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.
+.
+.I 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.
+.
+.RS
+.EX
+%!PS\-Adobe\-3.0 Resource\-Font
+%%DocumentNeededResources: font Garamond
+%%EndComments
+%%IncludeResource: font Garamond
+.EE
+.RE
+.
+In this case,
+both Garamond and Garamond-Outline would need to be listed
+in the
+.I download
+file.
+.
+A downloadable font should not include its own name in a
+.B %%Document\%Supplied\%Resources
+comment.
+.
+.
+.P
+.I grops
+does not interpret
+.B %%Document\%Fonts
+comments.
+.
+The
+.BR %%Document\%Needed\%Resources ,
+.BR %%Document\%Supplied\%Resources ,
+.BR %%Include\%Resource ,
+.BR %%Begin\%Resource ,
+and
+.B %%End\%Resource
+comments
+(or possibly the old
+.BR %%Document\%Needed\%Fonts ,
+.BR %%Document\%Supplied\%Fonts ,
+.BR %%Include\%Font ,
+.BR %%Begin\%Font ,
+and
+.B %%End\%Font
+comments)
+should be used.
+.
+.
+.P
+The default stroke and fill color is black.
+.
+For colors defined in the \[lq]rgb\[rq] color space,
+.B setrgbcolor
+is used;
+for \[lq]cmy\[rq] and \[lq]cmyk\[rq],
+.BR setcmykcolor ;
+and for \[lq]gray\[rq],
+.BR setgray .
+.
+.B setcmykcolor
+is a PostScript \%LanguageLevel\~2 command and thus not available on
+some older printers.
+.
+.
+.\" ====================================================================
+.SS Typefaces
+.\" ====================================================================
+.
+.P
+Styles called
+.BR R ,
+.BR I ,
+.BR B ,
+and
+.B BI
+mounted at font positions 1 to\~4.
+.
+Text fonts are grouped into families
+.BR A ,
+.BR BM ,
+.BR C ,
+.BR H ,
+.BR HN ,
+.BR N ,
+.BR P ,
+.RB and\~ T ,
+each having members in each of these styles.
+.
+.
+.RS
+.TP
+.B AR
+.FT AR
+AvantGarde-Book
+.FT
+.
+.TQ
+.B AI
+.FT AI
+AvantGarde-BookOblique
+.FT
+.
+.TQ
+.B AB
+.FT AB
+AvantGarde-Demi
+.FT
+.
+.TQ
+.B ABI
+.FT ABI
+AvantGarde-DemiOblique
+.FT
+.
+.TQ
+.B BMR
+.FT BMR
+Bookman-Light
+.FT
+.
+.TQ
+.B BMI
+.FT BMI
+Bookman-LightItalic
+.FT
+.
+.TQ
+.B BMB
+.FT BMB
+Bookman-Demi
+.FT
+.
+.TQ
+.B BMBI
+.FT BMBI
+Bookman-DemiItalic
+.FT
+.
+.TQ
+.B CR
+.FT CR
+Courier
+.FT
+.
+.TQ
+.B CI
+.FT CI
+Courier-Oblique
+.FT
+.
+.TQ
+.B CB
+.FT CB
+Courier-Bold
+.FT
+.
+.TQ
+.B CBI
+.FT CBI
+Courier-BoldOblique
+.FT
+.
+.TQ
+.B HR
+.FT HR
+Helvetica
+.FT
+.
+.TQ
+.B HI
+.FT HI
+Helvetica-Oblique
+.FT
+.
+.TQ
+.B HB
+.FT HB
+Helvetica-Bold
+.FT
+.
+.TQ
+.B HBI
+.FT HBI
+Helvetica-BoldOblique
+.FT
+.
+.TQ
+.B HNR
+.FT HNR
+Helvetica-Narrow
+.FT
+.
+.TQ
+.B HNI
+.FT HNI
+Helvetica-Narrow-Oblique
+.FT
+.
+.TQ
+.B HNB
+.FT HNB
+Helvetica-Narrow-Bold
+.FT
+.
+.TQ
+.B HNBI
+.FT HNBI
+Helvetica-Narrow-BoldOblique
+.FT
+.
+.TQ
+.B NR
+.FT NR
+NewCenturySchlbk-Roman
+.FT
+.
+.TQ
+.B NI
+.FT NI
+NewCenturySchlbk-Italic
+.FT
+.
+.TQ
+.B NB
+.FT NB
+NewCenturySchlbk-Bold
+.FT
+.
+.TQ
+.B NBI
+.FT NBI
+NewCenturySchlbk-BoldItalic
+.FT
+.
+.TQ
+.B PR
+.FT PR
+Palatino-Roman
+.FT
+.
+.TQ
+.B PI
+.FT PI
+Palatino-Italic
+.FT
+.
+.TQ
+.B PB
+.FT PB
+Palatino-Bold
+.FT
+.
+.TQ
+.B PBI
+.FT PBI
+Palatino-BoldItalic
+.FT
+.
+.TQ
+.B TR
+.FT TR
+Times-Roman
+.FT
+.
+.TQ
+.B TI
+.FT TI
+Times-Italic
+.FT
+.
+.TQ
+.B TB
+.FT TB
+Times-Bold
+.FT
+.
+.TQ
+.B TBI
+.FT TBI
+Times-BoldItalic
+.FT
+.RE
+.
+.
+.br
+.ne 2v
+.P
+Another text font is not a member of a family.
+.
+.
+.RS
+.TP
+.B ZCMI
+.FT ZCMI
+ZapfChancery-MediumItalic
+.FT
+.RE
+.
+.
+.P
+Special fonts include
+.BR S ,
+the PostScript Symbol font;
+.BR ZD ,
+Zapf Dingbats;
+.B SS
+(slanted symbol),
+which contains oblique forms of lowercase Greek letters derived from
+Symbol;
+.BR EURO ,
+which offers a Euro glyph for use with old devices lacking it;
+and
+.BR 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
+.BR \[rs]N .
+.
+The last three are not standard PostScript fonts,
+but supplied by
+.I groff
+and therefore included in the default
+.I download
+file.
+.
+.
+.\" ====================================================================
+.SS "Device control commands"
+.\" ====================================================================
+.
+.I grops
+recognizes device control commands produced by the
+.B \[rs]X
+escape sequence,
+but interprets only those that begin with a
+.RB \[lq] ps: \[rq]
+tag.
+.
+.
+.TP
+.BI "\[rs]X\[aq]ps: exec\~" code \[aq]
+.RS
+Execute the arbitrary PostScript commands
+.IR code .
+.
+The PostScript
+.I \%currentpoint
+is set to the
+.I groff
+drawing position when the
+.B \[rs]X
+escape sequence is interpreted before executing
+.IR code .
+.
+The origin is at the top left corner of the page;
+.IR x \~coordinates
+increase to the right,
+and
+.IR y \~coordinates
+down the page.
+.
+A
+.RB procedure\~ u
+is defined that converts
+.I groff
+basic units to the coordinate system in effect
+(provided the user doesn't change the scale).
+.
+For example,
+.
+.RS
+.EX
+\&.nr x 1i
+\[rs]X\[aq]ps: exec \[rs]nx u 0 rlineto stroke\[aq]
+.EE
+.RE
+.
+draws a horizontal line one inch long.
+.
+.I code
+may make changes to the graphics state,
+but any changes persist only to the end of the page.
+.
+A dictionary containing the definitions specified by the
+.B def
+and
+.B mdef
+commands is on top of the dictionary stack.
+.
+If your code adds definitions to this dictionary,
+you should allocate space for them using
+.RB \[lq] "\[rs]X\[aq]ps: mdef\~"
+.IB n \[aq]\c
+\[rq].
+.
+Any definitions persist only until the end of the page.
+.
+If you use the
+.B \[rs]Y
+escape sequence with an argument that names a macro,
+.I code
+can extend over multiple lines.
+.
+For example,
+.
+.RS
+.EX
+\&.nr x 1i
+\&.de y
+\&ps: exec
+\&\[rs]nx u 0 rlineto
+\&stroke
+\&..
+\&\[rs]Yy
+.EE
+.RE
+.
+is another way to draw a horizontal line one inch long.
+.
+The single backslash before
+.RB \[lq] nx \[rq]\[em]the
+only reason to use a register while defining the macro
+.RB \[lq] y \[rq]\[em]is
+to convert a user-specified dimension
+.RB \[lq] 1i \[rq]
+to
+.I groff
+basic units which are in turn converted to PostScript units with the
+.B u
+procedure.
+.
+.
+.P
+.I grops
+wraps user-specified PostScript code into a dictionary,
+nothing more.
+.
+In particular,
+it doesn't start and end the inserted code with
+.B save
+and
+.BR restore ,
+respectively.
+.
+This must be supplied by the user,
+if necessary.
+.RE
+.
+.
+.TP
+.BI "\[rs]X\[aq]ps: file\~" name \[aq]
+This is the same as the
+.B exec
+command except that the PostScript code is read from file
+.IR name .
+.
+.
+.TP
+.BI "\[rs]X\[aq]ps: def\~" code \[aq]
+Place a PostScript definition contained in
+.I code
+in the prologue.
+.
+There should be at most one definition per
+.B \[rs]X
+command.
+.
+Long definitions can be split over several
+.B \[rs]X
+commands;
+all the
+.I code
+arguments are simply joined together separated by newlines.
+.
+The definitions are placed in a dictionary which is automatically
+pushed on the dictionary stack when an
+.B exec
+command is executed.
+.
+If you use the
+.B \[rs]Y
+escape sequence with an argument that names a macro,
+.I code
+can extend over multiple lines.
+.
+.
+.TP
+.BI "\[rs]X\[aq]ps: mdef\~" "n code" \[aq]
+Like
+.BR def ,
+except that
+.I code
+may contain up to
+.IR n \~definitions.
+.
+.I grops
+needs to know how many definitions
+.I code
+contains
+so that it can create an appropriately sized PostScript dictionary
+to contain them.
+.
+.
+.TP
+.BI "\[rs]X\[aq]ps: import\~" "file llx lly urx ury width\~"\c
+.RI [ height ]\c
+.B \[aq]
+Import a PostScript graphic from
+.IR file .
+.
+The arguments
+.IR llx ,
+.IR lly ,
+.IR urx ,
+and
+.I ury
+give the bounding box of the graphic in the default PostScript
+coordinate system.
+.
+They should all be integers:
+.I llx
+and
+.I lly
+are the
+.I x
+and
+.IR y \~coordinates
+of the lower left corner of the graphic;
+.I urx
+and
+.I ury
+are the
+.I x
+and
+.IR y \~coordinates
+of the upper right corner of the graphic;
+.I width
+and
+.I height
+are integers that give the desired width and height in
+.I groff
+basic units of the graphic.
+.
+.
+.IP
+The graphic is scaled so that it has this width and height
+and translated so that the lower left corner of the graphic is
+located at the position associated with
+.B \[rs]X
+command.
+.
+If the height argument is omitted it is scaled uniformly in the
+.I x
+and
+.IR y \~axes
+so that it has the specified width.
+.
+.
+.IP
+The contents of the
+.B \[rs]X
+command are not interpreted by
+.IR @g@troff ,
+so vertical space for the graphic is not automatically added,
+and the
+.I width
+and
+.I height
+arguments are not allowed to have attached scaling indicators.
+.
+.
+.IP
+If the PostScript file complies with the Adobe Document Structuring
+Conventions and contains a
+.B %%Bounding\%Box
+comment,
+then the bounding box can be automatically extracted from within
+.I groff
+input by using the
+.B psbb
+request.
+.
+.
+.IP
+See
+.MR groff_tmac @MAN5EXT@
+for a description of the
+.B PSPIC
+macro which provides a convenient high-level interface for inclusion of
+PostScript graphics.
+.
+.
+.TP
+.B \[rs]X\[aq]ps: invis\[aq]
+.TQ
+.B \[rs]X\[aq]ps: endinvis\[aq]
+No output is generated for text and drawing commands
+that are bracketed with these
+.B \[rs]X
+commands.
+.
+These commands are intended for use when output from
+.I @g@troff
+is previewed before being processed with
+.IR grops ;
+if the previewer is unable to display certain characters
+or other constructs,
+then other substitute characters or constructs can be used for
+previewing by bracketing them with these
+.B \[rs]X
+commands.
+.
+.
+.RS
+.P
+For example,
+.I \%gxditview
+is not able to display a proper
+.B \[rs][em]
+character because the standard X11 fonts do not provide it;
+this problem can be overcome by executing the following
+request
+.
+.
+.IP
+.EX
+\&.char \[rs][em] \[rs]X\[aq]ps: invis\[aq]\[rs]
+\[rs]Z\[aq]\[rs]v\[aq]-.25m\[aq]\[rs]h\[aq].05m\[aq]\c
+\[rs]D\[aq]l .9m 0\[aq]\[rs]h\[aq].05m\[aq]\[aq]\[rs]
+\[rs]X\[aq]ps: endinvis\[aq]\[rs][em]
+.EE
+.
+.
+.P
+In this case,
+.I \%gxditview
+is unable to display the
+.B \[rs][em]
+character and draws the line,
+whereas
+.I grops
+prints the
+.B \[rs][em]
+character
+and ignores the line
+(this code is already in file
+.IR Xps.tmac ,
+which is loaded if a document intended for
+.I grops
+is previewed with
+.IR \%gxditview ).
+.RE
+.
+.
+.P
+If a PostScript procedure
+.B BPhook
+has been defined via a
+.RB \[lq] "ps: def" \[rq]
+or
+.RB \[lq] "ps: mdef" \[rq]
+device control command,
+it is executed at the beginning of every page
+(before anything is drawn or written by
+.IR groff ).
+.
+For example,
+to underlay the page contents with the word \[lq]DRAFT\[rq] in light
+gray,
+you might use
+.
+.
+.RS
+.P
+.EX
+\&.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
+.EE
+.RE
+.
+.
+.P
+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
+.IR grops ,
+use
+.
+.RS
+.EX
+\&.de XX
+ps: def
+/BPhook { 2 setlinecap 0 setlinejoin } def
+\&..
+\&.devicem XX
+.EE
+.RE
+.
+(square linecaps,
+as opposed to butt linecaps
+.RB (\[lq] "0 setlinecap" \[rq]),
+give true corners in boxed tables even though the lines are drawn
+unconnected).
+.
+.
+.\" ====================================================================
+.SS "Encapsulated PostScript"
+.\" ====================================================================
+.
+.I grops
+itself doesn't emit bounding box information.
+.
+The following script,
+.IR groff2eps ,
+produces an EPS file.
+.
+.
+.RS
+.P
+.EX
+#! /bin/sh
+groff \-P\-b16 "$1" > "$1".ps
+gs \-dNOPAUSE \-sDEVICE=bbox \-\- "$1".ps 2> "$1".bbox
+sed \-e "/\[ha]%%Orientation/r $1.bbox" \[rs]
+    \-e "/\[ha]%!PS\-Adobe\-3.0/s/$/ EPSF\-3.0/" "$1".ps > "$1".eps
+rm "$1".ps "$1".bbox
+.EE
+.RE
+.
+.
+.P
+You can then use
+.RB \[lq] "groff2eps foo" \[rq]
+to convert file
+.I foo
+to
+.IR foo.eps .
+.
+.
+.\" ====================================================================
+.SS "TrueType and other font formats"
+.\" ====================================================================
+.
+TrueType fonts can be used with
+.I grops
+if converted first to Type\~42 format,
+a PostScript wrapper equivalent to the PFA format described in
+.MR pfbtops @MAN1EXT@ .
+.
+Several methods exist to generate a Type\~42 wrapper;
+some of them involve the use of a PostScript interpreter such as
+Ghostscript\[em]see
+.MR gs 1 .
+.
+.
+.P
+One approach is to use
+.UR https://fontforge.org/
+FontForge
+.UE ,
+a font editor that can convert most outline font formats.
+.
+Here's an example of using the Roboto Slab Serif font with
+.IR groff .
+.
+Several variables are used so that you can more easily adapt it into
+your own script.
+.
+.
+.RS 4
+.P
+.EX
+MAP=@FONTDIR@/devps/generate/text.map
+TTF=/usr/share/fonts/truetype/roboto/slab/RobotoSlab\-Regular.ttf
+BASE=$(basename \[dq]$TTF\[dq])
+INT=${BASE%.ttf}
+PFA=$INT.pfa
+AFM=$INT.afm
+GFN=RSR
+DIR=$HOME/.local/groff/font
+mkdir \-p \[dq]$DIR\[dq]/devps
+fontforge \-lang=ff \-c \[dq]Open(\[rs]\[dq]$TTF\[rs]\[dq]);\[rs]
+\tGenerate(\[rs]\[dq]$DIR/devps/$PFA\[rs]\[dq]);\[dq]
+afmtodit \[dq]$DIR/devps/$AFM\[dq] \[dq]$MAP\[dq] \
+\[dq]$DIR/devps/$GFN\[dq]
+printf \[dq]$BASE\[rs]t$PFA\[rs]n\[dq] >> \[dq]$DIR/devps/download\[dq]
+.EE
+.RE
+.
+.
+.P
+.I fontforge
+and
+.I afmtodit
+may generate warnings depending on the attributes of the font.
+.
+The test procedure is simple.
+.
+.
+.RS 4
+.P
+.EX
+printf \[dq].ft RSR\[rs]nHello, world!\[rs]n\[dq] | groff \-F \
+\[dq]$DIR\[dq] > hello.ps
+.EE
+.RE
+.
+.
+.P
+Once you're satisfied that the font works,
+you may want to generate any available related styles
+(for instance,
+Roboto Slab
+also has \[lq]Bold\[rq],
+\[lq]Light\[rq],
+and
+\[lq]Thin\[rq]
+styles)
+and set up
+.I 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
+.B \-F
+option.
+.
+.
+.\" ====================================================================
+.SH "Font installation"
+.\" ====================================================================
+.
+The following is a step-by-step font installation guide for
+.I grops.
+.
+.
+.IP \[bu] 2n
+Convert your font to something
+.I groff
+understands.
+.
+This is a PostScript Type\~1 font in PFA format or a PostScript
+Type\~42 font,
+together with an AFM file.
+.
+A PFA file begins as follows.
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+%!PS\-AdobeFont\-1.0:
+.EE
+.RE
+.
+A PFB file contains this string as well,
+preceded by some non-printing bytes.
+.
+If your font is in PFB format,
+use
+.IR groff 's
+.MR pfbtops @MAN1EXT@
+program to convert it to PFA.
+.
+For TrueType and other font formats,
+we recommend
+.IR fontforge ,
+which can convert most outline font formats.
+.
+A Type\~42 font file begins as follows.
+.
+.RS
+.EX
+%!PS\-TrueTypeFont
+.EE
+.RE
+.
+This is a wrapper format for TrueType fonts.
+.
+Old PostScript printers might not support them
+(that is,
+they might not have a built-in TrueType font interpreter).
+.
+In the following steps,
+we will consider the use of CTAN's
+.UR https://\:ctan.org/\:tex\-archive/\:fonts/\:brushscr
+BrushScriptX-Italic
+.UE
+font in PFA format.
+.RE \" now restore left margin
+.
+.
+.IP \[bu]
+Convert the AFM file to a
+.I groff
+font description file with the
+.MR afmtodit @MAN1EXT@
+program.
+.
+For instance,
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+$ \c
+.B afmtodit BrushScriptX\-Italic.afm text.map BSI
+.EE
+.RE
+.
+converts the Adobe Font Metric file
+.I BrushScriptX\-Italic.afm
+to the
+.I groff
+font description file
+.IR BSI .
+.RE \" now restore left margin
+.
+.
+.IP
+If you have a font family which provides regular upright (roman),
+bold,
+italic,
+and
+bold-italic styles
+(where \[lq]italic\[rq] may be \[lq]oblique\[rq] or \[lq]slanted\[rq]),
+we recommend using the letters
+.BR R ,
+.BR B ,
+.BR I ,
+and
+.BR BI ,
+respectively,
+as suffixes to the
+.I groff
+font family name to enable
+.IR groff 's
+font family and style selection features.
+.
+An example is
+.IR groff 's
+built-in support for Times:
+the font family
+name is abbreviated as
+.BR T ,
+and the
+.I groff
+font names are therefore
+.BR TR ,
+.BR TB ,
+.BR TI ,
+and
+.BR TBI .
+.
+In our example,
+however,
+the BrushScriptX font is available in a single style only,
+italic.
+.
+.
+.IP \[bu]
+Install the
+.I groff
+font description file(s) in a
+.I devps
+subdirectory in the search path that
+.I groff
+uses for device and font file descriptions.
+.
+See the
+.I GROFF_FONT_PATH
+entry in section \[lq]Environment\[rq] of
+.MR @g@troff @MAN1EXT@
+for the current value of the font search path.
+.
+While
+.I groff
+doesn't directly use AFM files,
+it is a good idea to store them alongside its font description files.
+.
+.
+.IP \[bu]
+Register fonts in the
+.I devps/download
+file so they can be located for embedding in PostScript files
+.I grops
+generates.
+.
+Only the first
+.I download
+file encountered in the font search path is read.
+.
+If in doubt,
+copy the default
+.I download
+file
+(see section \[lq]Files\[rq] below)
+to the first directory in the font search path and add your fonts there.
+.
+The PostScript font name used by
+.I grops
+is stored in the
+.B internalname
+field in the
+.I groff
+font description file.
+.
+(This name does not necessarily resemble the font's file name.)
+.
+We add the following line to
+.IR download .
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+BrushScriptX\-Italic\[->]BrushScriptX\-Italic.pfa
+.EE
+.RE \" but only one to get back to it
+.
+A tab character,
+depicted as \[->],
+separates the fields.
+.RE \" now restore left margin
+.
+.
+.IP \[bu]
+Test the selection and embedding of the new font.
+.
+.RS
+.RS \" two RS calls to get inboard of IP indentation
+.EX
+printf "\[rs]\[rs]f[BSI]Hello, world!\[rs]n" \
+| groff \-T ps \-P \-e >hello.ps
+see hello.pdf
+.EE
+.RE
+.RE \" now restore left margin
+.
+.
+.\" ====================================================================
+.SH "Old fonts"
+.\" ====================================================================
+.
+.I 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
+.I @OLDFONTDIR@/\:\%devps
+directory.
+.
+.
+.P
+To use them,
+make sure that
+.I grops
+finds the fonts before the default system fonts
+(with the same names):
+either give
+.I grops
+the
+.B \-F
+command-line option,
+.
+.RS
+.EX
+$ \c
+.B groff \-Tps \-P\-F \-P@OLDFONTDIR@ \c
+\&.\|.\|.
+.EE
+.RE
+.
+or add the directory to
+.IR groff 's
+font and device description search path environment variable,
+.
+.RS
+.EX
+$ \c
+.B GROFF_FONT_PATH=\:@OLDFONTDIR@ \[rs]
+.RS
+.B groff \-Tps \c
+\&.\|.\|.
+.RE
+.EE
+.RE
+.
+when the command runs.
+.
+.
+.br
+.ne 3v
+.\" ====================================================================
+.SH Environment
+.\" ====================================================================
+.
+.TP
+.I GROFF_FONT_PATH
+A list of directories in which to seek the selected output device's
+directory of device and font description files.
+.
+See
+.MR @g@troff @MAN1EXT@
+and
+.MR groff_font @MAN5EXT@ .
+.
+.
+.TP
+.I GROPS_PROLOGUE
+If this is set to
+.IR foo ,
+then
+.I grops
+uses the file
+.I foo
+(in the font path) instead of the default prologue file
+.IR prologue .
+.
+The option
+.B \-P
+overrides this environment variable.
+.
+.
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the output creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using
+.MR ctime 3
+and recorded in a PostScript comment.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.MR tzset 3 .
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:DESC
+describes the
+.B ps
+output device.
+.
+.
+.TP
+.IR @FONTDIR@/\:\%devps/ F
+describes the font known
+.RI as\~ F
+on device
+.BR ps .
+.
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:\%download
+lists fonts available for embedding within the PostScript document
+(or download to the device).
+.
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:\%prologue
+is the default PostScript prologue prefixed to every output file.
+.
+.
+.TP
+.I @FONTDIR@/\:\%devps/\:text.enc
+describes the encoding scheme used by most PostScript Type\~1 fonts;
+the
+.B \%encoding
+directive of
+font description files for the
+.B ps
+device refers to it.
+.
+.
+.TP
+.I @MACRODIR@/\:ps.tmac
+defines macros for use with the
+.B ps
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B ps
+output device is selected.
+.
+.
+.TP
+.I @MACRODIR@/\:pspic.tmac
+defines the
+.B PSPIC
+macro for embedding images in a document;
+see
+.MR groff_tmac @MAN5EXT@ .
+.
+It is automatically loaded by
+.I troffrc.
+.
+.
+.TP
+.I @MACRODIR@/psold.tmac
+provides replacement glyphs for text fonts that lack complete coverage
+of the ISO Latin-1 character set;
+using it,
+.I groff
+can produce glyphs like eth (\[Sd]) and thorn (\[Tp]) that older
+PostScript printers do not natively support.
+.
+.
+.P
+.I grops
+creates temporary files using the template
+.RI \[lq] grops XXXXXX\[rq];
+see
+.MR groff @MAN1EXT@
+for details on their storage location.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.UR http://\:partners\:.adobe\:.com/\:public/\:developer/\:en/\:ps/\
+\:5001\:.DSC_Spec\:.pdf
+PostScript Language Document Structuring Conventions Specification
+.UE
+.
+.
+.P
+.MR afmtodit @MAN1EXT@ ,
+.MR groff @MAN1EXT@ ,
+.MR @g@troff @MAN1EXT@ ,
+.MR pfbtops @MAN1EXT@ ,
+.MR groff_char @MAN7EXT@ ,
+.MR groff_font @MAN5EXT@ ,
+.MR groff_out @MAN5EXT@ ,
+.MR groff_tmac @MAN5EXT@
+.
+.
+.\" Clean up.
+.rm FT
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_grops_1_man_C]
+.do rr *groff_grops_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: