diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/groff.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/groff.1 | 2055 |
1 files changed, 2055 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/groff.1 b/upstream/mageia-cauldron/man1/groff.1 new file mode 100644 index 00000000..95c01591 --- /dev/null +++ b/upstream/mageia-cauldron/man1/groff.1 @@ -0,0 +1,2055 @@ +.TH GROFF 1 "17 December 2018" "groff 1.22.4" +.SH NAME +groff \- front-end for the groff document formatting system +. +.\" groff.man -> groff.1 +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr groff_1_C \n[.C] +.cp 0 +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2018 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff type-setting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, with no Front-Cover Texts, +.\" and with no Back-Cover Texts. +.\" +.\" A copy of the Free Documentation License is included as a file +.\" called FDL in the main directory of the groff source package. +. +. +.\" ==================================================================== +.\" Definitions +.\" ==================================================================== +. +.\" ==================================================================== +.\" 'char or string' +.de Quoted +. ft CR +\[oq]\\$*\[cq] +. ft +.. +. +.\" ==================================================================== +.SH SYNOPSIS +.\" ==================================================================== +. +.SY groff +.OP \-abcegijklpstzCEGNRSUVXZ +.OP \-d cs +.OP \-D arg +.OP \-f fam +.OP \-F dir +.OP \-I dir +.OP \-K arg +.OP \-L arg +.OP \-m name +.OP \-M dir +.OP \-n num +.OP \-o list +.OP \-P arg +.OP \-r cn +.OP \-T dev +.OP \-w name +.OP \-W name +.RI [ file +\&.\|.\|.\&] +.YS +. +.SY groff +.B \-h +.SY groff +.B \-\-help +.YS +. +.SY groff +.B \-v +.RI [ option +\&.\|.\|.\&] +.SY groff +.B \-\-version +.RI [ option +\&.\|.\|.\&] +.YS +. +. +.\" ==================================================================== +.SH DESCRIPTION +.\" ==================================================================== +. +This document describes the +.B groff +program, the main front-end for the +.I groff +document formatting system. +. +The +.I groff +program and macro suite is the implementation of a +.BR roff (7) +system within the free software collection +.UR http://\:www.gnu.org +GNU +.UE . +. +The +.I groff +system has all features of the classical +.IR roff , +but adds many extensions. +. +. +.P +The +.B groff +program allows control of the whole +.I groff +system by command-line options. +. +This is a great simplification in comparison to the classical case (which +uses pipes only). +. +. +.\" ==================================================================== +.SH OPTIONS +.\" ==================================================================== +. +The command line is parsed according to the usual \f[CR]GNU\f[] +convention. +. +Whitespace is permitted between a command-line option and its argument. +. +Options can be grouped behind a single \[oq]\-\[cq] (minus character). +. +A filename of +.B \- +(minus character) denotes the standard input. +. +. +.P +As +.B groff +is a wrapper program for +.B troff +both programs share a set of options. +. +But the +.B groff +program has some additional, native options and gives a new meaning to +some +.B troff +options. +. +On the other hand, not all +.B troff +options can be fed into +.BR groff . +. +. +.\" ==================================================================== +.SS Native groff Options +.\" ==================================================================== +. +The following options either do not exist for +.B troff +or are differently interpreted by +.BR groff . +. +. +.TP +.BI \-D\ arg +Set default input encoding used by +.B preconv +to +.IR arg . +. +Implies +.BR \-k . +. +. +.TP +.B \-e +Preprocess with +.BR eqn . +. +. +.TP +.B \-g +Preprocess with +.BR grn . +. +. +.TP +.B \-G +Preprocess with +.BR grap . +. +Implies +.BR \-p . +. +. +.TP +.B \-h +.TQ +.B \-\-help +Print a help message. +. +. +.TP +.BI \-I\ dir +This option may be used to specify a directory to search for +files (both those on the command line and those named in +.B .psbb +and +.B .so +requests, and +.B \eX'ps: import' +, +.B \eX'ps: file' +and +.B \eX'pdf: pdfpic' +escapes). +. +The current directory is always searched first. +. +This option may be specified more than once; +the directories are searched in the order specified. +. +No directory search is performed for files specified using an absolute path. +. +This option implies the +.B \-s +option. +. +. +.TP +.B \-j +Preprocess with +.BR chem . +. +Implies +.BR \-p . +. +. +.TP +.B \-k +Preprocess with +.BR preconv . +. +This is run before any other preprocessor. +. +Please refer to +.BR preconv 's +manual page for its behaviour if no +.B \-K +(or +.BR \-D ) +option is specified. +. +. +.TP +.BI \-K\ arg +Set input encoding used by +.B preconv +to +.IR arg . +. +Implies +.BR \-k . +. +. +.TP +.B \-l +Send the output to a spooler program for printing. +. +The command that should be used for this is specified by the +.B print +command in the device description file, see +.BR \%groff_font (5). +. +If this command is not present, the output is piped into the +.BR lpr (1) +program by default. +. +See options +.B \-L +and +.BR \-X . +. +. +.TP +.BI \-L\ arg +Pass +.I arg +to the spooler program. +. +Several arguments should be passed with a separate +\-L +option each. +. +Note that +.B groff +does not prepend +\[oq]\-\[cq] +(a minus sign) to +.I arg +before passing it to the spooler program. +. +. +.TP +.B \-N +Don't allow newlines within +.I eqn +delimiters. +. +This is the same as the +.B \-N +option in +.BR eqn . +. +. +.TP +.B \-p +Preprocess with +.BR pic . +. +. +.TP +.BI \-P\ \-option +.TQ +.BI \-P\ \-option \ \-P\ arg +Pass +.I \-option +or +.I "\-option\~arg" +to the postprocessor. +. +The option must be specified with the necessary preceding minus +sign(s) +.Quoted \- +or +.Quoted \-\- +because +.B groff +does not prepend any dashes before passing it to the postprocessor. +. +For example, to pass a title to the +.B \%gxditview +postprocessor, the shell command +. +.RS +.IP +.EX +groff \-X \-P \-title \-P 'groff it' \f[I]foo\f[] +.EE +.RE +. +.IP +is equivalent to +. +.RS +.IP +.EX +groff \-X \-Z \f[I]foo\f[] | \ +gxditview \-title 'groff it' \- +.EE +.RE +. +. +.TP +.B \-R +Preprocess with +.BR refer . +. +No mechanism is provided for passing arguments to +.B refer +because most +.B refer +options have equivalent language elements that can be specified within +the document. +. +See +.BR \%refer (1) +for more details. +. +. +.TP +.B \-s +Preprocess with +.BR soelim . +. +. +.TP +.B \-S +Safer mode. +. +Pass the +.B \-S +option to +.B pic +and disable the following +.B troff +requests: +.BR .open , +.BR .opena , +.BR .pso , +.BR .sy , +and +.BR .pi . +. +For security reasons, safer mode is enabled by default. +. +. +.TP +.B \-t +Preprocess with +.BR tbl . +. +. +.TP +.BI \-T\ dev +Set output device to +.IR dev . +. +For this device, +.B troff +generates the +.I intermediate +.IR output ; +see +.BR \%groff_out (5). +. +Then +.B groff +calls a postprocessor to convert +.BR troff 's +.I intermediate output +to its final format. +. +Real devices in +.B groff +are +. +.RS +.RS +.TP +dvi +TeX DVI format (postprocessor is +.BR grodvi ). +. +.TP +html +.TQ +xhtml +HTML and XHTML output (preprocessors are +.B soelim +and +.BR \%pre-grohtml , +postprocessor is +.BR \%post-grohtml ). +. +.TP +lbp +Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers; +postprocessor is +.BR grolbp ). +. +.TP +lj4 +HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor +is +.BR grolj4 ). +. +.TP +ps +PostScript output (postprocessor is +.BR grops ). +. +.TP +pdf +Portable Document Format (PDF) output (postprocessor is +.BR gropdf ). +.RE +.RE +. +. +.IP +For the following TTY output devices (postprocessor is always +.BR grotty ), +.B \-T +selects the output encoding: +. +.RS +.RS +.TP +ascii +7bit \f[CR]ASCII\f[]. +. +.TP +cp1047 +\%Latin-1 character set for EBCDIC hosts. +. +.TP +latin1 +ISO \%8859-1. +. +.TP +utf8 +Unicode character set in \%UTF-8 encoding. +. +This mode has the most useful fonts for TTY mode, so it is the best +mode for TTY output. +.RE +.RE +. +. +.IP +The following arguments select +.B \%gxditview +as the \[oq]postprocessor\[cq] (it is rather a viewing program): +. +.RS +.RS +.TP +X75 +75\|dpi resolution, 10\|pt document base font. +.TP +X75\-12 +75\|dpi resolution, 12\|pt document base font. +.TP +X100 +100\|dpi resolution, 10\|pt document base font. +.TP +X100\-12 +100\|dpi resolution, 12\|pt document base font. +.RE +.RE +. +.IP +The default device is +.BR ps . +. +. +.TP +.B \-U +Unsafe mode. +. +Reverts to the (old) unsafe behaviour; see option +.BR \-S . +. +. +.TP +.B \-v +.TQ +.B \-\-version +Output version information of +.B groff +and of all programs that are run by it; that is, the given command line +is parsed in the usual way, passing +.B \-v +to all subprograms. +. +. +.TP +.B \-V +Output the pipeline that would be run by +.B groff +(as a wrapper program) on the standard output, but do not execute it. +. +If given more than once, +the commands are both printed on the standard error and run. +. +. +.TP +.B \-X +Use +.B \%gxditview +instead of using the usual postprocessor to (pre)view a document. +. +The printing spooler behavior as outlined with options +.B \-l +and +.B \-L +is carried over to +.BR \%gxditview (1) +by determining an argument for the +.B \-printCommand +option of +.BR \%gxditview (1). +. +This sets the default +.B Print +action and the corresponding menu entry to that value. +. +.B \-X +only produces good results with +.BR \-Tps , +.BR \-TX75 , +.BR \-TX75\-12 , +.BR \-TX100 , +and +.BR \-TX100\-12 . +. +The default resolution for previewing +.B \-Tps +output is 75\|dpi; this can be changed by passing the +.B \-resolution +option to +.BR \%gxditview , +for example +. +.RS +.IP +.EX +groff \-X \-P\-resolution \-P100 \-man foo.1 +.EE +.RE +. +. +.TP +.B \-z +Suppress output generated by +.BR troff . +. +Only error messages are printed. +. +. +.TP +.B \-Z +Do not automatically postprocess +.I groff intermediate output +in the usual manner. +. +This will cause the +.B troff +.I output +to appear on standard output, +replacing the usual postprocessor output; see +.BR \%groff_out (5). +. +. +.\" ==================================================================== +.SS Transparent Options +.\" ==================================================================== +. +The following options are transparently handed over to the formatter +program +.B troff +that is called by +.B groff +subsequently. +. +These options are described in more detail in +.BR troff (1). +. +.TP +.B \-a +\f[CR]ASCII\f[] approximation of output. +. +.TP +.B \-b +Backtrace on error or warning. +. +.TP +.B \-c +Disable color output. +. +Please consult the +.BR \%grotty (1) +man page for more details. +. +.TP +.B \-C +Enable compatibility mode. +. +.TP +.BI \-d\ cs +.TQ +.BI \-d\ name = s +Define string. +. +.TP +.B \-E +Disable +.B troff +error messages. +. +.TP +.BI \-f\ fam +Set default font family. +. +.TP +.BI \-F\ dir +Set path for device +.I DESC +files. +. +.TP +.B \-i +Process standard input after the specified input files. +. +.TP +.BI \-m\ name +Include macro file +.RI name .tmac +(or +.IR tmac. name); +see also +.BR \%groff_tmac (5). +. +.TP +.BI \-M\ dir +Path for macro files. +. +.TP +.BI \-n\ num +Number the first page +.IR num . +. +.TP +.BI \-o\ list +Output only pages in +.IR list . +. +.TP +.BI \-r\ cn +.TQ +.BI \-r\ name = n +Set number register. +. +.TP +.BI \-w\ name +Enable warning +.IR name . +. +See +.BR troff (1) +for names. +. +.TP +.BI \-W\ name +disable warning +.IR name . +. +See +.BR troff (1) +for names. +. +. +.\" ==================================================================== +.SH "USING GROFF" +.\" ==================================================================== +. +The +.I groff system +implements the infrastructure of classical roff; see +.BR roff (7) +for a survey on how a +.I roff +system works in general. +. +Due to the front-end programs available within the +.I groff +system, using +.I groff +is much easier than +.IR "classical roff" . +. +This section gives an overview of the parts that constitute the +.I groff +system. +. +It complements +.BR roff (7) +with +.IR groff -specific +features. +. +This section can be regarded as a guide to the documentation around +the +.I groff +system. +. +. +.\" ==================================================================== +.SS Paper Size +.\" ==================================================================== +. +The +.I virtual +paper size used by +.B troff +to format the input is controlled globally with the requests +.BR .po , +.BR .pl , +and +.BR .ll . +. +See +.BR groff_tmac (5) +for the \[oq]papersize\[cq] macro package which provides a convenient +interface. +. +. +.P +The +.I physical +paper size, giving the actual dimensions of the paper sheets, is +controlled by output devices like +.B grops +with the command-line options +.B \-p +and +.BR \-l . +. +See +.BR groff_font (5) +and the man pages of the output devices for more details. +. +.B groff +uses the command-line option +.B \-P +to pass options to output devices; for example, the following selects +A4 paper in landscape orientation for the PS device: +. +.IP +.EX +groff \-Tps \-P\-pa4 \-P\-l ... +.EE +. +. +.\" ==================================================================== +.SS Front-ends +.\" ==================================================================== +. +The +.B groff +program is a wrapper around the +.BR troff (1) +program. +. +It allows one to specify the preprocessors by command-line options and +automatically runs the postprocessor that is appropriate for the +selected device. +. +Doing so, the sometimes tedious piping mechanism of classical +.BR roff (7) +can be avoided. +. +. +.P +The +.BR grog (1) +program can be used for guessing the correct +.I groff +command line to format a file. +. +. +.P +The +.BR \%groffer (1) +program is an all-around viewer for +.I groff +files and man pages. +. +. +.\" ==================================================================== +.SS Preprocessors +.\" ==================================================================== +. +The +.I groff +preprocessors are reimplementations of the classical preprocessors +with moderate extensions. +. +The standard preprocessors distributed with the +.I groff +package are +. +.TP +.BR eqn (1) +for mathematical formulae, +. +.TP +.BR grn (1) +for including +.BR gremlin (1) +pictures, +. +.TP +.BR pic (1) +for drawing diagrams, +. +.TP +.BR chem (1) +for chemical structure diagrams, +. +.TP +.BR \%refer (1) +for bibliographic references, +. +.TP +.BR \%soelim (1) +for including macro files from standard locations, +. +.P +and +. +.TP +.BR tbl (1) +for tables. +. +.P +A new preprocessor not available in classical +.I troff +is +.BR \%preconv (1) +which converts various input encodings to something +.B groff +can understand. +. +It is always run first before any other preprocessor. +. +.P +Besides these, there are some internal preprocessors that are +automatically run with some devices. +. +These aren't visible to the user. +. +. +.\" ==================================================================== +.SS "Macro Packages" +.\" ==================================================================== +. +Macro packages can be included by option +.BR \-m . +. +The +.I groff +system implements and extends all classical macro packages in a +compatible way and adds some packages of its own. +. +Actually, the following macro packages come with +.IR groff : +. +.TP +.B man +The traditional man page format; see +.BR \%groff_man (7). +It can be specified on the command line as +.B \-man +or +.BR \-m\~man . +. +.TP +.B mandoc +The general package for man pages; it automatically recognizes +whether the documents uses the +.I man +or the +.I mdoc +format and branches to the corresponding macro package. +. +It can be specified on the command line as +.B \%\-mandoc +or +.BR \-m\~\%mandoc . +. +.TP +.B mdoc +The \f[CR]BSD\f[]-style man page format; see +.BR \%groff_mdoc (7). +. +It can be specified on the command line as +.B \-mdoc +or +.BR \-m\~mdoc . +. +.TP +.B me +The classical +.I me +document format; see +.BR \%groff_me (7). +. +It can be specified on the command line as +.B \-me +or +.BR \-m\~me . +. +.TP +.B mm +The classical +.I mm +document format; see +.BR \%groff_mm (7). +. +It can be specified on the command line as +.B \-mm +or +.BR \-m\~mm . +. +.TP +.B ms +The classical +.I ms +document format; see +.BR \%groff_ms (7). +It can be specified on the command line as +.B \-ms +or +.BR \-m\~ms . +. +.TP +.B www +HTML-like macros for inclusion in arbitrary +.I groff +documents; see +.BR \%groff_www (7). +. +.P +Details on the naming of macro files and their placement can be found +in +.BR \%groff_tmac (5); +this man page also documents some other, minor auxiliary macro packages +not mentioned here. +. +. +.\" ==================================================================== +.SS "Programming Language" +.\" ==================================================================== +. +General concepts common to all +.I roff +programming languages are described in +.BR roff (7). +. +. +.P +The +.I groff +extensions to the classical +.I troff +language are documented in +.BR \%groff_diff (7). +. +. +.P +An overview of language features, +including all supported escapes and requests, +can be found in +.BR groff (7). +. +. +.\" ==================================================================== +.SS Formatters +.\" ==================================================================== +. +The central +.I roff +formatter within the +.I groff +system is +.BR troff (1). +. +It provides the features of both the classical +.I troff +and +.IR nroff , +as well as the +.I groff +extensions. +. +The command-line option +.B \-C +switches +.B troff +into +.I "compatibility mode" +which tries to emulate classical +.I roff +as much as possible. +. +. +.P +There is a shell script +.BR nroff (1) +that emulates the behavior of classical +.BR nroff . +. +It tries to automatically select the proper output encoding, according to +the current locale. +. +. +.P +The formatter program generates +.IR "intermediate output" ; +see +.BR \%groff_out (7). +. +. +.\" ==================================================================== +.SS Devices +.\" ==================================================================== +. +In +.IR roff , +the output targets are called +.IR devices . +A device can be a piece of hardware, e.g., a printer, or a software +file format. +. +A device is specified by the option +.BR \-T . +. +The +.I groff +devices are as follows. +. +.TP +.B ascii +Text output using the +.BR ascii (7) +character set. +. +.TP +.B cp1047 +Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix). +. +.TP +.B dvi +TeX DVI format. +. +.TP +.B html +HTML output. +. +.TP +.B latin1 +Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see +.BR \%iso_8859_1 (7). +. +.TP +.B lbp +Output for Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser +printers). +. +.TP +.B lj4 +HP LaserJet4-compatible (or other PCL5-compatible) printers. +. +.TP +.B ps +PostScript output; suitable for printers and previewers like +.BR gv (1). +. +.TP +.B pdf +PDF files; suitable for viewing with tools such as +.BR evince (1) +and +.BR okular (1). +. +.TP +.B utf8 +Text output using the Unicode (ISO 10646) character set with \%UTF-8 +encoding; see +.BR unicode (7). +. +.TP +.B xhtml +XHTML output. +. +.TP +.B X75 +75dpi X Window System output suitable for the previewers +.BR \%xditview (1x) +and +.BR \%gxditview (1). +. +A variant for a 12\|pt document base font is +.BR \%X75-12 . +. +.TP +.B X100 +100dpi X Window System output suitable for the previewers +.BR \%xditview (1x) +and +.BR \%gxditview (1). +. +A variant for a 12\|pt document base font is +.BR \%X100-12 . +. +. +.P +The postprocessor to be used for a device is specified by the +.B postpro +command in the device description file; see +.BR \%groff_font (5). +. +This can be overridden with the +.B \-X +option. +. +.P +The default device is +.BR ps . +. +. +.\" ==================================================================== +.SS Postprocessors +.\" ==================================================================== +. +.I groff +provides 3\~hardware postprocessors: +. +.TP +.BR \%grolbp (1) +for some Canon printers, +. +.TP +.BR \%grolj4 (1) +for printers compatible to the HP LaserJet\~4 and PCL5, +. +.TP +.BR \%grotty (1) +for text output using various encodings, e.g., on text-oriented +terminals or line printers. +. +. +.P +Today, most printing or drawing hardware is handled by the operating +system, by device drivers, or by software interfaces, usually +accepting PostScript. +. +Consequently, there isn't an urgent need for more hardware device +postprocessors. +. +. +.P +The +.I groff +software devices for conversion into other document file formats are +. +.TP +.BR \%grodvi (1) +for the DVI format, +. +.TP +.BR \%grohtml (1) +for HTML and XHTML formats, +. +.TP +.BR grops (1) +for PostScript. +. +.TP +.BR gropdf (1) +for PDF. +. +. +.P +Combined with the many existing free conversion tools this should +be sufficient to convert a +.I troff +document into virtually any existing data format. +. +. +.\" ==================================================================== +.SS Utilities +.\" ==================================================================== +. +The following utility programs around +.I groff +are available. +. +.TP +.BR \%addftinfo (1) +Add information to +.I troff +font description files for use with +.IR groff . +. +.TP +.BR \%afmtodit (1) +Create font description files for PostScript device. +. +.TP +.BR \%eqn2graph (1) +Convert an +.B eqn +image into a cropped image. +. +.TP +.BR \%gdiffmk (1) +Mark differences between +.IR groff , +.IR nroff , +or +.I troff +files. +. +.TP +.BR \%grap2graph (1) +Convert a +.B grap +diagram into a cropped bitmap image. +. +.TP +.BR \%groffer (1) +General viewer program for +.I groff +files and man pages. +. +.TP +.BR \%gxditview (1) +The +.I groff +X viewer, the \f[CR]GNU\f[] version of +.BR xditview . +. +.TP +.BR \%hpftodit (1) +Create font description files for lj4 device. +. +.TP +.BR \%indxbib (1) +Make inverted index for bibliographic databases. +. +.TP +.BR lkbib (1) +Search bibliographic databases. +. +.TP +.BR \%lookbib (1) +Interactively search bibliographic databases. +. +.TP +.BR \%pdfroff (1) +Create PDF documents using +.BR groff . +. +.TP +.BR \%pfbtops (1) +Translate a PostScript font in \&.pfb format to \f[CR]ASCII\f[]. +. +.TP +.BR \%pic2graph (1) +Convert a +.B pic +diagram into a cropped image. +. +.TP +.BR \%tfmtodit (1) +Create font description files for TeX DVI device. +. +.TP +.BR \%xditview (1x) +.I roff +viewer historically distributed with the X Window System. +.\" Nowadays (2017) it's its own module as X.Org does not do monolithic +.\" releases anymore (since 2012). Development on "app/xditview" is +.\" close to moribund, though. +. +.TP +.BR \%xtotroff (1) +Convert X font metrics into \f[CR]GNU\f[] +.I troff +font metrics. +. +. +.\" ==================================================================== +.SH ENVIRONMENT +.\" ==================================================================== +. +Normally, the path separator in the following environment variables is +the colon; this may vary depending on the operating system. +. +For example, DOS and Windows use a semicolon instead. +. +. +.TP +.I GROFF_BIN_PATH +This search path, followed by +.IR PATH , +is used for commands that are executed by +.BR groff . +. +If it is not set then the directory where the +.I groff +binaries were installed is prepended to +.IR PATH . +. +. +.TP +.I GROFF_COMMAND_PREFIX +When there is a need to run different +.I roff +implementations at the same time +.I groff +provides the facility to prepend a prefix to most of its programs that +could provoke name clashings at run time (default is to have none). +. +Historically, this prefix was the character +.BR g , +but it can be anything. +. +For example, +.B gtroff +stood for +.IR groff 's +.BR troff , +.B gtbl +for the +.I groff +version of +.BR tbl . +. +By setting +.I \%GROFF_COMMAND_PREFIX +to different values, the different +.I roff +installations can be addressed. +. +More exactly, if it is set to prefix +.I xxx +then +.B groff +as a wrapper program internally calls +.IB xxx troff +instead of +.BR troff . +. +This also applies to the preprocessors +.BR eqn , +.BR grn , +.BR pic , +.BR \%refer , +.BR tbl , +.BR \%soelim , +and to the utilities +.B \%indxbib +and +.BR \%lookbib . +. +This feature does not apply to any programs different from the ones +above (most notably +.B groff +itself) since they are unique to the +.I groff +package. +. +. +.TP +.I GROFF_ENCODING +The value of this environment value is passed to the +.B preconv +preprocessor to select the encoding of input files. +. +Setting this option implies +.BR groff 's +command-line option +.B \-k +(this is, +.B groff +actually always calls +.BR preconv ). +. +If set without a value, +.B groff +calls +.B preconv +without arguments. +. +An explicit +.B \-K +command-line option overrides the value of +.IR \%GROFF_ENCODING . +. +See +.BR preconv (1) +for details. +. +. +.TP +.I GROFF_FONT_PATH +A list of directories in which to search for the +.IR dev name +directory in addition to the default ones. +. +See +.BR troff (1) +and +.BR \%groff_font (5) +for more details. +. +. +.TP +.I GROFF_TMAC_PATH +A list of directories in which to search for macro files in addition +to the default directories. +. +See +.BR troff (1) +and +.BR \%groff_tmac (5) +for more details. +. +. +.TP +.I GROFF_TMPDIR +The directory in which temporary files are created. +. +If this is not set but the environment variable +.I \%TMPDIR +instead, temporary files are created in the directory +.IR \%TMPDIR . +. +On MS-DOS and Windows platforms, the environment variables +.I TMP +and +.I TEMP +(in that order) are searched also, after +.I \%GROFF_TMPDIR +and +.IR \%TMPDIR . +. +Otherwise, temporary files are created in +.IR /tmp . +. +The +.BR \%refer (1), +.BR \%groffer (1), +.BR \%grohtml (1), +and +.BR grops (1) +commands use temporary files. +. +. +.TP +.I GROFF_TYPESETTER +Preset the default device. +. +If this is not set the +.B ps +device is used as default. +. +This device name is overwritten by the option +.BR \-T . +. +. +.\" ==================================================================== +.SH EXAMPLES +.\" ==================================================================== +. +The following example illustrates the power of the +.B groff +program as a wrapper around +.BR troff . +. +. +.P +To process a +.I roff +file using the preprocessors +.B tbl +and +.B pic +and the +.B me +macro set, classical +.I troff +had to be called by +. +.IP +.EX +pic foo.me | tbl | troff \-me \-Tlatin1 | grotty +.EE +. +. +.P +Using +.BR groff , +this pipe can be shortened to the equivalent command +. +.IP +.EX +groff \-p \-t \-me \-T latin1 foo.me +.EE +. +. +.P +An even easier way to call this is to use +.BR grog (1) +to guess the preprocessor and macro options and execute the generated +command (by using backquotes to specify shell command substitution) +. +.IP +.EX +\[ga]grog \-Tlatin1 foo.me\[ga] +.EE +. +. +.P +The simplest way is to view the contents in an automated way by +calling +. +.IP +.EX +groffer foo.me +.EE +. +. +.\" ==================================================================== +.SH BUGS +.\" ==================================================================== +. +On \f[CR]EBCDIC\f[] hosts (e.g., \f[CR]OS/390 Unix\f[]), output +devices +.B ascii +and +.B latin1 +aren't available. +. +Similarly, output for \f[CR]EBCDIC\f[] code page +.B cp1047 +is not available on \f[CR]ASCII\f[] based operating systems. +. +. +.\" ==================================================================== +.SH "INSTALLATION DIRECTORIES" +.\" ==================================================================== +. +.I groff +installs files in varying locations depending on its compile-time +configuration. +. +On this installation, the following locations are used. +. +. +.TP +.I /usr/\:lib64/\:X11/\:app\-defaults/\: +Application defaults directory for +.IR gxditview (1). +. +. +.TP +.I /usr/\:bin +Directory containing +.IR groff 's +executable commands. +. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:eign +List of common words for +.IR indxbib (1). +. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4 +Directory for data files. +. +. +.TP +.I /usr/\:dict/\:papers/\:Ind +Default index for +.IR lkbib (1) +and +.IR refer (1). +. +. +.TP +.I /usr/\:share/\:doc/\:groff\-1.22.4 +Documentation directory. +. +. +.TP +.I /usr/\:share/\:doc/\:groff\-1.22.4/\:examples +Example directory. +. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:font +Font directory. +. +. +.TP +.I /usr/\:share/\:doc/\:groff\-1.22.4/\:html +HTML documentation directory. +. +. +.TP +.I /usr/\:lib/\:font +Legacy font directory. +. +. +.TP +.I /usr/\:share/\:groff/\:site\-font +Local font directory. +. +. +.TP +.I /usr/\:share/\:groff/\:site\-tmac +Local macro package +.RI ( tmac +file) directory. +. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:tmac +Macro package +.RI ( tmac +file) directory. +. +. +.TP +.I /usr/\:share/\:groff/\:1.22.4/\:oldfont +Font directory for compatibility with old versions of +.IR groff ; +see +.IR grops (1). +. +. +.TP +.I /usr/\:share/\:doc/\:groff\-1.22.4/\:pdf +PDF documentation directory. +. +. +.TP +.I /usr/\:lib64/\:groff/\:site\-tmac +System macro package +.RI ( tmac +file) directory. +. +. +.\" ==================================================================== +.SS "groff Macro Directory" +.\" ==================================================================== +. +This contains all information related to macro packages. +. +Note that more than a single directory is searched for those files +as documented in +.BR \%groff_tmac (5). +. +For the +.I groff +installation corresponding to this document, it is located at +.IR /usr/\:share/\:groff/\:1.22.4/\:tmac . +. +The following files contained in the +.I groff macro directory +have a special meaning: +. +. +.TP +.I troffrc +Initialization file for +.IR troff . +. +This is interpreted by +.B troff +before reading the macro sets and any input. +. +. +.TP +.I troffrc\-end +Final startup file for +.IR troff . +. +It is parsed after all macro sets have been read. +. +. +.TP +.RI name .tmac +.TQ +.IR tmac. name +Macro file for macro package +.IR name . +. +. +.\" ==================================================================== +.SS "groff Font Directory" +.\" ==================================================================== +. +This contains all information related to output devices. +. +Note that more than a single directory is searched for those files; see +.BR troff (1). +. +For the +.I groff +installation corresponding to this document, it is located at +.IR /usr/\:share/\:groff/\:1.22.4/\:font . +. +The following files contained in the +.I "groff font directory" +have a special meaning: +. +. +.TP +.IR dev name /DESC +Device description file for device +.IR name , +see +.BR \%groff_font (5). +. +. +.TP +.IR dev name / F +Font file for font +.I F +of device +.IR name . +. +. +.\" ==================================================================== +.SH AVAILABILITY +.\" ==================================================================== +. +Information on how to get +.I groff +and related information is available at the +.UR http://\:www.gnu.org/\:software/\:groff +groff page of the GNU website +.UE . +. +. +.P +Three +.I groff +mailing lists are available: +. +. +.IP +.MT bug\-groff@\:gnu.org +bug tracker activity (read-only) +.ME ; +. +. +.IP +.MT groff@\:gnu.org +general discussion +.ME ; +and +. +. +.IP +.MT groff\-commit@\:gnu.org +commit activity (read-only) +.ME , +which reports changes to +.IR groff 's +source code repository by its developers. +. +. +.P +Details on repository access and much more can be found in the file +.I README +at the top directory of the +.I groff +source package. +. +. +.P +A free implementation of the +.B grap +preprocessor, written by +.MT faber@\:lunabase.org +Ted Faber +.ME , +can be found at the +.UR http://\:www.lunabase.org/\:\|\[ti]faber/\:Vault/\:software/\:grap/ +grap website +.UE . +. +This is the only +.I grap +supported by +.IR groff . +. +. +.\" ==================================================================== +.SH AUTHORS +.\" ==================================================================== +. +.B groff +was written by +.MT jjc@\:jclark.com +James Clark +.ME . +. +This document was rewritten, enhanced, and put under the FDL license in +2002 by +.MT groff\-bernd.warken\-72@\:web.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "SEE ALSO" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.P +Due to its complex structure, the +.I groff +system has many man pages. +. +They can be read with +.BR man (1) +or +.BR \%groffer (1). +. +.P +But there are special sections of +.IR "man pages" . +. +.I groff +has man pages in sections +.BR 1 , " 5" , and " 7" . +. +When there are several +.I man pages +with the same name in the same +.I man +section, the one with the lowest section is should as first. +. +The other man pages can be shown anyway by adding the section number +as argument before the man page name. +. +Reading the man page about the +.I groff +language is done by one of +.RS +.nf +.nh +.EX +.B man 7 groff +.B groffer 7 groff +.EE +.hy +.fi +.RE +. +.ad l +.TP +Introduction, history and further readings: +.BR roff (7). +. +.TP +Viewer for groff files: +.BR \%groffer (1), +.BR \%gxditview (1), +.BR \%xditview (1x). +. +.TP +Wrapper programs for formatters: +.BR \%groff (1), +.BR \%grog (1). +. +.TP +Roff preprocessors: +.BR \%eqn (1), +.BR \%grn (1), +.BR \%pic (1), +.BR \%chem (1), +.BR \%preconv (1), +.BR \%refer (1), +.BR \%soelim (1), +.BR \%tbl (1), +.BR grap (1). +. +.TP +Roff language with the groff extensions: +.BR \%groff (7), +.BR \%groff_char (7), +.BR \%groff_diff (7), +.BR \%groff_font (5). +. +.TP +Roff formatter programs: +.BR \%nroff (1), +.BR \%troff (1), +.BR ditroff (7). +. +.TP +The intermediate output language: +.BR \%groff_out (7). +. +.TP +Postprocessors for the output devices: +.BR \%grodvi (1), +.BR \%grohtml (1), +.BR \%grolbp (1), +.BR \%grolj4 (1), +.BR \%lj4_font (5), +.BR \%grops (1), +.BR \%gropdf (1), +.BR \%grotty (1). +. +.TP +Groff macro packages and macro-specific utilities: +.BR \%groff_tmac (5), +.BR \%groff_man (7), +.BR \%groff_mdoc (7), +.BR \%groff_me (7), +.BR \%groff_mm (7), +.BR \%groff_mmse (7), +.BR \%groff_mom (7), +.BR \%groff_ms (7), +.BR \%groff_www (7), +.BR \%groff_trace (7), +.BR \%mmroff (7). +. +.TP +The following utilities are available: +.BR \%addftinfo (1), +.BR \%afmtodit (1), +.BR \%eqn2graph (1), +.BR \%gdiffmk (1), +.BR \%grap2graph (1), +.BR \%groffer (1), +.BR \%gxditview (1), +.BR \%hpftodit (1), +.BR \%indxbib (1), +.BR \%lkbib (1), +.BR \%lookbib (1), +.BR \%pdfroff (1), +.BR \%pfbtops (1), +.BR \%pic2graph (1), +.BR \%tfmtodit (1), +.BR \%xtotroff (1). +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[groff_1_C] +. +. +.\" ==================================================================== +.\" Emacs setup +.\" ==================================================================== +. +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff: |