1 .\" This file gives a small example how a web page could look like if created
5 .\" To make it work with other output devices also, we include www.tmac
10 .if '\*[.T]'html' .nr LL 10i
11 .if r ps4html .nr LL 10i
15 .HEAD "<link rel=""stylesheet"" type=""text/css"" href=""groff.css"" >"
16 .\" .HEAD "<link rel=""icon"" type=""image/png"" href=""http://www.gnu.org/graphics/gnu-mini.png"" >"
29 .defcolor mydarkred rgb 0.65f 0.1f 0.2f
30 .defcolor mydarkgreen rgb 0.1f 0.5f 0.2f
31 .defcolor mydarkblue rgb 0.1f 0.2f 0.6f
33 .ds GNU \m[mydarkred]G\m[]\m[mydarkgreen]N\m[]\m[mydarkblue]U\m[]
38 Home of Groff (GNU Troff).
41 .PSPIC -L gnu.eps 2i 2i
43 . nop \v'-0.66i'\h'2.0i'\s[80]\*[GNU] Troff\s0
45 . nop \v'-0.66i'\h'2.0i'\s[60]\*[GNU] Troff\s0
53 is the home page for groff (\c
54 .URL http://\:www.gnu.org/ GNU
57 Groff is a software typesetting package which reads plain text mixed with
58 formatting commands and produces formatted output.
60 The source code of the currently released versions of groff is
62 .URL "http://\:groff.ffii.org/\:groff/" "FFII host (Germany)" ,
63 .URL "ftp://\:ftp.gnu.org/\:gnu/\:groff/" "GNU host (USA)" ,
66 The USA site also contains older, obsolete versions.
68 The development version is available from a CVS repository, see below.
70 Development snapshots (produced twice a day from the CVS repository)
71 can be downloaded from
72 .URL "http://\:groff.ffii.org/\:groff/\:devel" here .
74 For a special version of groff on the Microsoft operating systems, see
75 .URL "http://\:gnuwin32.sf.net/\:packages/\:groffl.htm" "Groff for Windows" .
77 Groff was originally written and maintained by James Clark, however it
79 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding"
81 .MTO wl@\:gnu.org "Werner Lemberg" .
84 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding" .
86 Technical issues lead:
87 .MTO wl@\:gnu.org "Werner Lemberg" .
91 \s[-4]\f[I]This document was produced using
92 .URL http://groff.ffii.org/ groff-\n[.x].\n[.y].\n[.Y] .
94 The image at the top has been contributed by Imogen Mulley,
95 based on a similar picture found on the
96 .URL http://www.gnu.org "GNU server" .
101 GNU troff is released under the
102 .URL http://\:www.gnu.org/\:copyleft/\:gpl.html "GNU Copyright License" .
103 The documentation is released under the
104 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "Free Documentation License" .
105 Groff is an official GNU project as defined on
106 .URL http://\:savannah.gnu.org savannah .
111 This is the GNU groff document formatting system.
112 The version number is given in the file VERSION.
114 Included in this release are implementations of troff, pic, eqn, tbl,
115 grn, refer, \-man, \-mdoc, \-mom, and \-ms macros, and drivers for
116 PostScript, TeX dvi format, HP LaserJet\~4 printers, Canon CAPSL printers,
117 HTML and XHTML formats (beta status), and typewriter-like devices.
118 Also included is a modified version of the Berkeley \-me macros, the enhanced
119 version gxditview of the X11 xditview previewer, and an implementation of the
120 \-mm macros contributed by
121 .MTO jh@\:axis.se "J\[:o]rgen H\[:a]gg" .
123 See the file INSTALL for installation instructions.
124 You require a C++ compiler.
126 The file NEWS describes recent user-visible changes to groff.
128 Groff is free software.
129 See the file COPYING for copying permission.
131 The file PROBLEMS describes various problems that have been encountered in
132 compiling, installing, and running groff.
137 The most recent released version of groff is always available by
138 .URL "ftp://\:ftp.gnu.org/\:gnu/\:groff" "anonymous ftp" .
140 The current development version of groff is available from a
141 .URL "http://\:savannah.gnu.org/\:cvs/\:?group=groff" "CVS repository" .
142 You can access it by first selecting a parent directory in
143 which to create a working copy (call it, say, ~/cvswork), and then
144 executing the commands
150 cvs -d:pserver:anonymous@cvs.savannah.gnu.org/sources/groff -z5 co groff
155 This creates a subdirectory, ~/cvswork/groff, with a `checked out'
156 copy of the CVS repository.
157 An update of this working copy may be
158 achieved, at any later time by invoking the commands
169 Please read the CVS info pages for further details.
171 Finally, it is possible to access the CVS with a
172 .URL http://\:savannah.gnu.org/\:cvs/\:?group=groff "web browser" .
174 Alternatively, you can download snapshots (which are updated twice a day).
175 The complete groff source as a single file is available
176 .URL http://\:groff.ffii.org/\:groff/\:devel/\:groff-current.tar.gz here .
178 A diff file relative to groff-\[la]version\[ra], the latest official groff
179 release is available at
183 http://groff.ffii.org/groff/devel/groff-\[la]version\[ra]-current.diff.gz
187 Assuming that groff-\[la]version\[ra].tar.gz and
188 groff-\[la]version\[ra]-current.diff.gz are in the same directory, do the
189 following to apply the diff file:
194 tar xzvf groff-\[la]version\[ra].tar.gz
195 cd groff-\[la]version\[ra]
196 gunzip -c ../groff-\[la]version\[ra]-current.diff.gz | patch -p1
204 Depending on your requirements, you may need at least some of the
205 following tools to build groff directly from its source:
213 bison \[>=] 1.875b or byacc
217 Note that texinfo and bison or byacc are required only for building from
218 CVS sources (either a checked out working copy, or a daily snapshot).
219 They are not required for building from a stable release tarball.
220 Also note that the version numbers stated are the minimum supported.
221 No version of texinfo < 4.8 works, and the original release of bison
222 1.875 is known not to work; you \fImay\fP find that bison releases < 1.875
223 work, but in case of difficulty, please update to a later version
224 \fIbefore\fP posting a bug report.
226 For \fIall\fP sources, you need ghostscript for creation of either PDF or
227 HTML output; the netpbm and psutils packages are required only for HTML
229 If you don't intend to produce output in either of these formats, then
230 these packages are unnecessary.
232 In Linux Debian, the installation of texinfo is dangerous, for it creates a
233 file install-info that blocks the system installation.
234 So the created /usr/local/bin/install-info must be renamed.
236 The groff configure script searches for the X11 headers and libraries Xaw
238 So the corresponding developer packages of your system must be installed,
239 otherwise groff does not install gxditview and the -TX* devices.
240 In Debian, the developer packages are libxaw7-dev and libxmu-dev.
245 Please report bugs using the form in the file BUG-REPORT; the idea of this
246 is to make sure that FSF has all the information it needs to fix the bug.
247 At the very least, read the BUG-REPORT form and make sure that you supply
248 all the information that it asks for.
249 Even if you are not sure that something is a bug, report it using
250 BUG-REPORT: this enables us to determine whether it really is a bug or
256 Three mailing lists are available:
260 .MTO bug-groff@gnu.org bug-groff@gnu.org
264 .MTO groff@gnu.org groff@gnu.org
265 for general discussion of groff
268 .MTO groff-commit@gnu.org groff-commit@gnu.org
269 a read-only list showing commitments to the CVS repository
272 To subscribe, send e-mail to \[la]list\[ra]-request@\[la]domain\[ra]
274 .MTO groff-request@\:gnu.org groff-request@\:gnu.org
275 for the `groff' list) with the word `subscribe' in either the
276 subject or body of the e-mail (don't include the quotes).
277 Alternatively, you may subscribe by visiting the web pages at
281 .URL http://lists.gnu.org/mailman/listinfo/bug-groff
282 .URL http://lists.gnu.org/mailman/listinfo/groff
283 .URL http://lists.gnu.org/mailman/listinfo/groff-commit
287 Each of these web pages also provides a link to a browseable archive of
288 postings to the corresponding mailing list.
299 XHTML support has been added to grohtml and can be specified by
301 This option also utilizes the MathML capability of
302 eqn and combines the outputs of both in the final XHTML file.
303 Users can also specify the `\-P\-V' option together with `\-Txhtml'
305 This has the effect of creating an XHTML validator
306 button at the bottom of each page.
309 Some options have been added to control a new preprocessor,
310 `preconv' (see below): `\-k' activates it, `\-K' sets the input
311 encoding, and `\-D' sets the default encoding.
314 A new environment variable `GROFF_ENCODING' sets the encoding
315 of input files; it implies command option `\-k'.
324 Two new requests `device' and `devicem' have been added which are
325 equivalents to the \eX and \eY escapes, respectively.
328 A new read-only number register `.br' is available which is set to\~1
329 if a macro is called as .foo and to\~0 if called as 'foo.
330 This allows to reliably modify requests.
338 \&. ie \e\en[.br] .bp@orig
347 A new request `fzoom' has been added to adjust the optical size of a
348 font in relation to the others.
349 The zoom factor is given in integer multiples of 1/1000th.
350 In the following example, the CR font is magnified by 10% (the zoom
359 \&Palatino and \ef[CR]Courier\ef[]
364 The new number register `.zoom' holds the zoom value of the current font,
365 in multiples of 1/1000th.
368 The `cflags' request has been extended with a new flag value 64, to be
369 used in combination with values\~2 (break before character) and\~4 (break
371 If set, the hyphenation codes of the surrounding characters are ignored.
374 A new debugging request, `pev', has been added to print all of the current
375 known environments to stderr.
376 It first prints the state of the current environment, then iterates
377 through all of the known environments, printing each except the one that
381 A new escape `\e$^' has been added.
382 It represents the parameters of a macro as if they were an argument to
384 This is used by `trace.tmac'.
387 A new read-only number register `.O' is available which returns the
388 current suppression level as set by the `\eO' escape.
391 The space width emitted by the `\e|' and `\e^' escape sequences can be
392 controlled on a per-font basis.
393 If there is a glyph named `\e|' or `\e^', respectively (note the leading
394 backslash), defined in the current font file, use this glyph's width
395 instead of the default value.
397 This behaviour is not new, but hasn't been documented before.
406 Two new command line options `\-w' and `\-W' are accepted and passed to
407 groff to enable and disable warning messages, respectively.
416 This is a new preprocessor to convert various input encodings to something
417 groff understands (this is, ASCII and \e[uXXXX] entities, with `XXXX' a
418 hexadecimal number with 4 to 6 digits, representing a Unicode input code).
419 Normally, preconv should be invoked with options `\-k' and `\-K' of groff.
420 See the preconv man page for details.
429 int(x) now really behaves as documented: It truncates the non-integer part
430 of\~x, this is, it rounds towards zero and not towards the next integer
431 less than or equal to\~x.
434 Pic now supports up to 32 macro arguments (and up to 16 on EBCDIC
438 Heinz-Jürgen Örtel contributed code for two new keywords, `xslanted' and
439 `yslanted', which can change the shape of boxes into arbitrary
449 Latest versions of DWB tbl introduced an `x' column specifier for a single
450 column expanded to the line width.
451 GNU tbl has now been extended to support even multiple `x' specifiers
455 To avoid collision with the new `x' specifier, a block formatting macro
456 must now be selected with specifier letter `m'.
465 Eric S. Raymond has added a new device type to eqn, MathML.
466 When \-TMathML is enabled, eqn now emits MathML formula markup rather than
468 The new groff \-Txhtml device uses this.
477 The preprocessor `chem' was added.
478 `chem' is a roff language to generate chemical structure diagrams.
479 It generates `pic' output.
488 The PS font definition files have been regenerated with newer AFM versions
489 from Adobe's 35 core fonts as present in most Level\~2 PS printers.
490 The changes are minor (most notably, the addition of the `Euro' glyph and an
491 extended set of kerning values).
493 For backwards compatibility, the old set of font definition files is still
494 available; for details please read the man page of grops.
503 \eD'p...' is now supported if the polygon consists entirely of horizontal
513 XHTML support has been added.
516 New command line option `\-V' (to be used in XHTML mode) to produce an
517 XHTML validator button.
520 New command line option `\-y' to produce a right-justified groff signature
521 at the end of the document (in combination with option `\-V').
530 Support for keyboard navigation has been improved.
533 Similar to other X11 applications, there are now two resource files,
534 `GXditview' and `GXditview-color'.
543 `groffer' version 1.* exists now in a shell and a Perl version.
552 New option `\-c' to output more font information as comments.
555 New option `\-k' to suppress output of kerning data.
558 New option `\-f NAME' to set the internal name of the groff font.
567 Joachim Walsdorff contributed the `hdtbl' package for the generation of
568 tables, using a syntax very similar to the HTML table model.
569 For example, a table with two cells and two rows looks like this:
575 \&. TR .TD 1*1 .TD 1*2
576 \&. TR .TD 2*1 .TD 2*2
582 Here the same table using a more expanded syntax:
600 Tables can be nested; `hdtbl' works without a preprocessor so that the
601 full capability of groff's macro engine is available.
603 This package currently works with `-Tps' only.
606 \-mandoc now supports multiple man pages (in either man or mdoc format).
609 Fabrice Ménard contributed locales support.
610 In particular, it is now possible to get French localization of the main
611 macro packages (\-ms, \-mm, \-me, and \-mom, but not \-man and \-mdoc
612 which are localized differently) by appending `-mfr' to the list of macro
619 groff \-ms \-mfr foo > foo.ps
624 Note that latin-9 input encoding is used for French (to support the `oe'
628 Swedish macro localization (with `\-msv') has been added.
631 German macro localization (with `\-mde' and `\-mden' for traditional and
632 new orthography, respectively) has been added.
635 Czech macro localization (with `\-mcs') has been added.
637 Note that latin-2 input encoding is used for Czech.
640 A new macro `Dx' has been added to the mdoc package which identifies the
644 If mdoc is used to print multiple man pages (together with the \-rcR=0
645 command line option), each man page now starts a new page.
648 \-mtrace has been considerably improved, now showing number and string
649 register assignments, among other things.
650 See the groff_trace man page for details.
653 The PSPIC macro now works with all devices (producing a hollow
654 rectangle on devices which don't support inclusion of PS images) and
655 is loaded in troffrc at start-up.
658 A new auxiliary macro package `62bit' has been added which provides some
659 macros for adding, multiplying, and dividing signed 62bit integers (mainly
660 to handle normal groff number operations without risking overflow errors).
663 For \-ms, Eric S. Raymond contributed support for ancient Bell Labs
664 localisms `.SC', `.UC', `.P1', and `.P2'.
665 The latter three are enabled only after .SC is called.
668 A new string, `SN-STYLE', has been added to the ms macros, controlling
669 the formatting of section numbers in headings defined by `.NH'.
672 The new macro package `ptx' provides a template definition for the `.xx'
673 macro as needed by GNU ptx (for creating permuted indices).
685 Analogously to the .ft and \ef pair, two new requests `gcolor' and
686 `fcolor' (which pair with \em and \eM, respectively) have been added to
687 set the glyph and background colours.
690 A new read-only, string-valued register `.sty' returns the name of the
694 Two new conditional operators `F\~\[la]name\[ra]' and `S\~\[la]name\[ra]'
696 `F' is true if a font \[la]name\[ra] exists.
697 `S' is true if a style \[la]name\[ra] has been registered.
700 Cyrillic characters have been added to the `utf8' and `html' output
710 The `by' argument in a `for' loop can now be negative if it is additive.
711 For the multiplicative case, it must be greater than zero.
720 The following keywords aren't new but haven't been documented previously:
723 \fBundef NAME\fP (to undefine a macro)
725 \fBcopy "FILE"\fP (a synonym for `include')
727 \fBspace n\fP (to modify the vertical spacing before and after an equation)
731 The following macros aren't new but haven't been documented previously:
734 \fBAlpha, .\|.\|., Omega\fP (the same as `ALPHA', .\|.\|., `OMEGA')
736 \fBldots\fP (three dots on the base line)
738 \fBdollar\fP (a dollar glyph)
742 The following keywords have been extended. Again, this isn't new but
743 hasn't been documented previously:
763 (set vertical spacing between rows to\~N)
772 This device driver has been raised to beta stage; its set of tags should
776 New command line option `\-s' to set the base point size.
779 New command line option `\-S' to set the split level while generating
789 Experimental support for zero-width and double-width characters.
798 On platforms which have the X\~Window System this program is now built and
799 installed automatically.
808 This program to create font definition files for xditview isn't new but
809 hasn't been installed previously.
818 A security problem (reported as CAN-2004-0969) has been fixed.
827 A new script contributed by Mike Bianchi.
828 It compares two groff, nroff, or troff documents and creates an output with
829 added margin characters (using `.mc') to indicate the differences.
838 A new wrapper script contributed by Keith Marshall to easily create PDF
839 documents with groff.
852 Support for fractional point sizes: A value for the `PS', `VS', `FPS',
853 and `VPS' register larger than or equal to 1000 is always divided by 1000.
854 For example, `.nr\~PS\~10250' sets the document's font size to 10.25 points.
857 The `Ds' and `De' macros provided in ms since groff version 1.19 have
858 been removed; the equivalent `DS' and `DE' macros should be used instead.
859 X11 documents which actually use `Ds' and `De' always load a
860 specific macro file from the X11 distribution (`macros.t') which
861 provides proper definitions for the two macros.
864 The following registers have been added for improving layout control:
867 Defines number of lines following `LP', `PP', `QP', `IP' or `XP' which
868 must be kept together, before any automatic page break.
871 Sets number of lines of following paragraph which must be kept with a
872 heading, defined by `NH' or `SH', before any automatic page break.
875 Sets the first level of heading (set with `NH') which keeps the
876 same point size as body text.
879 Sets the point size increment for each level of heading (set with
880 `NH'), below the threshold level set by `GROWPS'; e.g., if
881 \en[PS]\~=\~10, \en[GROWPS]\~=\~3 and \en[PSINCR]\~=\~2.0p, then `.NH\~1'
882 produces 14pt headings, `.NH\~2' produces 12pt, and all other levels
883 remain at 10pt (because \en[PS]\~=\~10).
886 The `SH' macro now accepts a numeric argument, to make heading size
887 match that of `NH' with same argument value when the `GROWPS'/`PSINCR'
891 Please refer to the documentation of the ms package for other, minor
897 The section type set with the `++' request is available in the `_M'
899 This isn't new but hasn't been documented before.
904 The `HR' macro no longer causes an empty line for non-HTML devices.
906 A new macro `HEAD' has been added to directly add data to the
907 <head>...</head> block.
909 New macros `OLS' and `OLE' to start and end an ordered list.
911 New macros `DLS' and `DLE' to start and end a definition list.
920 A new macro package contributed by Keith Marshall which implements PDF
922 This is in alpha stage currently.
931 Two new keywords to the DESC file have been added which are needed for
932 grohtml: `image_generator' and `unscaled_charwidths'.
933 The former gives the name of the program which creates PNG images,
934 and the latter makes troff always use unscaled character widths.
946 The argument of the command line option `\-I' is now also passed to troff
947 and grops, specifying a directory to search for files on the command line,
948 files named in `so' and `psbb' requests, and files named in \eX'ps:\~file'
949 and \eX'ps:\~import' escapes.
952 If option `\-V' is used more than once, the commands are both printed
953 on standard error and run.
962 Two new read-only, string-valued registers `.m' and `.M' return the
963 name of the current drawing and background color, respectively.
966 New read-only register `.U' which is set to\~1 if in safer mode and set
967 to\~0 if in unsafe mode.
970 An input encoding file for \%latin-5 (a.k.a.\& ISO \%8859-9) has been
976 groff \-Tdvi \-mlatin5 my_file > my_file.dvi
980 Note that some output devices don't support all glyphs of this encoding.
983 If the `return' request is called with an argument, it exits twice,
984 namely the current macro and the macro one level higher.
985 This is used to define a wrapper macro for `return' in trace.tmac.
988 For completeness, two new requests have been added: `dei1' and `ami1'.
989 They are equivalent to `dei' and `ami', respectively, but the macros
990 are executed with compatibility mode off (similar to `de1' and `am1').
993 New command line option `\-I' to specify a directory for files (both
994 those on the command line and those named in `psbb' requests).
995 This is also handled by the groff wrapper program.
998 Since version 1.19 you can say `.vs\~0'.
999 Older versions emit a warning and convert this to `.vs\~\en[.V]'.
1001 This hasn't been documented properly.
1002 Note that `.vs\~0' isn't saved in a diversion since it doesn't result
1012 Dashed and dotted ellipses have been implemented.
1021 New key character `x' to make tbl call a user-defined macro on a table
1024 .MTO hj.oertel@\:surfeu.de "Heinz-J\[:u]rgen Oertel" .
1033 A new script contributed by
1034 .MTO esr@\:thyrsus.com "Eric S. Raymond" .
1035 It converts a grap diagram into a cropped image.
1036 Since it uses gs and the PNM library, virtually all graphics formats
1037 are available for output.
1038 [Note that the grap program itself isn't part of the groff package;
1039 see the file MORE.STUFF how to obtain grap.]
1048 New option `\-j' to emit output split into multiple files.
1057 New command line option `\-I' to specify a directory to search for files
1058 on the command line and files named in \eX'ps:\~import' and \eX'ps:\~file'
1060 This is also handled by the groff wrapper program.
1063 The default value for the `broken' keyword in the DESC file is now\~0.
1072 A new man page `lj4_font(5)' documents how fonts are accessed with
1076 The built-in fonts for LJ4 and newer PCL\~5 devices have been completely
1077 revised, mainly to access as much glyphs as possible.
1078 The provided metric files should be compatible with recent PCL\~5 printers
1080 Additionally, font description files have been added for the Arial and
1081 Times New Roman family, the MS symbol, and Wingdings fonts.
1090 New option `\-x' to prevent use of built-in Adobe Glyph List.
1099 Completely revised to handle HP TrueType metric files also.
1100 See the hpftodit manual page for more details.
1109 This version is a rewrite of groffer in many parts, but it is kept in
1110 the old single script style.
1114 New options: \-\-text (\-\-mode\~text), \-\-tty-viewer, \-\-X (\-\-mode\~X),
1115 \-\-X-viewer, \-\-html (\-\-mode\~html), \-\-html-view, \-\-apropos-data,
1116 \-\-apropos-devel, \-\-apropos-progs.
1119 New documentation file README_SH.
1122 Enhancement of the configuration files and the `apropos' handling.
1132 www.tmac: New macro `JOBNAME' to split output into multiple files.
1135 In mdoc, multiple calls to `.Lb' are now supported in the LIBRARY
1148 Input encoding files for \%latin-9 (a.k.a.\& \%latin-0 and ISO \%8859-15)
1149 and \%latin-2 (ISO \%8859-2) have been added.
1154 groff -Tdvi -mlatin9 my_file > my_file.dvi
1158 You still need proper fonts with the necessary glyphs.
1159 Out of the box, the groff package supports \%latin-9 only for \-Tps,
1160 \-Tdvi, and \-Tutf8, and \%latin-2 only for \-Tdvi and \-Tutf8.
1163 Composite glyphs are now supported.
1164 To do this, a subset of the Adobe Glyph List (AGL) Algorithm as described in
1165 .URL http://partners.adobe.com/public/developer/opentype/index_glyph.html \
1166 http://partners.adobe.com/public/developer/opentype/index_glyph.html
1167 is used to construct glyph names based on Unicode character codes.
1168 The existing groff glyph names are frozen; no glyph names which can't be
1169 constructed algorithmically will be added in the future.
1171 The \e[...] escape sequence has been extended to specify multiple glyph
1181 this accesses a glyph with the name `u0041_0328'.
1183 Some groff glyphs which are useful as composites map to `wrong' Unicode
1185 For example, `ho' maps to U+02DB which is a spacing ogonek, whereas a
1186 non-spacing ogonek U+0328 is needed for composite glyphs.
1191 \&.composite from to
1195 changes the mapping while a composite glyph name is constructed.
1196 To make \e[A\~ho] yield the expected result,
1200 \&.composite ho u0328
1205 [The new file `composite.tmac' loaded at start-up already
1206 contains proper calls to `.composite'.]
1208 Please refer to the info pages of groff and to the groff_char man page
1212 A new request `fschar' has been added to define font-specific fallback
1214 They are searched after the list of fonts declared with the
1215 `fspecial' request but before the list of fonts declared with `special'.
1218 Fallback characters defined with `fschar' can be removed with the
1219 new `rfschar' request.
1222 A new request `schar' has been added to define global fallback
1224 They are searched after the list of fonts declared with the
1225 `special' request but before the already mounted special fonts.
1228 In groff versions 1.18 and 1.18.1, \eD'f\~...'\& didn't move the current
1230 Despite of being silly, this change has been reverted for backwards
1232 Consequently, the intermediate output command `Df' also moves the
1233 position horizontally again.
1235 \eD'f\~...'\& is deprecated since it depends on the horizontal resolution
1236 of the output device (given with the `hor' parameter in the DESC file).
1237 Use the new \eD'Fg\~...'\& escape instead.
1240 For orthogonality, new \eD subcommands to change the fill color are
1245 \eD'Fr ...' \f[R](rgb)\f[]
1247 \eD'Fc ...' \f[R](cmy)\f[]
1249 \eD'Fg ...' \f[R](gray)\f[]
1251 \eD'Fk ...' \f[R](cmyk)\f[]
1253 \eD'Fd' \f[R](default color)\f[]
1257 The arguments are the same as with the `defcolor' request.
1258 The current position is \f[I]not\f[] changed.
1261 The values set with \eH and \eS are now available in number registers
1262 \en[.height] and \en[.slant], respectively.
1265 The `.pe' number register isn't new but hasn't been documented before.
1266 It is set to\~1 during a page ejection caused by the `bp' request.
1269 The new glyph symbol `tno' is a textual variant of `no'.
1272 The new glyph symbol `+e' represents U+03F5, GREEK LUNATE EPSILON SYMBOL.
1273 (Well, it is not really new since it has been previously supported by
1275 The mapping for both the dvi and lj4 symbol font has been
1276 changed accordingly so that Greek small letter epsilon, `*e', has the
1277 same glyph shape as with other devices.
1286 The font `freeeuro.pfa' has been added to provide various default glyph
1287 shapes for `eu' and `Eu'.
1290 It is now possible to access all glyphs in a Type\~1 font, not only 256
1291 (provided the font file created by afmtodit has proper entries).
1292 grops constructs additional encoding vectors on the fly if necessary.
1295 The paper size is now emitted via the %%DocumentMedia and PageSize
1296 mechanisms so that it is no longer required to tell `gv' or `ps2pdf'
1297 about the paper size.
1298 The `broken' flag value\~16 omits this feature
1299 (the used PostScript command `setpagedevice' is a LanguageLevel\~2
1302 .MTO egil@\:kvaleberg.no "Egil Kvaleberg" .
1305 Non-slanted PostScript metrics have been changed again; they no longer
1306 contain negative left italic correction values.
1307 This assures correct spacing with eqn.
1316 The font cmtex10 has been added as the special font `SC' to the DVI fonts.
1317 It is used as a font-specific special font for CW and CWI.
1320 New options \-l and \-p to set landscape orientation and the paper size.
1321 grodvi now emits a `papersize' special which is understood by DVI drivers
1324 Consequently, the DESC file should contain a `papersize' keyword.
1327 The glyph shapes for \e[*f] and \e[*e] have been exchanged with \e[+f] and
1328 \e[+e], respectively, to be in sync with all other devices.
1331 Glyphs \e[HE] and \e[DI] have been replaced with \e[u2662] and \e[u2661],
1332 respectively, since the former two glyphs have a black (filled) shape
1333 which grodvi doesn't provide by default (it never has actually).
1342 The glyphs \e[*e] and \e[+e] have been exchanged to be in sync with
1346 The glyph \e[~=] is now called \e[|=]. Similar to other devices, \e[~=]
1347 is now another name for glyph \e[~~].
1357 It is similar to the \-i option except it tells grotty to
1358 use the `reverse video' attribute to render italic fonts.
1367 New command `figname' to set the name of a picture's output box in TeX
1377 The environment variable `REFER' to override the name of the default
1378 database isn't new but hasn't been documented before.
1387 New option `\-r' to avoid emission of `.lf' lines.
1390 New option `\-t' to emit TeX comment lines (giving current file and the
1391 line number) instead of `.lf' lines.
1400 Unencoded glyphs in an AFM file are output also (since grops can now emit
1401 multiple encoding vectors for a single font).
1404 New option `\-m' to prevent negative left italic correction values.
1407 The mapping and encoding file together with file `DESC' are now searched
1408 in the default font directory also.
1409 Please refer to the man page of afmtodit for more details.
1418 .MTO kollar@\:alltel.net "Larry Kollar"
1419 and others made the man macros more customizable.
1423 New command line options \-rFT, \-rIN, and \-rSN to set the vertical
1424 location of the footer line, the body text indentation, and the
1425 sub-subheading indentation.
1428 New command line option \-rHY (similar to the ms macros) to control
1432 New macros `.PT' and `.BT' to print the header and footer strings.
1433 They can be replaced with a customized version in `man.local'.
1436 The string `HF' now holds the typeface to print headings and
1440 Similar to the ms macros, the LT register now defaults to LL if not
1441 explicitly specified on the command line.
1445 troff's start-up file `troffrc' now includes `papersize.tmac' to set
1446 the paper size with the command line option `-dpaper=<size>'.
1448 Possible values for `<size>' are the same as the predefined `papersize'
1449 values in the DESC file (only lowercase; see the groff_font man page)
1451 An appended `l' (ell) character denotes landscape orientation.
1452 Examples: `a4', `c3l', `letterl'.
1454 Most output drivers need additional command line switches `\-p' and
1455 `\-l' to override the default paper length and orientation as set in
1456 the driver specific DESC file.
1458 For example, use the following for PS output on A4 paper in landscape
1463 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1477 The non-slanted PostScript font definition files have been regenerated to
1478 include left and right italic correction values.
1479 Applying those to a glyph (this is, prepending the glyph with `\e,' and
1480 appending `\e/' to the glyph) sets the glyph width to the real value given
1481 by the horizontal bounding box values.
1482 Without those escapes, the advance width for the particular glyph is used
1483 (which can differ considerably).
1485 Most users will neither need this feature nor notice a difference in
1486 existing documents (provided \e, and \e/ is used as advertised, namely for
1487 italic fonts only); its main goal is to improve image generation with
1490 This is an experimental change, and feedback is welcome.
1498 Added global option `nospaces' to ignore leading and trailing spaces in data
1507 The option \-w (\-\-linewidth) has been added (similar to other device
1508 drivers) to set the default line width.
1516 Support for b-spline and Bezier curves has been added.
1524 New option \-\-shell to select the shell under wich groffer shall run.
1532 The string `Am' (producing an ampersand) has been added to mdoc for
1533 compatibility with NetBSD.
1536 `.IX' is now deprecated for mom; you should use `.IQ' (Indent Quit)
1540 In mom, new inlines `FWD', `BCK', `UP', and `DOWN' deal with horizontal
1541 and vertical movements; please refer to contrib/mom/NEWS for more
1545 New macro ENDNOTES_HDRFTR_CENTER for mom to better control headers.
1553 The `papersize' keyword in the DESC file now accepts multiple arguments.
1554 It is scanned from left to the right, and the first valid argument is used.
1555 This makes it possible to provide a fallback paper size.
1561 papersize /etc/papersize a4
1566 A local font directory has been prepended to the default font path; it
1567 defaults to /usr/local/share/groff/site-font. Similar to the normal
1568 font searching process, files must be placed into a dev\f[I]XXX\f[]
1573 /usr/local/share/groff/site-font/devps/FOO
1577 for a PostScript font definition file FOO.
1584 This section describes recent user-visible changes in groff.
1585 Bug fixes are not described.
1586 There are more details in the man pages.
1590 Please read the changes below regarding
1592 . URL #grotty grotty ,
1595 groff's tty frontend.\
1605 Color support has been added to troff and pic (and to the device drivers
1606 grops, grodvi, grotty, and grohtml -- other preprocessors and drivers will
1608 A new function `defcolor' defines colors; the escape sequence `\em' sets the
1609 drawing color, the escape sequence `\eM' specifies the background color for
1610 closed objects created with \eD'.\|.\|.' commands.
1611 `\em[]' and `\eM[]' switch back to the previous color.
1612 `\em' and `\eM' correspond to the new troff output command sets starting
1614 The device-specific default color is called `default' and can't be
1617 Use the `color' request to toggle the usage of colors (default is on); the
1618 read-only register `.color' is\~0 if colors are not active, and non-zero
1621 The old `Df' output command is mapped onto `DFg'; all color output
1622 commands don't change the current font position (consequently, `Df'
1625 Outputting color can be disabled in troff and groff with the option\~\-c
1626 (it is always disabled in compatibility mode).
1627 See the section on grotty for the
1629 . URL #GROFF_NO_SGR GROFF_NO_SGR
1632 environment variable also.
1634 For defining color components as fractions between 0 and\~1, a new scaling
1635 indicator `f' has been defined: 1f\~=\~65536u.
1636 For testing whether a color is defined (with .if and .ie), a new
1637 conditional operator `m' is available.
1639 More details can be found in the groff_diff.7 manual page and in
1643 Similar to \em and \eM, \ef[] switches back to the previous font.
1644 \efP (and \ef[P]) is still valid for backwards compatibility.
1647 The new escape \eF is the same as `.fam'; \eF[] switches back to previous
1648 family -- \eF[P] selects family `P'.
1651 Two new glyph symbols are available: `eu' is the official Euro symbol;
1652 `Eu' is a font-specific glyph variant.
1655 The new glyph symbols `t+\-', `tdi', and `tmu' are textual variants of
1656 `+\-', `di', and `mu', respectively.
1659 Latin-1 character 181 (PS name `mu', Unicode name U+00B5 MICRO SIGN) has
1660 got the troff glyph name `mc'.
1663 \-Tutf8 is now available on EBCDIC hosts.
1666 Strings can take arguments, using this syntax: \e*[foo\~arg1\~arg2\~.\|.\|.].
1672 \&.ds xxx This is a \e\e$1 test.
1679 It is now possible to have whitespace between the first and second dot (or
1680 the name of the ending macro) to end a macro definition.
1690 \&. nop Hello, I'm `foo'.
1691 \&. nop I will now define `bar'.
1693 \&. nop Hello, I'm `bar'.
1701 `.fn' is a new string-valued register which returns the (internal) real
1702 font name; styles and families are properly concatenated.
1705 Three new read/write registers `seconds', `minutes', and `hours' contain
1706 the current time, set at start-up of troff.
1707 Use the `af' request to control their output format.
1710 The new request `fchar' can be used to provide fallback characters.
1711 It has the same syntax as the `char' request; the only difference is that
1712 a character defined with `.char' hides the glyph with the same name in the
1713 current font, whereas a character defined with `.fchar' is checked only if
1714 the particular glyph isn't found in the current font.
1715 This test happens before checking special fonts.
1718 In analogy to the `tmc' request, `.writec' is the same as `.write' but
1719 doesn't emit a final newline.
1722 The new request `itc' is a variant of `.it' for which a line interrupted
1723 with \ec counts as one input line.
1726 Two new requests `ds1' and `as1' which are similar to `ds' and `as' but
1727 with compatibility mode disabled during expansion of strings defined by
1731 The syntax of the `substring' request has been changed:
1732 The first character in a string now has index\~0, the last character
1734 Note that this is an incompatible change.
1737 To emit strings directly to the intermediate output, a new `output'
1738 request has been added; it is similar to `\e!' used at the top level.
1741 `.hpf' has been extended.
1742 It can now handle most TeX hyphenation pattern files without
1744 To do that, the commands \epatterns, \ehyphenation, and \eendinput are
1746 Please refer to groff_diff.7 for more information.
1749 `hpfcode' is a new request to provide an input encoding mapping for the
1753 The new request `hpfa' appends hyphenation patterns (`hpf' replaces
1754 already existing patterns).
1757 A new request `ami' (append macro indirect) has been added.
1758 The first and second parameter of `ami' are taken from string registers
1759 rather than directly; this very special request is needed to make
1760 `trace.tmac' independent from the escape character (which might even
1764 The new request `sizes' is similar to the `sizes' command in DESC files.
1765 It expects the same syntax; the data must be on a single line, and the
1766 final `0' can be omitted.
1769 `trin' (translate input) is a new request which is similar to `tr' with
1770 the exception that the `asciify' request uses the character code (if
1771 any) before the character translation.
1790 The result is `x\~a'. Using `tr', the result would be `x\~x'.
1793 The request `pvs' isn't new, but hasn't been documented before.
1794 It adds vertical space after a line has been output.
1795 This makes it an alternative to the `ls' request to produce
1796 double-spaced documents.
1797 The read-only register `.pvs' holds the current amount of the
1798 post-vertical line space.
1801 For compatibility with plan 9's troff, multiple `pi' requests are
1813 is now equivalent to
1822 A new escape sequence `\eO' is available to disable and enable glyph
1824 Please see groff_diff.man and groff.texinfo for more details.
1827 The escapes `\e%', `\e&', `\e)', and `\e:' no longer cause an error in \eX;
1828 they are ignored now.
1829 Additionally `\e\ ' and `\e~' are converted to single space characters.
1832 The default tab distance in nroff mode is now 0.8i to be compatible
1836 Using the latin-1 input character 0xAD (soft hyphen) for the `shc'
1837 request was a bad idea.
1838 Instead, it is now translated to `\e%', and the default hyphenation
1839 character is again \e[hy].
1840 Note that the glyph \e[shc] is not useful for typographic purposes;
1841 it only exists to have glyph names for all latin-1 characters.
1849 .MTO df191@\:ncf.ca "Peter Schaffter"
1850 has contributed a new major macro package called `mom', mainly for
1851 non-scientific writers, which takes care of many typographic issues.
1852 It comes with a complete reference (in HTML format) and some examples.
1853 `mom' has been designed to format documents for PostScript output only.
1856 Two macros `AT' (AT&T) and `UC' (Univ. of California) have been added to
1857 the man macros for compatibility with older BSD releases.
1860 Both the man and mdoc macro packages now use the LL and LT registers for
1861 setting the line and title length, respectively (similar to those
1862 registers in the ms macro package).
1863 If not set on the command line or in a macro file loaded before the macro
1864 package itself, they default to 78n in nroff mode and 6.5i in troff mode.
1867 The `\-xwidth' specifier in the mdoc macro package has been removed.
1868 Its functionality is now integrated directly into `\-width'.
1869 Similarly, `\-column' has been extended to has this functionality also.
1872 A new macro `Ex' has been added to the mdoc macro package to document an
1876 `troff.man' has been split. Differences to UNIX troff are now documented
1877 in the new man page `groff_diff.man'.
1880 The PSPIC macro has been extended to work with DVI output (`pspic.tmac' is
1881 now automatically loaded for \-Tdvi), using a dvips special to load the EPS
1885 The trace.tmac package now traces calls to `am' also.
1886 Additionally, it works in compatibility mode.
1889 `troff.1' has been split.
1890 Differences to UNIX troff are now documented in the new man page
1894 `groff_mwww.7' has been renamed to `groff_www.7'.
1895 The file mwww.tmac has been removed.
1898 `groff_ms.7' has been completely rewritten.
1899 It now contains a complete reference to the ms macros.
1902 `groff_trace.7' documents the trace macro package.
1907 Note that HTML support is still in alpha change, so it is rather likely
1908 that both macro names and macro syntax will change.
1909 Some of the macros mentioned below aren't really new but haven't been
1910 documented properly before.
1914 The following macros have been renamed:
1925 For consistency, the macros `URL', `FTL', and `MTO' now all have the
1926 address as the first parameter followed by the description.
1929 By default, grohtml generates links to all section headings at the top
1931 Use the new `LK' macro to specify a different place.
1934 For specifying the background color and a background image, use the
1935 new macros `BCL' and `BGIMG', respectively.
1938 The macro `NHR' has been added; it suppresses the generation of top and
1939 bottom rules which grohtml emits by default.
1942 The new macro `HX' determines the cut-off point for automatic link
1943 generation to headings.
1946 The image position parameter names in `IMG' have been changed to `\-L',
1950 New macro `PIMG' for inclusion of a PNG image (it automatically
1951 converts it into an EPS file if not \-Thtml is used).
1954 New macro `MPIMG' for putting a PNG image into the left or right margin
1955 (it automatically converts it into an EPS file if not \-Thtml is used).
1958 New macros `HnS', `HnE' to start and end a header line block.
1961 New macro `DC' to produce dropcap characters.
1964 New macro `HTL' to generate an HTML title line only but no H1 heading.
1967 New macros `ULS' and `ULE' to start and end an unordered list.
1968 The new macro `LI' inserts a list item.
1978 The new command line `\-c' disables color output (which is always disabled
1979 in compatibility mode).
1988 Two new command line options `\-c' and `\-C'; the former passes `\-c' to
1989 grotty (switching to the old output scheme); the latter passes `\-C' to
1990 groff (enabling compatibility mode).
1999 New keywords `color' (or `colour', `colored', `coloured'), `outline' (or
2000 `outlined'), and `shaded' are available.
2001 `outline' sets the color of the outline, `shaded' the fill color, and
2007 circle shaded "green" outline "black" ;
2011 Filled arrows always use the outline color for filling.
2013 Color support for TeX output is not implemented yet.
2022 A new script contributed by
2023 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
2024 It converts a PIC diagram into a cropped image.
2025 Since it uses gs and the PNM library, virtually all graphics formats
2026 are available for output.
2035 A new script contributed by
2036 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
2037 It converts an EQN diagram into a cropped image.
2038 Since it uses gs and the PNM library, virtually all graphics formats
2039 are available for output.
2048 A new script contributed by
2049 .MTO bwarken@mayn.de "Bernd Warken" .
2050 It displays groff files and man pages on X and tty, taking care of most
2051 parameters automatically.
2060 Documents using the mom macro package are recognized.
2069 Color support has been added.
2072 A new option `\-p' is available to select the output paper size.
2073 It has the same syntax as the new `papersize' keyword in the DESC file.
2082 By default, font sizes are now available in the range 5\-10000pt, similar
2084 If you want the old behaviour (i.e., font sizes at discrete values only),
2085 insert the following at the start of your document:
2090 \&.if '\e*[.T]'dvi' \e
2091 \&. sizes 500 600 700 800 900 1000 1095 1200 1400 1440 1600 \e
2092 \& 1728 1800 2000 2074 2200 2400 2488 2800 3600
2098 A new font file HBI (using cmssbxo10; this is slanted sans serif bold
2099 extended) has been added.
2102 Two font families are now available: `T' and `H'.
2105 EC and TC fonts have been integrated.
2106 Use `\-mec' (calling the file ec.tmac) to switch to them.
2107 Those fonts give a much better coverage of the symbols defined by groff
2110 Note that ec.tmac must be called before any language-specific files; it
2111 doesn't take care of hcode values.
2114 Color support has been added.
2115 For drawing commands, colors are translated to gray values currently.
2125 Color support has been added, using the SGR (ISO\~6429, sometimes called
2126 ANSI color) escape sequences.
2129 SGR escape sequences are now used by default for underlining and bold
2130 printing also, no longer using the backspace character trick.
2131 To revert to the old behaviour, use the `\-c' switch.
2133 Note that you have to use the `\-R' option of `less' to make SGR escapes
2135 On the other hand, terminal programs and consoles like `xterm' which
2136 support SGR sequences natively can directly display the output of grotty.
2137 Consequently, the options `\-b', `\-B', `\-u', and `\-U' work only in
2138 combination with `\-c' and are ignored silently otherwise.
2140 For the `man' program, it may be necessary to add the `\-R' option of
2141 `less' to the $PAGER environment variable (or $MANPAGER, depending on the
2142 used version of `man'); alternatively, you can use `man's `\-P' option (or
2143 adapt its configuration file accordingly).
2144 See man(1) for more details.
2148 If the environment variable GROFF_NO_SGR is set, SGR output is disabled,
2149 reverting to the old behaviour.
2152 A new special \eX'tty:\~sgr\~n' has been added; if n is non-zero or missing,
2153 enable SGR output (the default).
2156 If the new option `\-i' is used (only in SGR mode), grotty sends escape
2157 sequences to set the italic font attribute instead of the underline
2158 attribute for italic fonts.
2159 Note that many terminals don't have support for this (including xterm).
2168 Color support for glyphs has been added.
2171 New option `\-h' to select the style of headings in HTML output.
2174 New option `\-b' to set the background colour to white.
2177 New options `\-a' and `\-g' to control the number of bits for anti-aliasing
2178 used for text and graphics, respectively.
2179 Default value is\~4; 0\~means no anti-aliasing.
2182 groff character/glyph entities now map onto HTML\~4 character entities.
2191 Valid paper sizes are now specified as with the new `papersize' keyword
2193 Specifically, the old custom paper type format `custAAAxBBB' is no longer
2203 A new manual page `ditroff.7' is available.
2206 The groff texinfo manual is now installed, together with a bunch
2210 A new keyword `papersize' has been added to the DESC file format.
2211 Its argument is either
2215 a predefined paper format (e.g. `A4' or `letter')
2218 a file name pointing to a file which must contain a paper size
2219 specification in its first line (e.g. `/etc/papersize')
2222 a custom paper size definition like `35c,4i'
2225 See groff_font(5) for more details.
2226 This keyword only affects the physical dimensions of the output medium;
2227 grops, grolj4, and grolbp use it currently.
2228 troff completely ignores it.