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
23 .defcolor mydarkred rgb 0.65f 0.1f 0.2f
24 .defcolor mydarkgreen rgb 0.1f 0.5f 0.2f
25 .defcolor mydarkblue rgb 0.1f 0.2f 0.6f
27 .ds GNU \m[mydarkred]G\m[]\m[mydarkgreen]N\m[]\m[mydarkblue]U\m[]
32 Home of Groff (GNU Troff).
35 .PSPIC -L gnu.eps 2i 2i
37 . nop \v'-0.66i'\h'2.0i'\s[100]\*[GNU] Troff\s0
39 . nop \v'-0.66i'\h'2.0i'\s[60]\*[GNU] Troff\s0
45 .URL http://\:groff.ffii.org/ (Groff)
47 .URL http://\:www.gnu.org/ GNU
50 .URL http://\:ffii.org/ FFII .
56 groff (GNU Troff) software
57 is a typesetting package which reads plain text mixed with
58 formatting commands and produces formatted output.
59 Groff now supports HTML.
65 .URL "ftp://\:groff.ffii.org/\:pub/\:groff/" Germany
67 .URL "ftp://\:ftp.gnu.org/\:gnu/\:groff/" USA
69 .URL http://\:www.gnu.org/\:copyleft/\:gpl.html License
71 .URL http://\:ffii.org/\:mailman/\:listinfo/\:groff/ "Mailing list"
73 .URL "http://\:gnuwin32.sf.net/\:packages/\:groffl.htm" "Groff for Windows"
76 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding"
78 Technical issues lead:
79 .MTO wl@\:gnu.org "Werner Lemberg"
85 This is the GNU groff document formatting system.
86 The version number is given in the file VERSION.
88 Included in this release are implementations of troff, pic, eqn, tbl, refer,
89 the \-man macros and the \-ms macros, and drivers for PostScript, TeX dvi
90 format, HP LaserJet 4 printers, HTML format (still alpha), and
91 typewriter-like devices.
92 Also included is a modified version of the Berkeley \-me macros, an enhanced
93 version of the X11 xditview previewer, and an implementation of the \-mm
95 .MTO jh@\:axis.se "J\[:o]rgen H\[:a]gg" .
97 See the file INSTALL for installation instructions.
98 You will require a C++ compiler.
100 The file NEWS describes recent user-visible changes to groff.
102 Groff is free software.
103 See the file COPYING for copying permission.
105 The file PROBLEMS describes various problems that have been encountered in
106 compiling, installing, and running groff.
108 For the moment, the documentation assumes that you are already familiar with
109 the Unix versions of troff, \-man, \-ms and the preprocessors.
111 The most recent released version of groff is always available by anonymous
112 ftp from ftp.gnu.org in the directory pub/\:gnu/\:groff.
114 A CVS repository is now available, containing the current development
116 You can access it with the commands
121 export CVSROOT=:pserver:anoncvs@anoncvs.ffii.org:/var/cvs
128 (if the prompt for the password appears, just press the enter key).
129 After a successful login you no longer need the first two commands; an
130 update of a checked out repository should be done with
138 Please read the info pages of cvs for further details.
140 Alternatively, you can download snapshots (which are updated twice a day)
142 .URL ftp://\:ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz here
143 or a diff file relative to the latest official groff release as:
147 ftp://ftp.ffii.org/pub/groff/devel/groff-\[la]version\[ra]-current.diff.gz
151 Assuming that groff-\[la]version\[ra].tar.gz and
152 groff-\[la]version\[ra]-current.diff.gz are in the same directory, do the
153 following to apply the diff file:
158 tar xzvf groff-\[la]version\[ra].tar.gz
159 cd groff-\[la]version\[ra]
160 gunzip -c ../groff-\[la]version\[ra]-current.diff.gz | patch -p1
165 Please report bugs using the form in the file BUG-REPORT; the idea of this
166 is to make sure that FSF has all the information it needs to fix the bug.
167 At the very least, read the BUG-REPORT form and make sure that you supply
168 all the information that it asks for.
169 Even if you are not sure that something is a bug, report it using
170 BUG-REPORT: this will enable us to determine whether it really is a bug or
173 Three mailing lists are available:
177 .MTO bug-groff@gnu.org bug-groff@gnu.org
181 .MTO groff@gnu.org groff@gnu.org
182 for general discussion of groff
185 .MTO groff-commit@ffii.org groff-commit@ffii.org
186 a read-only list showing logs of commitments to the CVS repository
189 Note that groff@gnu.org is an alias for
190 .MTO groff@\:ffii.org groff@\:ffii.org ;
191 you must be subscribed to the `groff' list to send mails.
193 To subscribe, send e-mail to \[la]list\[ra]-request@\[la]domain\[ra]
195 .MTO groff-request@\:ffii.org groff-request@\:ffii.org )
196 with the word `subscribe' in either the
197 subject or body of the e-mail (don't include the quotes).
199 GNU groff was written by
200 .MTO jjc@\:jclark.com "James Clark" .
201 It is now maintained by
202 .MTO Ted.Harding@\:nessie.mcc.ac.uk "Ted Harding"
204 .MTO wl@\:gnu.org "Werner Lemberg" .
215 The non-slanted PostScript font definition files have been regenerated to
216 include left and right italic correction values.
217 Applying those to a glyph (this is, prepending the glyph with `\e,' and
218 appending `\e/' to the glyph) sets the glyph width to the real value given
219 by the horizontal bounding box values.
220 Without those escapes, the advance width for the particular glyph is used
221 (which can differ considerably).
223 Most users will neither need this feature nor notice a difference in
224 existing documents (provided \e, and \e/ is used as advertised, namely for
225 italic fonts only); its main goal is to improve image generation with
228 This is an experimental change, and feedback is welcome.
236 Added global option `nospaces' to ignore leading and trailing spaces in data
245 The option \-w (\-\-linewidth) has been added (similar to other device
246 drivers) to set the default line width.
254 Support for b-spline and Bezier curves has been added.
262 New option \-\-shell to select the shell under wich groffer shall run.
270 The string `Am' (producing an ampersand) has been added to mdoc for
271 compatibility with NetBSD.
274 `.IX' is now deprecated for mom; you should use `.IQ' (Indent Quit)
278 In mom, new inlines `FWD', `BCK', `UP', and `DOWN' deal with horizontal
279 and vertical movements; please refer to contrib/mom/NEWS for more
283 New macro ENDNOTES_HDRFTR_CENTER for mom to better control headers.
291 The `papersize' keyword in the DESC file now accepts multiple arguments.
292 It is scanned from left to the right, and the first valid argument is used.
293 This makes it possible to provide a fallback paper size.
298 papersize /etc/papersize a4
303 A local font directory has been prepended to the default font path; it
304 defaults to /usr/local/share/groff/site-font. Similar to the normal
305 font searching process, files must be placed into a dev\fIXXX\fP
310 /usr/local/share/groff/site-font/devps/FOO
314 for a PostScript font definition file FOO.
321 This section describes recent user-visible changes in groff.
322 Bug fixes are not described.
323 There are more details in the man pages.
327 Please read the changes below regarding
329 . URL #grotty grotty ,
332 groff's tty frontend.\
342 Color support has been added to troff and pic (and to the device drivers
343 grops, grodvi, grotty, and grohtml -- other preprocessors and drivers will
345 A new function `defcolor' defines colors; the escape sequence `\em' sets the
346 drawing color, the escape sequence `\eM' specifies the background color for
347 closed objects created with \eD'.\|.\|.' commands.
348 `\em[]' and `\eM[]' switch back to the previous color.
349 `\em' and `\eM' correspond to the new troff output command sets starting
351 The device-specific default color is called `default' and can't be
354 Use the `color' request to toggle the usage of colors (default is on); the
355 read-only register `.color' is\~0 if colors are not active, and non-zero
358 The old `Df' output command is mapped onto `DFg'; all color output
359 commands don't change the current font position (consequently, `Df'
362 Outputting color can be disabled in troff and groff with the option\~\-c
363 (it is always disabled in compatibility mode).
364 See the section on grotty for the
366 . URL #GROFF_NO_SGR GROFF_NO_SGR
369 environment variable also.
371 For defining color components as fractions between 0 and\~1, a new scaling
372 indicator `f' has been defined: 1f\~=\~65536u.
373 For testing whether a color is defined (with .if and .ie), a new
374 conditional operator `m' is available.
376 More details can be found in the groff_diff.7 manual page and in
380 Similar to \em and \eM, \ef[] switches back to the previous font.
381 \efP (and \ef[P]) is still valid for backwards compatibility.
384 The new escape \eF is the same as `.fam'; \eF[] switches back to previous
385 family -- \eF[P] selects family `P'.
388 Two new glyph symbols are available: `eu' is the official Euro symbol;
389 `Eu' is a font-specific glyph variant.
392 The new glyph symbols `t+\-', `tdi', and `tmu' are textual variants of
393 `+\-', `di', and `mu', respectively.
396 Latin-1 character 181 (PS name `mu', Unicode name U+00B5 MICRO SIGN) has
397 got the troff glyph name `mc'.
400 \-Tutf8 is now available on EBCDIC hosts.
403 Strings can take arguments, using this syntax: \e*[foo\~arg1\~arg2\~.\|.\|.].
408 \&.ds xxx This is a \e\e$1 test.
415 It is now possible to have whitespace between the first and second dot (or
416 the name of the ending macro) to end a macro definition.
425 \&. nop Hello, I'm `foo'.
426 \&. nop I will now define `bar'.
428 \&. nop Hello, I'm `bar'.
436 `.fn' is a new string-valued register which returns the (internal) real
437 font name; styles and families are properly concatenated.
440 Three new read/write registers `seconds', `minutes', and `hours' contain
441 the current time, set at start-up of troff.
442 Use the `af' request to control their output format.
445 The new request `fchar' can be used to provide fallback characters.
446 It has the same syntax as the `char' request; the only difference is that
447 a character defined with `.char' hides the glyph with the same name in the
448 current font, whereas a character defined with `.fchar' is checked only if
449 the particular glyph isn't found in the current font.
450 This test happens before checking special fonts.
453 In analogy to the `tmc' request, `.writec' is the same as `.write' but
454 doesn't emit a final newline.
457 The new request `itc' is a variant of `.it' for which a line interrupted
458 with \ec counts as one input line.
461 Two new requests `ds1' and `as1' which are similar to `ds' and `as' but
462 with compatibility mode disabled during expansion of strings defined by
466 The syntax of the `substring' request has been changed:
467 The first character in a string now has index\~0, the last character
469 Note that this is an incompatible change.
472 To emit strings directly to the intermediate output, a new `output'
473 request has been added; it is similar to `\e!' used at the top level.
476 `.hpf' has been extended.
477 It can now handle most TeX hyphenation pattern files without
479 To do that, the commands \epatterns, \ehyphenation, and \eendinput are
481 Please refer to groff_diff.7 for more information.
484 `hpfcode' is a new request to provide an input encoding mapping for the
488 The new request `hpfa' appends hyphenation patterns (`hpf' replaces
489 already existing patterns).
492 A new request `ami' (append macro indirect) has been added.
493 The first and second parameter of `ami' are taken from string registers
494 rather than directly; this very special request is needed to make
495 `trace.tmac' independent from the escape character (which might even
499 The new request `sizes' is similar to the `sizes' command in DESC files.
500 It expects the same syntax; the data must be on a single line, and the
501 final `0' can be omitted.
504 `trin' (translate input) is a new request which is similar to `tr' with
505 the exception that the `asciify' request will use the character code (if
506 any) before the character translation.
524 The result is `x\~a'. Using `tr', the result would be `x\~x'.
527 The request `pvs' isn't new, but hasn't been documented before.
528 It adds vertical space after a line has been output.
529 This makes it an alternative to the `ls' request to produce
530 double-spaced documents.
531 The read-only register `.pvs' holds the current amount of the
532 post-vertical line space.
535 For compatibility with plan 9's troff, multiple `pi' requests are
555 A new escape sequence `\eO' is available to disable and enable glyph
557 Please see groff_diff.man and groff.texinfo for more details.
560 The escapes `\e%', `\e&', `\e)', and `\e:' no longer cause an error in \eX;
561 they are ignored now.
562 Additionally `\e\ ' and `\e~' are converted to single space characters.
565 The default tab distance in nroff mode is now 0.8i to be compatible
569 Using the latin-1 input character 0xAD (soft hyphen) for the `shc'
570 request was a bad idea.
571 Instead, it is now translated to `\e%', and the default hyphenation
572 character is again \e[hy].
573 Note that the glyph \e[shc] is not useful for typographic purposes;
574 it only exists to have glyph names for all latin-1 characters.
582 .MTO df191@\:ncf.ca "Peter Schaffter"
583 has contributed a new major macro package called `mom', mainly for
584 non-scientific writers, which takes care of many typographic issues.
585 It comes with a complete reference (in HTML format) and some examples.
586 `mom' has been designed to format documents for PostScript output only.
589 Two macros `AT' (AT&T) and `UC' (Univ. of California) have been added to
590 the man macros for compatibility with older BSD releases.
593 Both the man and mdoc macro packages now use the LL and LT registers for
594 setting the line and title length, respectively (similar to those
595 registers in the ms macro package).
596 If not set on the command line or in a macro file loaded before the macro
597 package itself, they default to 78n in nroff mode and 6.5i in troff mode.
600 The `\-xwidth' specifier in the mdoc macro package has been removed.
601 Its functionality is now integrated directly into `\-width'.
602 Similarly, `\-column' has been extended to has this functionality also.
605 A new macro `Ex' has been added to the mdoc macro package to document an
609 `troff.man' has been split. Differences to UNIX troff are now documented
610 in the new man page `groff_diff.man'.
613 The PSPIC macro has been extended to work with DVI output (`pspic.tmac' is
614 now automatically loaded for \-Tdvi), using a dvips special to load the EPS
618 The trace.tmac package now traces calls to `am' also.
619 Additionally, it works in compatibility mode.
622 `troff.1' has been split.
623 Differences to UNIX troff are now documented in the new man page
627 `groff_mwww.7' has been renamed to `groff_www.7'.
628 The file mwww.tmac has been removed.
631 `groff_ms.7' has been completely rewritten.
632 It now contains a complete reference to the ms macros.
635 `groff_trace.7' documents the trace macro package.
640 Note that HTML support is still in alpha change, so it is rather likely
641 that both macro names and macro syntax will change.
642 Some of the macros mentioned below aren't really new but haven't been
643 documented properly before.
647 The following macros have been renamed:
657 For consistency, the macros `URL', `FTL', and `MTO' now all have the
658 address as the first parameter followed by the description.
661 By default, grohtml generates links to all section headings at the top
663 Use the new `LK' macro to specify a different place.
666 For specifying the background color and a background image, use the
667 new macros `BCL' and `BGIMG', respectively.
670 The macro `NHR' has been added; it suppresses the generation of top and
671 bottom rules which grohtml emits by default.
674 The new macro `HX' determines the cut-off point for automatic link
675 generation to headings.
678 The image position parameter names in `IMG' have been changed to `\-L',
682 New macro `PIMG' for inclusion of a PNG image (it will automatically
683 convert it into an EPS file if not \-Thtml is used).
686 New macro `MPIMG' for putting a PNG image into the left or right margin
687 (it will automatically convert it into an EPS file if not \-Thtml is used).
690 New macros `HnS', `HnE' to start and end a header line block.
693 New macro `DC' to produce dropcap characters.
696 New macro `HTL' to generate an HTML title line only but no H1 heading.
699 New macros `ULS' and `ULE' to start and end an unordered list.
700 The new macro `LI' inserts a list item.
710 The new command line `\-c' disables color output (which is always disabled
711 in compatibility mode).
720 Two new command line options `\-c' and `\-C'; the former passes `\-c' to
721 grotty (switching to the old output scheme); the latter passes `\-C' to
722 groff (enabling compatibility mode).
731 New keywords `color' (or `colour', `colored', `coloured'), `outline' (or
732 `outlined'), and `shaded' are available.
733 `outline' sets the color of the outline, `shaded' the fill color, and
738 circle shaded "green" outline "black" ;
742 Filled arrows always use the outline color for filling.
744 Color support for TeX output is not implemented yet.
753 A new script contributed by
754 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
755 It converts a PIC diagram into a cropped image.
756 Since it uses gs and the PNM library, virtually all graphics formats
757 are available for output.
766 A new script contributed by
767 .MTO esr@\:thyrsus.com "Eric S.\~Raymond" .
768 It converts an EQN diagram into a cropped image.
769 Since it uses gs and the PNM library, virtually all graphics formats
770 are available for output.
779 A new script contributed by
780 .MTO bwarken@mayn.de "Bernd Warken" .
781 It displays groff files and man pages on X and tty, taking care of most
782 parameters automatically.
791 Documents using the mom macro package are recognized.
800 Color support has been added.
803 A new option `\-p' is available to select the output paper size.
804 It has the same syntax as the new `papersize' keyword in the DESC file.
813 By default, font sizes are now available in the range 5\-10000pt, similar
815 If you want the old behaviour (i.e., font sizes at discrete values only),
816 insert the following at the start of your document:
820 \&.if '\e*[.T]'dvi' \e
821 \&. sizes 500 600 700 800 900 1000 1095 1200 1400 1440 1600 \e
822 \& 1728 1800 2000 2074 2200 2400 2488 2800 3600
828 A new font file HBI (using cmssbxo10; this is slanted sans serif bold
829 extended) has been added.
832 Two font families are now available: `T' and `H'.
835 EC and TC fonts have been integrated.
836 Use `\-mec' (calling the file ec.tmac) to switch to them.
837 Those fonts give a much better coverage of the symbols defined by groff
840 Note that ec.tmac must be called before any language-specific files; it
841 doesn't take care of hcode values.
844 Color support has been added.
845 For drawing commands, colors are translated to gray values currently.
855 Color support has been added, using the SGR (ISO\~6429, sometimes called
856 ANSI color) escape sequences.
859 SGR escape sequences are now used by default for underlining and bold
860 printing also, no longer using the backspace character trick.
861 To revert to the old behaviour, use the `\-c' switch.
863 Note that you have to use the `\-R' option of `less' to make SGR escapes
865 On the other hand, terminal programs and consoles like `xterm' which
866 support SGR sequences natively can directly display the output of grotty.
867 Consequently, the options `\-b', `\-B', `\-u', and `\-U' work only in
868 combination with `\-c' and are ignored silently otherwise.
870 For the `man' program, it may be necessary to add the `\-R' option of
871 `less' to the $PAGER environment variable; alternatively, you can use
872 `man's `\-P' option (or adapt its configuration file accordingly).
873 See man(1) for more details.
877 If the environment variable GROFF_NO_SGR is set, SGR output is disabled,
878 reverting to the old behaviour.
881 A new special \eX'tty:\~sgr\~n' has been added; if n is non-zero or missing,
882 enable SGR output (the default).
885 If the new option `\-i' is used (only in SGR mode), grotty sends escape
886 sequences to set the italic font attribute instead of the underline
887 attribute for italic fonts.
888 Note that many terminals don't have support for this (including xterm).
897 Color support for glyphs has been added.
900 New option `\-h' to select the style of headings in HTML output.
903 New option `\-b' to set the background colour to white.
906 New options `\-a' and `\-g' to control the number of bits for anti-aliasing
907 used for text and graphics, respectively.
908 Default value is\~4; 0\~means no anti-aliasing.
911 groff character/glyph entities now map onto HTML\~4 character entities.
920 Valid paper sizes are now specified as with the new `papersize' keyword
922 Specifically, the old custom paper type format `custAAAxBBB' is no longer
932 A new manual page `ditroff.7' is available.
935 The groff texinfo manual will now be installed, together with a bunch
939 A new keyword `papersize' has been added to the DESC file format.
940 Its argument is either
944 a predefined paper format (e.g. `A4' or `letter')
947 a file name pointing to a file which must contain a paper size
948 specification in its first line (e.g. `/etc/papersize')
951 a custom paper size definition like `35c,4i'
954 See groff_font(5) for more details.
955 This keyword only affects the physical dimensions of the output medium;
956 grops, grolj4, and grolbp use it currently.
957 troff completely ignores it.
962 \s-2\fIThis document was produced using
963 .URL http://groff.ffii.org/ groff-\n[.x].\n[.y].\n[.Y] .
965 The image at the top has been contributed by Imogen Mulley (born 1991),
966 based on a similar picture found on the
967 .URL http://www.gnu.org "GNU server" .
nant's projects / dragonfly.git / blob