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
13 .HEAD "<link rel=""stylesheet"" type=""text/css"" href=""groff.css"" >"
14 .\" .HEAD "<link rel=""icon"" type=""image/png"" href=""http://www.gnu.org/graphics/gnu-mini.png"" >"
28 .defcolor mydarkred rgb 0.65f 0.1f 0.2f
29 .defcolor mydarkgreen rgb 0.1f 0.5f 0.2f
30 .defcolor mydarkblue rgb 0.1f 0.2f 0.6f
32 .ds GNU \m[mydarkred]G\m[]\m[mydarkgreen]N\m[]\m[mydarkblue]U\m[]
37 Home of Groff (GNU Troff).
40 .PSPIC -L gnu.eps 2i 2i
42 . nop \v'-0.66i'\h'2.0i'\s[80]\*[GNU] Troff\s0
44 . nop \v'-0.66i'\h'2.0i'\s[60]\*[GNU] Troff\s0
52 is the home page for groff (\c
53 .URL http://\:www.gnu.org/ GNU
56 Groff is a software typesetting package which reads plain text mixed with
57 formatting commands and produces formatted output.
59 The source code of the currently released versions of groff is
61 .URL "http://\:groff.ffii.org/\:groff/" "FFII host (Germany)" ,
62 .URL "ftp://\:ftp.gnu.org/\:gnu/\:groff/" "GNU host (USA)" ,
65 The USA site also contains older, obsolete versions.
67 The development version is available from a CVS repository, see below.
69 Development snapshots (produced twice a day from the CVS repository)
70 can be downloaded from
71 .URL "http://\:groff.ffii.org/\:groff/\:devel" here .
73 For a special version of groff on the Microsoft operating systems, see
74 .URL "http://\:gnuwin32.sf.net/\:packages/\:groffl.htm" "Groff for Windows" .
76 Groff was originally written and maintained by James Clark, however it
78 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding"
80 .MTO wl@\:gnu.org "Werner Lemberg" .
83 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding" .
85 Technical issues lead:
86 .MTO wl@\:gnu.org "Werner Lemberg" .
90 \s[-4]\f[I]This document was produced using
91 .URL http://groff.ffii.org/ groff-\n[.x].\n[.y].\n[.Y] .
93 The image at the top has been contributed by Imogen Mulley (born 1991),
94 based on a similar picture found on the
95 .URL http://www.gnu.org "GNU server" .
102 GNU troff is released under the
103 .URL http://\:www.gnu.org/\:copyleft/\:gpl.html "GNU Copyright License" .
104 The documentation is released under the
105 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "Free Documentation License" .
106 Groff is an official GNU project as defined on
107 .URL http://\:savannah.gnu.org savannah .
112 This is the GNU groff document formatting system.
113 The version number is given in the file VERSION.
115 Included in this release are implementations of troff, pic, eqn, tbl,
116 grn, refer, \-man, \-mdoc, and \-ms macros, and drivers for PostScript,
117 TeX dvi format, HP LaserJet\~4 printers, Canon CAPSL printers, HTML format
118 (beta status), and typewriter-like devices.
119 Also included is a modified version of the Berkeley \-me macros, an enhanced
120 version of the X11 xditview previewer, and an implementation of the \-mm
121 macros contributed by
122 .MTO jh@\:axis.se "J\[:o]rgen H\[:a]gg" .
124 See the file INSTALL for installation instructions.
125 You require a C++ compiler.
127 The file NEWS describes recent user-visible changes to groff.
129 Groff is free software.
130 See the file COPYING for copying permission.
132 The file PROBLEMS describes various problems that have been encountered in
133 compiling, installing, and running groff.
138 The most recent released version of groff is always available by
139 .URL "ftp://\:ftp.gnu.org/\:gnu/\:groff" "anonymous ftp" .
141 The current development version of groff is available from a
142 .URL "http://\:savannah.gnu.org/\:cvs/\:?group=groff" "CVS repository" .
143 You can access it by first selecting a parent directory in
144 which to create a working copy (call it, say, ~/cvswork), and then
145 executing the commands
151 cvs -d:pserver:anoncvs@savannah.gnu.org:/cvsroot/groff login
152 cvs -d:pserver:anoncvs@savannah.gnu.org:/cvsroot/groff -z5 co groff
157 When asked for a password during the `login' call, simply press Enter.
159 This creates a subdirectory, ~/cvswork/groff, with a `checked out'
160 copy of the CVS repository.
161 An update of this working copy may be
162 achieved, at any later time by invoking the commands
173 Please read the CVS info pages for further details.
175 Finally, it is possible to access the CVS with a
176 .URL http://\:savannah.gnu.org/\:cvs/\:?group=groff "web browser" .
178 Alternatively, you can download snapshots (which are updated twice a day).
179 The complete groff source as a single file is available
180 .URL http://\:groff.ffii.org/\:groff/\:devel/\:groff-current.tar.gz here .
182 A diff file relative to groff-\[la]version\[ra], the latest official groff
183 release is available at
187 http://groff.ffii.org/groff/devel/groff-\[la]version\[ra]-current.diff.gz
191 Assuming that groff-\[la]version\[ra].tar.gz and
192 groff-\[la]version\[ra]-current.diff.gz are in the same directory, do the
193 following to apply the diff file:
198 tar xzvf groff-\[la]version\[ra].tar.gz
199 cd groff-\[la]version\[ra]
200 gunzip -c ../groff-\[la]version\[ra]-current.diff.gz | patch -p1
207 Depending on your requirements, you may need at least some of the
208 following tools to build groff directly from its source:
216 bison \[>=] 1.875b or byacc
220 Note that texinfo and bison or byacc are required only for building from
221 CVS sources (either a checked out working copy, or a daily snapshot).
222 They are not required for building from a stable release tarball.
223 Also note that the version numbers stated are the minimum supported.
224 No version of texinfo < 4.8 work, and the original release of bison
225 1.875 is known not to work; you \fImay\fP find that bison releases < 1.875
226 do work, but in case of difficulty, please update to a later version
227 \fIbefore\fP posting a bug report.
229 For \fIall\fP sources, you need ghostscript for creation of either PDF or
230 HTML output; the netpbm and psutils packages are required only for HTML
232 If you don't intend to produce output in either of these formats, then
233 these packages are unnecessary.
238 Please report bugs using the form in the file BUG-REPORT; the idea of this
239 is to make sure that FSF has all the information it needs to fix the bug.
240 At the very least, read the BUG-REPORT form and make sure that you supply
241 all the information that it asks for.
242 Even if you are not sure that something is a bug, report it using
243 BUG-REPORT: this enables us to determine whether it really is a bug or
249 Three mailing lists are available:
253 .MTO bug-groff@gnu.org bug-groff@gnu.org
257 .MTO groff@gnu.org groff@gnu.org
258 for general discussion of groff
261 .MTO groff-commit@gnu.org groff-commit@gnu.org
262 a read-only list showing commitments to the CVS repository
265 You can post mails directly to the `bug-groff' list, without subscribing
266 (this fact makes the list contain many spam files); to post mails to the
267 `groff' list you must subscribe to it.
269 To subscribe, send e-mail to \[la]list\[ra]-request@\[la]domain\[ra]
271 .MTO groff-request@\:gnu.org groff-request@\:gnu.org
272 for the `groff' list) with the word `subscribe' in either the
273 subject or body of the e-mail (don't include the quotes).
274 Alternatively, you may subscribe by visiting the web pages at
278 .URL http://lists.gnu.org/mailman/listinfo/bug-groff
279 .URL http://lists.gnu.org/mailman/listinfo/groff
280 .URL http://lists.gnu.org/mailman/listinfo/groff-commit
284 Each of these web pages also provides a link to a browseable archive of
285 postings to the corresponding mailing list.
295 Analogously to the .ft and \ef pair, two new requests `gcolor' and
296 `fcolor' (which pair with \em and \eM, respectively) have been added to
297 set the glyph and background colours.
300 A new read-only, string-valued register `.sty' returns the name of the
304 Two new conditional operators `F\~\[la]name\[ra]' and `S\~\[la]name\[ra]'
306 `F' is true if a font \[la]name\[ra] exists.
307 `S' is true if a style \[la]name\[ra] has been registered.
310 Cyrillic characters have been added to the `utf8' and `html' output
320 The `by' argument in a `for' loop can now be negative if it is additive.
321 For the multiplicative case, it must be greater than zero.
330 The following keywords aren't new but haven't been documented previously:
333 \fBundef NAME\fP (to undefine a macro)
335 \fBcopy "FILE"\fP (a synonym for `include')
337 \fBspace n\fP (to modify the vertical spacing before and after an equation)
341 The following macros aren't new but haven't been documented previously:
344 \fBAlpha, .\|.\|., Omega\fP (the same as `ALPHA', .\|.\|., `OMEGA')
346 \fBldots\fP (three dots on the base line)
348 \fBdollar\fP (a dollar glyph)
352 The following keywords have been extended. Again, this isn't new but
353 hasn't been documented previously:
373 (set vertical spacing between rows to\~N)
382 This device driver has been raised to beta stage; its set of tags should
386 New command line option `\-s' to set the base point size.
389 New command line option `\-S' to set the split level while generating
399 Experimental support for zero-width and double-width characters.
408 On platforms which have the X\~Window System this program is now built and
409 installed automatically.
418 This program to create font definition files for xditview isn't new but
419 hasn't been installed previously.
428 A security problem (reported as CAN-2004-0969) has been fixed.
437 A new script contributed by Mike Bianchi.
438 It compares two groff, nroff, or troff documents and creates an output with
439 added margin characters (using `.mc') to indicate the differences.
448 A new wrapper script contributed by Keith Marshall to easily create PDF
449 documents with groff.
462 Support for fractional point sizes: A value for the `PS', `VS', `FPS',
463 and `VPS' register larger than or equal to 1000 is always divided by 1000.
464 For example, `.nr\~PS\~10250' sets the document's font size to 10.25 points.
467 The `Ds' and `De' macros provided in ms since groff version 1.19 have
468 been removed; the equivalent `DS' and `DE' macros should be used instead.
469 X11 documents which actually use `Ds' and `De' always load a
470 specific macro file from the X11 distribution (`macros.t') which
471 provides proper definitions for the two macros.
474 The following registers have been added for improving layout control:
477 Defines number of lines following `LP', `PP', `QP', `IP' or `XP' which
478 must be kept together, before any automatic page break.
481 Sets number of lines of following paragraph which must be kept with a
482 heading, defined by `NH' or `SH', before any automatic page break.
485 Sets the first level of heading (set with `NH') which keeps the
486 same point size as body text.
489 Sets the point size increment for each level of heading (set with
490 `NH'), below the threshold level set by `GROWPS'; e.g., if
491 \en[PS]\~=\~10, \en[GROWPS]\~=\~3 and \en[PSINCR]\~=\~2.0p, then `.NH\~1'
492 produces 14pt headings, `.NH\~2' produces 12pt, and all other levels
493 remain at 10pt (because \en[PS]\~=\~10).
496 The `SH' macro now accepts a numeric argument, to make heading size
497 match that of `NH' with same argument value when the `GROWPS'/`PSINCR'
501 Please refer to the documentation of the ms package for other, minor
507 The section type set with the `++' request is available in the `_M'
509 This isn't new but hasn't been documented before.
514 The `HR' macro no longer causes an empty line for non-HTML devices.
516 A new macro `HEAD' has been added to directly add data to the
517 <head>...</head> block.
519 New macros `OLS' and `OLE' to start and end an ordered list.
521 New macros `DLS' and `DLE' to start and end a definition list.
530 A new macro package contributed by Keith Marshall which implements PDF
532 This is in alpha stage currently.
541 Two new keywords to the DESC file have been added which are needed for
542 grohtml: `image_generator' and `unscaled_charwidths'.
543 The former gives the name of the program which creates PNG images,
544 and the latter makes troff always use unscaled character widths.
556 The argument of the command line option `\-I' is now also passed to troff
557 and grops, specifying a directory to search for files on the command line,
558 files named in `so' and `psbb' requests, and files named in \eX'ps:\~file'
559 and \eX'ps:\~import' escapes.
562 If option `\-V' is used more than once, the commands are both printed
563 on standard error and run.
572 Two new read-only, string-valued registers `.m' and `.M' return the
573 name of the current drawing and background color, respectively.
576 New read-only register `.U' which is set to\~1 if in safer mode and set
577 to\~0 if in unsafe mode.
580 An input encoding file for \%latin-5 (a.k.a.\& ISO \%8859-9) has been
586 groff \-Tdvi \-mlatin5 my_file > my_file.dvi
590 Note that some output devices don't support all glyphs of this encoding.
593 If the `return' request is called with an argument, it exits twice,
594 namely the current macro and the macro one level higher.
595 This is used to define a wrapper macro for `return' in trace.tmac.
598 For completeness, two new requests have been added: `dei1' and `ami1'.
599 They are equivalent to `dei' and `ami', respectively, but the macros
600 are executed with compatibility mode off (similar to `de1' and `am1').
603 New command line option `\-I' to specify a directory for files (both
604 those on the command line and those named in `psbb' requests).
605 This is also handled by the groff wrapper program.
608 Since version 1.19 you can say `.vs\~0'.
609 Older versions emit a warning and convert this to `.vs\~\en[.V]'.
611 This hasn't been documented properly.
612 Note that `.vs\~0' isn't saved in a diversion since it doesn't result
622 Dashed and dotted ellipses have been implemented.
631 New key character `x' to make tbl call a user-defined macro on a table
634 .MTO hj.oertel@\:surfeu.de "Heinz-J\[:u]rgen Oertel" .
643 A new script contributed by
644 .MTO esr@\:thyrsus.com "Eric S. Raymond" .
645 It converts a grap diagram into a cropped image.
646 Since it uses gs and the PNM library, virtually all graphics formats
647 are available for output.
648 [Note that the grap program itself isn't part of the groff package;
649 see the file MORE.STUFF how to obtain grap.]
658 New option `\-j' to emit output split into multiple files.
667 New command line option `\-I' to specify a directory to search for files
668 on the command line and files named in \eX'ps:\~import' and \eX'ps:\~file'
670 This is also handled by the groff wrapper program.
673 The default value for the `broken' keyword in the DESC file is now\~0.
682 A new man page `lj4_font(5)' documents how fonts are accessed with
686 The built-in fonts for LJ4 and newer PCL\~5 devices have been completely
687 revised, mainly to access as much glyphs as possible.
688 The provided metric files should be compatible with recent PCL\~5 printers
690 Additionally, font description files have been added for the Arial and
691 Times New Roman family, the MS symbol, and Wingdings fonts.
700 New option `\-x' to prevent use of built-in Adobe Glyph List.
709 Completely revised to handle HP TrueType metric files also.
710 See the hpftodit manual page for more details.
719 This version is a rewrite of groffer in many parts, but it is kept in
720 the old single script style.
724 New options: \-\-text (\-\-mode\~text), \-\-tty-viewer, \-\-X (\-\-mode\~X),
725 \-\-X-viewer, \-\-html (\-\-mode\~html), \-\-html-view, \-\-apropos-data,
726 \-\-apropos-devel, \-\-apropos-progs.
729 New documentation file README_SH.
732 Enhancement of the configuration files and the `apropos' handling.
742 www.tmac: New macro `JOBNAME' to split output into multiple files.
745 In mdoc, multiple calls to `.Lb' are now supported in the LIBRARY
758 Input encoding files for \%latin-9 (a.k.a.\& \%latin-0 and ISO \%8859-15)
759 and \%latin-2 (ISO \%8859-2) have been added.
764 groff -Tdvi -mlatin9 my_file > my_file.dvi
768 You still need proper fonts with the necessary glyphs.
769 Out of the box, the groff package supports \%latin-9 only for \-Tps,
770 \-Tdvi, and \-Tutf8, and \%latin-2 only for \-Tdvi and \-Tutf8.
773 Composite glyphs are now supported.
774 To do this, a subset of the Adobe Glyph List (AGL) Algorithm as described in
775 .URL http://partners.adobe.com/public/developer/opentype/index_glyph.html \
776 http://partners.adobe.com/public/developer/opentype/index_glyph.html
777 is used to construct glyph names based on Unicode character codes.
778 The existing groff glyph names are frozen; no glyph names which can't be
779 constructed algorithmically will be added in the future.
781 The \e[...] escape sequence has been extended to specify multiple glyph
791 this accesses a glyph with the name `u0041_0328'.
793 Some groff glyphs which are useful as composites map to `wrong' Unicode
795 For example, `ho' maps to U+02DB which is a spacing ogonek, whereas a
796 non-spacing ogonek U+0328 is needed for composite glyphs.
805 changes the mapping while a composite glyph name is constructed.
806 To make \e[A\~ho] yield the expected result,
810 \&.composite ho u0328
815 [The new file `composite.tmac' loaded at start-up already
816 contains proper calls to `.composite'.]
818 Please refer to the info pages of groff and to the groff_char man page
822 A new request `fschar' has been added to define font-specific fallback
824 They are searched after the list of fonts declared with the
825 `fspecial' request but before the list of fonts declared with `special'.
828 Fallback characters defined with `fschar' can be removed with the
829 new `rfschar' request.
832 A new request `schar' has been added to define global fallback
834 They are searched after the list of fonts declared with the
835 `special' request but before the already mounted special fonts.
838 In groff versions 1.18 and 1.18.1, \eD'f\~...'\& didn't move the current
840 Despite of being silly, this change has been reverted for backwards
842 Consequently, the intermediate output command `Df' also moves the
843 position horizontally again.
845 \eD'f\~...'\& is deprecated since it depends on the horizontal resolution
846 of the output device (given with the `hor' parameter in the DESC file).
847 Use the new \eD'Fg\~...'\& escape instead.
850 For orthogonality, new \eD subcommands to change the fill color are
855 \eD'Fr ...' \f[R](rgb)\f[]
857 \eD'Fc ...' \f[R](cmy)\f[]
859 \eD'Fg ...' \f[R](gray)\f[]
861 \eD'Fk ...' \f[R](cmyk)\f[]
863 \eD'Fd' \f[R](default color)\f[]
867 The arguments are the same as with the `defcolor' request.
868 The current position is \f[I]not\f[] changed.
871 The values set with \eH and \eS are now available in number registers
872 \en[.height] and \en[.slant], respectively.
875 The `.pe' number register isn't new but hasn't been documented before.
876 It is set to\~1 during a page ejection caused by the `bp' request.
879 The new glyph symbol `tno' is a textual variant of `no'.
882 The new glyph symbol `+e' represents U+03F5, GREEK LUNATE EPSILON SYMBOL.
883 (Well, it is not really new since it has been previously supported by
885 The mapping for both the dvi and lj4 symbol font has been
886 changed accordingly so that Greek small letter epsilon, `*e', has the
887 same glyph shape as with other devices.
896 The font `freeeuro.pfa' has been added to provide various default glyph
897 shapes for `eu' and `Eu'.
900 It is now possible to access all glyphs in a Type\~1 font, not only 256
901 (provided the font file created by afmtodit has proper entries).
902 grops constructs additional encoding vectors on the fly if necessary.
905 The paper size is now emitted via the %%DocumentMedia and PageSize
906 mechanisms so that it is no longer required to tell `gv' or `ps2pdf'
907 about the paper size.
908 The `broken' flag value\~16 omits this feature
909 (the used PostScript command `setpagedevice' is a LanguageLevel\~2
912 .MTO egil@\:kvaleberg.no "Egil Kvaleberg" .
915 Non-slanted PostScript metrics have been changed again; they no longer
916 contain negative left italic correction values.
917 This assures correct spacing with eqn.
926 The font cmtex10 has been added as the special font `SC' to the DVI fonts.
927 It is used as a font-specific special font for CW and CWI.
930 New options \-l and \-p to set landscape orientation and the paper size.
931 grodvi now emits a `papersize' special which is understood by DVI drivers
934 Consequently, the DESC file should contain a `papersize' keyword.
937 The glyph shapes for \e[*f] and \e[*e] have been exchanged with \e[+f] and
938 \e[+e], respectively, to be in sync with all other devices.
941 Glyphs \e[HE] and \e[DI] have been replaced with \e[u2662] and \e[u2661],
942 respectively, since the former two glyphs have a black (filled) shape
943 which grodvi doesn't provide by default (it never has actually).
952 The glyphs \e[*e] and \e[+e] have been exchanged to be in sync with
956 The glyph \e[~=] is now called \e[|=]. Similar to other devices, \e[~=]
957 is now another name for glyph \e[~~].
967 It is similar to the \-i option except it tells grotty to
968 use the `reverse video' attribute to render italic fonts.
977 New command `figname' to set the name of a picture's output box in TeX
987 The environment variable `REFER' to override the name of the default
988 database isn't new but hasn't been documented before.
997 New option `\-r' to avoid emission of `.lf' lines.
1000 New option `\-t' to emit TeX comment lines (giving current file and the
1001 line number) instead of `.lf' lines.
1010 Unencoded glyphs in an AFM file are output also (since grops can now emit
1011 multiple encoding vectors for a single font).
1014 New option `\-m' to prevent negative left italic correction values.
1017 The mapping and encoding file together with file `DESC' are now searched
1018 in the default font directory also.
1019 Please refer to the man page of afmtodit for more details.
1028 .MTO kollar@\:alltel.net "Larry Kollar"
1029 and others made the man macros more customizable.
1033 New command line options \-rFT, \-rIN, and \-rSN to set the vertical
1034 location of the footer line, the body text indentation, and the
1035 sub-subheading indentation.
1038 New command line option \-rHY (similar to the ms macros) to control
1042 New macros `.PT' and `.BT' to print the header and footer strings.
1043 They can be replaced with a customized version in `man.local'.
1046 The string `HF' now holds the typeface to print headings and
1050 Similar to the ms macros, the LT register now defaults to LL if not
1051 explicitly specified on the command line.
1055 troff's start-up file `troffrc' now includes `papersize.tmac' to set
1056 the paper size with the command line option `-dpaper=<size>'.
1058 Possible values for `<size>' are the same as the predefined `papersize'
1059 values in the DESC file (only lowercase; see the groff_font man page)
1061 An appended `l' (ell) character denotes landscape orientation.
1062 Examples: `a4', `c3l', `letterl'.
1064 Most output drivers need additional command line switches `\-p' and
1065 `\-l' to override the default paper length and orientation as set in
1066 the driver specific DESC file.
1068 For example, use the following for PS output on A4 paper in landscape
1073 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
1087 The non-slanted PostScript font definition files have been regenerated to
1088 include left and right italic correction values.
1089 Applying those to a glyph (this is, prepending the glyph with `\e,' and
1090 appending `\e/' to the glyph) sets the glyph width to the real value given
1091 by the horizontal bounding box values.
1092 Without those escapes, the advance width for the particular glyph is used
1093 (which can differ considerably).
1095 Most users will neither need this feature nor notice a difference in
1096 existing documents (provided \e, and \e/ is used as advertised, namely for
1097 italic fonts only); its main goal is to improve image generation with
1100 This is an experimental change, and feedback is welcome.
1108 Added global option `nospaces' to ignore leading and trailing spaces in data
1117 The option \-w (\-\-linewidth) has been added (similar to other device
1118 drivers) to set the default line width.
1126 Support for b-spline and Bezier curves has been added.
1134 New option \-\-shell to select the shell under wich groffer shall run.
1142 The string `Am' (producing an ampersand) has been added to mdoc for
1143 compatibility with NetBSD.
1146 `.IX' is now deprecated for mom; you should use `.IQ' (Indent Quit)
1150 In mom, new inlines `FWD', `BCK', `UP', and `DOWN' deal with horizontal
1151 and vertical movements; please refer to contrib/mom/NEWS for more
1155 New macro ENDNOTES_HDRFTR_CENTER for mom to better control headers.
1163 The `papersize' keyword in the DESC file now accepts multiple arguments.
1164 It is scanned from left to the right, and the first valid argument is used.
1165 This makes it possible to provide a fallback paper size.
1171 papersize /etc/papersize a4
1176 A local font directory has been prepended to the default font path; it
1177 defaults to /usr/local/share/groff/site-font. Similar to the normal
1178 font searching process, files must be placed into a dev\f[I]XXX\f[]
1183 /usr/local/share/groff/site-font/devps/FOO
1187 for a PostScript font definition file FOO.
1194 This section describes recent user-visible changes in groff.
1195 Bug fixes are not described.
1196 There are more details in the man pages.
1200 Please read the changes below regarding
1202 . URL #grotty grotty ,
1205 groff's tty frontend.\
1215 Color support has been added to troff and pic (and to the device drivers
1216 grops, grodvi, grotty, and grohtml -- other preprocessors and drivers will
1218 A new function `defcolor' defines colors; the escape sequence `\em' sets the
1219 drawing color, the escape sequence `\eM' specifies the background color for
1220 closed objects created with \eD'.\|.\|.' commands.
1221 `\em[]' and `\eM[]' switch back to the previous color.
1222 `\em' and `\eM' correspond to the new troff output command sets starting
1224 The device-specific default color is called `default' and can't be
1227 Use the `color' request to toggle the usage of colors (default is on); the
1228 read-only register `.color' is\~0 if colors are not active, and non-zero
1231 The old `Df' output command is mapped onto `DFg'; all color output
1232 commands don't change the current font position (consequently, `Df'
1235 Outputting color can be disabled in troff and groff with the option\~\-c
1236 (it is always disabled in compatibility mode).
1237 See the section on grotty for the
1239 . URL #GROFF_NO_SGR GROFF_NO_SGR
1242 environment variable also.
1244 For defining color components as fractions between 0 and\~1, a new scaling
1245 indicator `f' has been defined: 1f\~=\~65536u.
1246 For testing whether a color is defined (with .if and .ie), a new
1247 conditional operator `m' is available.
1249 More details can be found in the groff_diff.7 manual page and in
1253 Similar to \em and \eM, \ef[] switches back to the previous font.
1254 \efP (and \ef[P]) is still valid for backwards compatibility.
1257 The new escape \eF is the same as `.fam'; \eF[] switches back to previous
1258 family -- \eF[P] selects family `P'.
1261 Two new glyph symbols are available: `eu' is the official Euro symbol;
1262 `Eu' is a font-specific glyph variant.
1265 The new glyph symbols `t+\-', `tdi', and `tmu' are textual variants of
1266 `+\-', `di', and `mu', respectively.
1269 Latin-1 character 181 (PS name `mu', Unicode name U+00B5 MICRO SIGN) has
1270 got the troff glyph name `mc'.
1273 \-Tutf8 is now available on EBCDIC hosts.
1276 Strings can take arguments, using this syntax: \e*[foo\~arg1\~arg2\~.\|.\|.].
1282 \&.ds xxx This is a \e\e$1 test.
1289 It is now possible to have whitespace between the first and second dot (or
1290 the name of the ending macro) to end a macro definition.
1300 \&. nop Hello, I'm `foo'.
1301 \&. nop I will now define `bar'.
1303 \&. nop Hello, I'm `bar'.
1311 `.fn' is a new string-valued register which returns the (internal) real
1312 font name; styles and families are properly concatenated.
1315 Three new read/write registers `seconds', `minutes', and `hours' contain
1316 the current time, set at start-up of troff.
1317 Use the `af' request to control their output format.
1320 The new request `fchar' can be used to provide fallback characters.
1321 It has the same syntax as the `char' request; the only difference is that
1322 a character defined with `.char' hides the glyph with the same name in the
1323 current font, whereas a character defined with `.fchar' is checked only if
1324 the particular glyph isn't found in the current font.
1325 This test happens before checking special fonts.
1328 In analogy to the `tmc' request, `.writec' is the same as `.write' but
1329 doesn't emit a final newline.
1332 The new request `itc' is a variant of `.it' for which a line interrupted
1333 with \ec counts as one input line.
1336 Two new requests `ds1' and `as1' which are similar to `ds' and `as' but
1337 with compatibility mode disabled during expansion of strings defined by
1341 The syntax of the `substring' request has been changed:
1342 The first character in a string now has index\~0, the last character
1344 Note that this is an incompatible change.
1347 To emit strings directly to the intermediate output, a new `output'
1348 request has been added; it is similar to `\e!' used at the top level.
1351 `.hpf' has been extended.
1352 It can now handle most TeX hyphenation pattern files without
1354 To do that, the commands \epatterns, \ehyphenation, and \eendinput are
1356 Please refer to groff_diff.7 for more information.
1359 `hpfcode' is a new request to provide an input encoding mapping for the
1363 The new request `hpfa' appends hyphenation patterns (`hpf' replaces
1364 already existing patterns).
1367 A new request `ami' (append macro indirect) has been added.
1368 The first and second parameter of `ami' are taken from string registers
1369 rather than directly; this very special request is needed to make
1370 `trace.tmac' independent from the escape character (which might even
1374 The new request `sizes' is similar to the `sizes' command in DESC files.
1375 It expects the same syntax; the data must be on a single line, and the
1376 final `0' can be omitted.
1379 `trin' (translate input) is a new request which is similar to `tr' with
1380 the exception that the `asciify' request uses the character code (if
1381 any) before the character translation.
1400 The result is `x\~a'. Using `tr', the result would be `x\~x'.
1403 The request `pvs' isn't new, but hasn't been documented before.
1404 It adds vertical space after a line has been output.
1405 This makes it an alternative to the `ls' request to produce
1406 double-spaced documents.
1407 The read-only register `.pvs' holds the current amount of the
1408 post-vertical line space.
1411 For compatibility with plan 9's troff, multiple `pi' requests are
1423 is now equivalent to
1432 A new escape sequence `\eO' is available to disable and enable glyph
1434 Please see groff_diff.man and groff.texinfo for more details.
1437 The escapes `\e%', `\e&', `\e)', and `\e:' no longer cause an error in \eX;
1438 they are ignored now.
1439 Additionally `\e\ ' and `\e~' are converted to single space characters.
1442 The default tab distance in nroff mode is now 0.8i to be compatible
1446 Using the latin-1 input character 0xAD (soft hyphen) for the `shc'
1447 request was a bad idea.
1448 Instead, it is now translated to `\e%', and the default hyphenation
1449 character is again \e[hy].
1450 Note that the glyph \e[shc] is not useful for typographic purposes;
1451 it only exists to have glyph names for all latin-1 characters.
1459 .MTO df191@\:ncf.ca "Peter Schaffter"
1460 has contributed a new major macro package called `mom', mainly for
1461 non-scientific writers, which takes care of many typographic issues.
1462 It comes with a complete reference (in HTML format) and some examples.
1463 `mom' has been designed to format documents for PostScript output only.
1466 Two macros `AT' (AT&T) and `UC' (Univ. of California) have been added to
1467 the man macros for compatibility with older BSD releases.
1470 Both the man and mdoc macro packages now use the LL and LT registers for
1471 setting the line and title length, respectively (similar to those
1472 registers in the ms macro package).
1473 If not set on the command line or in a macro file loaded before the macro
1474 package itself, they default to 78n in nroff mode and 6.5i in troff mode.
1477 The `\-xwidth' specifier in the mdoc macro package has been removed.
1478 Its functionality is now integrated directly into `\-width'.
1479 Similarly, `\-column' has been extended to has this functionality also.
1482 A new macro `Ex' has been added to the mdoc macro package to document an
1486 `troff.man' has been split. Differences to UNIX troff are now documented
1487 in the new man page `groff_diff.man'.
1490 The PSPIC macro has been extended to work with DVI output (`pspic.tmac' is
1491 now automatically loaded for \-Tdvi), using a dvips special to load the EPS
1495 The trace.tmac package now traces calls to `am' also.
1496 Additionally, it works in compatibility mode.
1499 `troff.1' has been split.
1500 Differences to UNIX troff are now documented in the new man page
1504 `groff_mwww.7' has been renamed to `groff_www.7'.
1505 The file mwww.tmac has been removed.
1508 `groff_ms.7' has been completely rewritten.
1509 It now contains a complete reference to the ms macros.
1512 `groff_trace.7' documents the trace macro package.
1517 Note that HTML support is still in alpha change, so it is rather likely
1518 that both macro names and macro syntax will change.
1519 Some of the macros mentioned below aren't really new but haven't been
1520 documented properly before.
1524 The following macros have been renamed:
1535 For consistency, the macros `URL', `FTL', and `MTO' now all have the
1536 address as the first parameter followed by the description.
1539 By default, grohtml generates links to all section headings at the top
1541 Use the new `LK' macro to specify a different place.
1544 For specifying the background color and a background image, use the
1545 new macros `BCL' and `BGIMG', respectively.
1548 The macro `NHR' has been added; it suppresses the generation of top and
1549 bottom rules which grohtml emits by default.
1552 The new macro `HX' determines the cut-off point for automatic link
1553 generation to headings.
1556 The image position parameter names in `IMG' have been changed to `\-L',
1560 New macro `PIMG' for inclusion of a PNG image (it automatically
1561 converts it into an EPS file if not \-Thtml is used).
1564 New macro `MPIMG' for putting a PNG image into the left or right margin
1565 (it automatically converts it into an EPS file if not \-Thtml is used).
1568 New macros `HnS', `HnE' to start and end a header line block.
1571 New macro `DC' to produce dropcap characters.
1574 New macro `HTL' to generate an HTML title line only but no H1 heading.
1577 New macros `ULS' and `ULE' to start and end an unordered list.
1578 The new macro `LI' inserts a list item.
1588 The new command line `\-c' disables color output (which is always disabled
1589 in compatibility mode).
1598 Two new command line options `\-c' and `\-C'; the former passes `\-c' to
1599 grotty (switching to the old output scheme); the latter passes `\-C' to
1600 groff (enabling compatibility mode).
1609 New keywords `color' (or `colour', `colored', `coloured'), `outline' (or
1610 `outlined'), and `shaded' are available.
1611 `outline' sets the color of the outline, `shaded' the fill color, and
1617 circle shaded "green" outline "black" ;
1621 Filled arrows always use the outline color for filling.
1623 Color support for TeX output is not implemented yet.
1632 A new script contributed by
1633 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
1634 It converts a PIC diagram into a cropped image.
1635 Since it uses gs and the PNM library, virtually all graphics formats
1636 are available for output.
1645 A new script contributed by
1646 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
1647 It converts an EQN diagram into a cropped image.
1648 Since it uses gs and the PNM library, virtually all graphics formats
1649 are available for output.
1658 A new script contributed by
1659 .MTO bwarken@mayn.de "Bernd Warken" .
1660 It displays groff files and man pages on X and tty, taking care of most
1661 parameters automatically.
1670 Documents using the mom macro package are recognized.
1679 Color support has been added.
1682 A new option `\-p' is available to select the output paper size.
1683 It has the same syntax as the new `papersize' keyword in the DESC file.
1692 By default, font sizes are now available in the range 5\-10000pt, similar
1694 If you want the old behaviour (i.e., font sizes at discrete values only),
1695 insert the following at the start of your document:
1700 \&.if '\e*[.T]'dvi' \e
1701 \&. sizes 500 600 700 800 900 1000 1095 1200 1400 1440 1600 \e
1702 \& 1728 1800 2000 2074 2200 2400 2488 2800 3600
1708 A new font file HBI (using cmssbxo10; this is slanted sans serif bold
1709 extended) has been added.
1712 Two font families are now available: `T' and `H'.
1715 EC and TC fonts have been integrated.
1716 Use `\-mec' (calling the file ec.tmac) to switch to them.
1717 Those fonts give a much better coverage of the symbols defined by groff
1720 Note that ec.tmac must be called before any language-specific files; it
1721 doesn't take care of hcode values.
1724 Color support has been added.
1725 For drawing commands, colors are translated to gray values currently.
1735 Color support has been added, using the SGR (ISO\~6429, sometimes called
1736 ANSI color) escape sequences.
1739 SGR escape sequences are now used by default for underlining and bold
1740 printing also, no longer using the backspace character trick.
1741 To revert to the old behaviour, use the `\-c' switch.
1743 Note that you have to use the `\-R' option of `less' to make SGR escapes
1745 On the other hand, terminal programs and consoles like `xterm' which
1746 support SGR sequences natively can directly display the output of grotty.
1747 Consequently, the options `\-b', `\-B', `\-u', and `\-U' work only in
1748 combination with `\-c' and are ignored silently otherwise.
1750 For the `man' program, it may be necessary to add the `\-R' option of
1751 `less' to the $PAGER environment variable (or $MANPAGER, depending on the
1752 used version of `man'); alternatively, you can use `man's `\-P' option (or
1753 adapt its configuration file accordingly).
1754 See man(1) for more details.
1758 If the environment variable GROFF_NO_SGR is set, SGR output is disabled,
1759 reverting to the old behaviour.
1762 A new special \eX'tty:\~sgr\~n' has been added; if n is non-zero or missing,
1763 enable SGR output (the default).
1766 If the new option `\-i' is used (only in SGR mode), grotty sends escape
1767 sequences to set the italic font attribute instead of the underline
1768 attribute for italic fonts.
1769 Note that many terminals don't have support for this (including xterm).
1778 Color support for glyphs has been added.
1781 New option `\-h' to select the style of headings in HTML output.
1784 New option `\-b' to set the background colour to white.
1787 New options `\-a' and `\-g' to control the number of bits for anti-aliasing
1788 used for text and graphics, respectively.
1789 Default value is\~4; 0\~means no anti-aliasing.
1792 groff character/glyph entities now map onto HTML\~4 character entities.
1801 Valid paper sizes are now specified as with the new `papersize' keyword
1803 Specifically, the old custom paper type format `custAAAxBBB' is no longer
1813 A new manual page `ditroff.7' is available.
1816 The groff texinfo manual is now installed, together with a bunch
1820 A new keyword `papersize' has been added to the DESC file format.
1821 Its argument is either
1825 a predefined paper format (e.g. `A4' or `letter')
1828 a file name pointing to a file which must contain a paper size
1829 specification in its first line (e.g. `/etc/papersize')
1832 a custom paper size definition like `35c,4i'
1835 See groff_font(5) for more details.
1836 This keyword only affects the physical dimensions of the output medium;
1837 grops, grolj4, and grolbp use it currently.
1838 troff completely ignores it.