1.ig 2groff.man 3 4Last update: 01 Jul 2005 5 6Copyright (C) 1989, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. 7Rewritten in 2002 by Bernd Warken <bwarken@mayn.de> 8 9Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.1 or 11any later version published by the Free Software Foundation; with the 12Invariant Sections being this .ig-section and AUTHOR, with no 13Front-Cover Texts, and with no Back-Cover Texts. 14 15A copy of the Free Documentation License is included as a file called 16FDL in the main directory of the groff source package. 17 18$FreeBSD: releng/11.0/contrib/groff/src/roff/groff/groff.man 151503 2005-10-20 10:53:15Z ru $ 19 20.. 21. 22.\" -------------------------------------------------------------------- 23.\" Setup 24.\" -------------------------------------------------------------------- 25. 26.do nr groff_C \n[.C] 27.cp 0 28. 29.mso www.tmac 30. 31.\" set adjust to both 32.ad b 33. 34.\" fonts of fixed length 35. 36.if n \{\ 37. mso tty-char.tmac 38. ftr CR R 39. ftr CI I 40. ftr CB B 41.\} 42. 43.if '\*[.T]'dvi' \ 44. ftr CB CW 45. 46.\" -------------------------------------------------------------------- 47.\" String definitions 48. 49.ds @- "\-\" 50.ds @-- "\-\^\-\" 51. 52.ds Ellipsis .\|.\|.\" 53. 54. 55.\" -------------------------------------------------------------------- 56.\" Begin of macro definitions 57.de c 58.\" this is like a comment request when escape mechanism is off 59.. 60.eo 61. 62.c -------------------------------------------------------------------- 63.de TP+ 64.br 65.ns 66.TP \$1 67.. 68.c -------------------------------------------------------------------- 69.c Like TP, but if specified indent is more than half 70.c the current line-length - indent, use the default indent. 71.de Tp 72. ie \n[.$]=0:((0\$1)*2u>(\n.lu-\n(.iu)) .TP 73. el .TP "\$1" 74.. 75.c -------------------------------------------------------------------- 76.de Text 77. nop \)\$* 78.. 79.c -------------------------------------------------------------------- 80.de Synopsis 81. ds @arg1 \$1\" 82. nr @old_indent \n[.i] 83. ad l 84. in +\w'\f[B]\*[@arg1]\0'u 85. ti \n[@old_indent]u 86. B \*[@arg1]\0\c 87. rr @old_indent 88. rm @arg1 89.. 90.c -------------------------------------------------------------------- 91.de EndSynopsis 92. ad 93. in 94.. 95.c -------------------------------------------------------------------- 96.c ShortOpt[] (name [arg]) 97.c 98.c short option in synopsis 99.c 100.de ShortOpt[] 101. if \n[.$]=0 \ 102. return 103. ds @opt \$1\" 104. shift 105. ie \n[.$]=0 \ 106. Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[] 107. el \ 108. Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[] 109. rm @opt 110.. 111.c -------------------------------------------------------------------- 112.c Option in synopsis (short option) 113.de SynOpt 114. if \n[.$]=0 \ 115. return 116. ds @opt \$1\" 117. shift 118. ie \n[.$]=0 \ 119. Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[] 120. el \ 121. Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[] 122. rm @opt 123.. 124.c -------------------------------------------------------------------- 125.c ShortOpt ([char [punct]]) 126.c 127.c `-c' somewhere in the text 128.c second arg is punctuation 129.c 130.de ShortOpt 131. ds @opt \$1\" 132. shift 133. Text \f[CB]\*[@-]\*[@opt]\f[]\/\$* 134. rm @opt 135.. 136.c -------------------------------------------------------------------- 137.c LongOpt ([name [punct]]) 138.c 139.c `--name' somewhere in the text 140.c second arg is punctuation 141.c 142.de LongOpt 143. ds @opt \$1\" 144. shift 145. Text \f[CB]\*[@--]\f[]\f[B]\*[@opt]\f[]\/\$* 146. rm @opt 147.. 148.c -------------------------------------------------------------------- 149.c OptDef (shortopt [longopt [argument]]) 150.c 151.c option documentation 152.c args : `shortopt', `longopt' can be "" 153.c 154.de OptDef 155. ds @short 156. ds @long 157. ds @arg 158. if \n[.$]>=1 \{\ 159. ds @arg1 "\$1\" 160. if !'\*[@arg1]'' \ 161. ds @short "\f[CB]\*[@-]\*[@arg1]\f[]\" 162. if \n[.$]>=2 \{\ 163. if !'\*[@short]'' \ 164. as @short \f[CW]\0\f[] 165. ds @arg2 "\$2\" 166. if !'\*[@arg2]'' \ 167. ds @long "\f[CB]\*[@--]\f[]\f[B]\*[@arg2]\f[]\" 168. if \n[.$]>=3 \{\ 169. if !'\*[@long]'' \ 170. as @long \|=\|\" 171. shift 2 172. ds @arg \f[I]\$*\" 173. \} 174. \} 175. \} 176. IP "\f[R]\*[@short]\*[@long]\*[@arg]\f[]" 177. rm @arg 178. rm @arg1 179. rm @arg2 180. rm @short 181. rm @long 182.. 183.c -------------------------------------------------------------------- 184.c Continuation of an OptDef header. 185.de OptDef+ 186. br 187. ns 188. OptDef \$@ 189.. 190.c -------------------------------------------------------------------- 191.c Environment variable 192.de EnvVar 193. SM 194. BR \%\$1 \$2 195.. 196.c -------------------------------------------------------------------- 197.c a shell command line 198.de ShellCommand 199. nr @font \n[.f] 200. c replace argument separator by unbreakable space 201. ds @args \$1\"" 202. shift 203. while (\n[.$]>0) \{\ 204. ds @args \*[@args]\~\$1 205. shift 206. \} 207. br 208. ad l 209. nh 210. Text \f[I]sh#\h'1m'\f[P]\f[CR]\*[@args]\f[P]\&\" 211. ft R 212. ft P 213. hy 214. ad 215. ft \n[@font] 216. br 217. rr @font 218. rm @args 219.. 220.c -------------------------------------------------------------------- 221.c `char or string' 222.de Quoted 223. ft CR 224. Text \[oq]\$*\[cq] 225. ft 226.. 227.c -------------------------------------------------------------------- 228.c End of macro definitions 229.ec 230. 231. 232.\" -------------------------------------------------------------------- 233.\" Title 234.\" -------------------------------------------------------------------- 235. 236.TH GROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 237.SH NAME 238groff \- front-end for the groff document formatting system 239. 240. 241.\" -------------------------------------------------------------------- 242.SH SYNOPSIS 243.\" -------------------------------------------------------------------- 244. 245.ad l 246.Synopsis groff 247.ShortOpt[] abcegilpstzCEGNRSUVXZ 248.ShortOpt[] d cs 249.ShortOpt[] f fam 250.ShortOpt[] F dir 251.ShortOpt[] I dir 252.ShortOpt[] L arg 253.ShortOpt[] m name 254.ShortOpt[] M dir 255.ShortOpt[] n num 256.ShortOpt[] o list 257.ShortOpt[] P arg 258.ShortOpt[] r cn 259.ShortOpt[] T dev 260.ShortOpt[] w name 261.ShortOpt[] W name 262.RI [ file 263.Text \*[Ellipsis]] 264.EndSynopsis 265. 266.Synopsis groff 267.ShortOpt h 268| 269.LongOpt help 270.EndSynopsis 271. 272.Synopsis groff 273.ShortOpt v 274| 275.LongOpt version 276.RI [ option 277.Text \*[Ellipsis]] 278.EndSynopsis 279. 280.P 281The command line is parsed according to the usual GNU convention. 282. 283The whitespace between a command line option and its argument is 284optional. 285. 286Options can be grouped behind a single 287.ShortOpt 288(minus character). 289. 290A filename of 291.ShortOpt 292(minus character) denotes the standard input. 293. 294. 295.\" -------------------------------------------------------------------- 296.SH DESCRIPTION 297.\" -------------------------------------------------------------------- 298. 299This document describes the 300.B groff 301program, the main front-end for the 302.I groff 303document formatting system. 304. 305The 306.I groff 307program and macro suite is the implementation of a 308.BR roff (@MAN7EXT@) 309system within the free software collection 310.URL http://\:www.gnu.org "GNU" . 311. 312The 313.I groff 314system has all features of the classical 315.IR roff , 316but adds many extensions. 317. 318.P 319The 320.B groff 321program allows to control the whole 322.I groff 323system by command line options. 324. 325This is a great simplification in comparison to the classical case (which 326uses pipes only). 327. 328. 329.\" -------------------------------------------------------------------- 330.SH OPTIONS 331.\" -------------------------------------------------------------------- 332. 333As 334.B groff 335is a wrapper program for 336.B @g@troff 337both programs share a set of options. 338. 339But the 340.B groff 341program has some additional, native options and gives a new meaning to 342some 343.B @g@troff 344options. 345. 346On the other hand, not all 347.B @g@troff 348options can be fed into 349.BR groff . 350. 351. 352.\" -------------------------------------------------------------------- 353.SS Native groff Options 354.\" -------------------------------------------------------------------- 355. 356The following options either do not exist for 357.B @g@troff 358or are differently interpreted by 359.BR groff . 360. 361. 362.OptDef e 363Preprocess with 364.BR @g@eqn . 365. 366. 367.OptDef g 368Preprocess with 369.BR @g@grn . 370. 371. 372.OptDef G 373Preprocess with 374.BR grap . 375. 376. 377.OptDef h help 378Print a help message. 379. 380. 381.OptDef I "" dir 382This option may be used to specify a directory to search for 383files (both those on the command line and those named in 384.B \&.psbb 385and 386.B \&.so 387requests, and 388.B \eX'ps: import' 389and 390.B \eX'ps: file' 391escapes). 392The current directory is always searched first. 393This option may be specified more than once; 394the directories will be searched in the order specified. 395No directory search is performed for files specified using an absolute path. 396This option implies the 397.ShortOpt s 398option. 399. 400. 401.OptDef l 402Send the output to a spooler program for printing. 403. 404The command that should be used for this is specified by the 405.B print 406command in the device description file, see 407.BR \%groff_font (@MAN5EXT@). 408If this command is not present, the output is piped into the 409.BR lpr (1) 410program by default. 411. 412See options 413.ShortOpt L 414and 415.ShortOpt X . 416. 417. 418.OptDef L "" arg 419Pass 420.I arg 421to the spooler program. 422Several arguments should be passed with a separate 423.ShortOpt L 424option each. 425. 426Note that 427.B groff 428does not prepend 429.ShortOpt\" just a minus sign 430(a minus sign) to 431.I arg 432before passing it to the spooler program. 433. 434. 435.OptDef N 436Don't allow newlines within 437.I eqn 438delimiters. 439. 440This is the same as the 441.ShortOpt N 442option in 443.BR @g@eqn . 444. 445. 446.OptDef p 447Preprocess with 448.BR @g@pic . 449. 450. 451.OptDef P "" "\*[@-]option" 452.OptDef+ P "" "\*[@-]option \f[CB]\*[@-]P\f[] arg" 453Pass 454.I \*[@-]option 455or 456.I \*[@-]option arg 457to the postprocessor. 458. 459The option must be specified with the necessary preceding minus 460sign(s) 461.Quoted \*[@-] 462or 463.Quoted \*[@--] 464because groff does not prepend any dashes before passing it to the 465postprocessor. 466. 467For example, to pass a title to the \%gxditview postprocessor, the shell 468command 469.IP 470.ShellCommand groff \*[@-]X \*[@-]P \*[@-]title \*[@-]P 'groff it' \f[I]foo\f[] 471.IP 472is equivalent to 473.IP 474.ShellCommand groff \*[@-]X \*[@-]Z \f[I]foo\f[] | \ 475gxditview \*[@-]title 'groff it' \*[@-] 476. 477. 478.OptDef R 479Preprocess with 480.BR @g@refer . 481. 482No mechanism is provided for passing arguments to 483.B @g@refer 484because most 485.B @g@refer 486options have equivalent language elements that can be specified within 487the document. 488. 489See 490.BR \%@g@refer (@MAN1EXT@) 491for more details. 492. 493. 494.OptDef s 495Preprocess with 496.BR @g@soelim . 497. 498. 499.OptDef S 500Safer mode. 501. 502Pass the 503.ShortOpt S 504option to 505.B @g@pic 506and disable the following 507.B @g@troff 508requests: 509.BR .open , 510.BR .opena , 511.BR .pso , 512.BR .sy , 513and 514.BR .pi . 515For security reasons, safer mode is enabled by default. 516. 517. 518.OptDef t 519Preprocess with 520.BR @g@tbl . 521. 522. 523.OptDef T "" dev 524Set output device to 525.IR dev . 526For this device, 527.B @g@troff 528generates the 529.I intermediate 530.IR output ; 531see 532.BR \%groff_out (@MAN5EXT@). 533. 534Then 535.B groff 536calls a postprocessor to convert 537.BR @g@troff 's 538.I intermediate output 539to its final format. 540. 541Real devices in 542.B groff 543are 544. 545.RS 546.RS 547.IP dvi 548TeX DVI format (postprocessor is 549.BR grodvi ). 550.IP html 551HTML output (preprocessors are 552.B @g@soelim 553and 554.BR \%pre-grohtml , 555postprocessor is 556.BR \%post-grohtml ). 557.IP lbp 558Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers; 559postprocessor is 560.BR grolbp ). 561.IP lj4 562HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor 563is 564.BR grolj4 ). 565.IP ps 566PostScript output (postprocessor is 567.BR grops ). 568.RE 569.RE 570. 571.IP 572For the following TTY output devices (postprocessor is always 573.BR grotty ), 574.ShortOpt T 575selects the output encoding: 576.RS 577.RS 578.IP ascii 5797bit ASCII. 580.IP cp1047 581\%Latin-1 character set for EBCDIC hosts. 582.IP latin1 583ISO \%8859-1. 584.IP utf8 585Unicode character set in \%UTF-8 encoding. 586.RE 587.RE 588. 589.IP 590The following arguments select 591.B \%gxditview 592as the `postprocessor' (it is rather a viewing program): 593. 594.RS 595.RS 596.IP X75 59775dpi resolution, 10pt document base font. 598.IP X75-12 59975dpi resolution, 12pt document base font. 600.IP X100 601100dpi resolution, 10pt document base font. 602.IP X100-12 603100dpi resolution, 12pt document base font. 604.RE 605.RE 606. 607.IP 608The default device is 609.BR @DEVICE@ . 610. 611. 612.OptDef U 613Unsafe mode. 614. 615Reverts to the (old) unsafe behaviour; see option 616.ShortOpt S . 617. 618. 619.OptDef v version 620Output version information of 621.B groff 622and of all programs that are run by it; that is, the given command line 623is parsed in the usual way, passing 624.ShortOpt v 625to all subprograms. 626. 627. 628.OptDef V 629Output the pipeline that would be run by 630.BR groff 631(as a wrapper program) on the standard output, but do not execute it. 632If given more than once, 633the commands will be both printed on the standard error and run. 634. 635. 636.OptDef X 637Use 638.B \%gxditview 639instead of using the usual postprocessor to (pre)view a document. 640. 641The printing spooler behavior as outlined with options 642.ShortOpt l 643and 644.ShortOpt L 645is carried over to 646.BR \%gxditview (@MAN1EXT@) 647by determining an argument for the 648.B \*[@-]printCommand 649option of 650.BR \%gxditview (@MAN1EXT@). 651. 652This sets the default 653.B Print 654action and the corresponding menu entry to that value. 655. 656.ShortOpt X 657only produces good results with 658.ShortOpt Tps , 659.ShortOpt TX75 , 660.ShortOpt TX75-12 , 661.ShortOpt TX100 , 662and 663.ShortOpt TX100-12 . 664. 665The default resolution for previewing 666.ShortOpt Tps 667output is 75\|dpi; this can be changed by passing the 668.ShortOpt resolution 669option to 670.BR \%gxditview , 671for example 672. 673.IP 674.ShellCommand groff \*[@-]X \*[@-]P\*[@-]resolution \*[@-]P100 \*[@-]man foo.1 675. 676. 677.OptDef z 678Suppress output generated by 679.BR @g@troff . 680Only error messages will be printed. 681. 682. 683.OptDef Z 684Print the 685.I groff intermediate output 686to standard output; see 687.BR \%groff_out (@MAN5EXT@). 688Normally 689.BR groff 690calls automatically a postprocessor. 691. 692With this option, the output of 693.B @g@troff 694for the device, the so-called 695.I intermediate output 696is issued without postprocessing. 697. 698. 699.\" -------------------------------------------------------------------- 700.SS Transparent Options 701.\" -------------------------------------------------------------------- 702. 703The following options are transparently handed over to the formatter 704program 705.B @g@troff 706that is called by groff subsequently. 707. 708These options are described in more detail in 709.BR @g@troff (@MAN1EXT@). 710. 711.OptDef a 712ascii approximation of output. 713. 714.OptDef b 715backtrace on error or warning. 716. 717.OptDef c 718disable color output. 719. 720Please consult the 721.BR \%grotty (@MAN1EXT@) 722man page for more details. 723. 724.OptDef C 725enable compatibility mode. 726. 727.OptDef d "" cs 728.OptDef+ d "" name=s 729define string. 730. 731.OptDef E 732disable 733.B @g@troff 734error messages. 735. 736.OptDef f "" fam 737set default font family. 738. 739.OptDef F "" dir 740set path for font DESC files. 741. 742.OptDef i 743process standard input after the specified input files. 744. 745.OptDef m "" name 746include macro file \f[I]name\f[]\f[B].tmac\f[] (or 747\f[B]tmac.\f[]\f[I]name\f[]); see also 748.BR \%groff_tmac (@MAN5EXT@). 749. 750.OptDef M "" dir 751path for macro files. 752. 753.OptDef n "" num 754number the first page 755.IR num . 756. 757.OptDef o "" list 758output only pages in 759.IR list . 760. 761.OptDef r "" cn 762.OptDef+ r "" name=n 763set number register. 764. 765.OptDef w "" name 766enable warning 767.IR name . 768. 769.OptDef W "" name 770disable warning 771.IR name . 772. 773. 774.\" -------------------------------------------------------------------- 775.SH "USING GROFF" 776.\" -------------------------------------------------------------------- 777. 778The 779.I groff system 780implements the infrastructure of classical roff; see 781.BR roff (@MAN7EXT@) 782for a survey on how a roff system works in general. 783. 784Due to the front-end programs available within the groff system, using 785.I groff 786is much easier than 787.IR "classical roff" . 788. 789This section gives an overview of the parts that constitute the groff 790system. 791. 792It complements 793.BR roff (@MAN7EXT@) 794with groff-specific features. 795. 796This section can be regarded as a guide to the documentation around 797the groff system. 798. 799. 800.\" -------------------------------------------------------------------- 801.SS Paper Size 802.\" -------------------------------------------------------------------- 803. 804The 805.I virtual 806paper size used by 807.B troff 808to format the input is controlled globally with the requests 809.BR .po , 810.BR .pl , 811and 812.BR .ll . 813See 814.BR groff_tmac (@MAN5EXT@) 815for the `papersize' macro package which provides a convenient interface. 816. 817.P 818The 819.I physical 820paper size, giving the actual dimensions of the paper sheets, is 821controlled by output devices like 822.BR grops 823with the command line options 824.B \-p 825and 826.BR \-l . 827See 828.BR groff_font (@MAN5EXT@) 829and the man pages of the output devices for more details. 830.B groff 831uses the command line option 832.B \-P 833to pass options to output devices; for example, the following selects 834A4 paper in landscape orientation for the PS device: 835. 836.RS 837.P 838groff -Tps -P-pa4 -P-l .\|.\|. 839.RE 840. 841. 842.\" -------------------------------------------------------------------- 843.SS Front-ends 844.\" -------------------------------------------------------------------- 845. 846The 847.B groff 848program is a wrapper around the 849.BR @g@troff (@MAN1EXT@) 850program. 851. 852It allows to specify the preprocessors by command line options and 853automatically runs the postprocessor that is appropriate for the 854selected device. 855. 856Doing so, the sometimes tedious piping mechanism of classical 857.BR roff (@MAN7EXT@) 858can be avoided. 859. 860.P 861The 862.BR grog (@MAN1EXT@) 863program can be used for guessing the correct groff command line to 864format a file. 865. 866.P 867The 868.BR \%groffer (@MAN1EXT@) 869program is an allround-viewer for groff files and man pages. 870. 871. 872.\" -------------------------------------------------------------------- 873.SS Preprocessors 874.\" -------------------------------------------------------------------- 875. 876The groff preprocessors are reimplementations of the classical 877preprocessors with moderate extensions. 878. 879The preprocessors distributed with the 880.I groff 881package are 882. 883.TP 884.BR @g@eqn (@MAN1EXT@) 885for mathematical formul\(ae, 886.TP 887.BR @g@grn (@MAN1EXT@) 888for including 889.BR gremlin (1) 890pictures, 891.TP 892.BR @g@pic (@MAN1EXT@) 893for drawing diagrams, 894.TP 895.BR \%@g@refer (@MAN1EXT@) 896for bibliographic references, 897.TP 898.BR \%@g@soelim (@MAN1EXT@) 899for including macro files from standard locations, 900. 901.P 902and 903.TP 904.BR @g@tbl (@MAN1EXT@) 905for tables. 906. 907.P 908Besides these, there are some internal preprocessors that are 909automatically run with some devices. 910. 911These aren't visible to the user. 912. 913. 914.\" -------------------------------------------------------------------- 915.SS "Macro Packages" 916.\" -------------------------------------------------------------------- 917. 918Macro packages can be included by option 919.ShortOpt m . 920. 921The groff system implements and extends all classical macro packages 922in a compatible way and adds some packages of its own. 923. 924Actually, the following macro packages come with 925.IR groff : 926. 927.TP 928.B man 929The traditional man page format; see 930.BR \%groff_man (@MAN7EXT@). 931It can be specified on the command line as 932.ShortOpt man 933or 934.ShortOpt m 935.BR man . 936. 937.TP 938.B mandoc 939The general package for man pages; it automatically recognizes 940whether the documents uses the 941.I man 942or the 943.I mdoc 944format and branches to the corresponding macro package. 945. 946It can be specified on the command line as 947.ShortOpt mandoc 948or 949.ShortOpt m 950.BR mandoc . 951. 952.TP 953.B mdoc 954The BSD-style man page format; see 955.BR \%groff_mdoc (@MAN7EXT@). 956It can be specified on the command line as 957.ShortOpt mdoc 958or 959.ShortOpt m 960.BR mdoc . 961. 962.TP 963.B me 964The classical 965.I me 966document format; see 967.BR \%groff_me (@MAN7EXT@). 968It can be specified on the command line as 969.ShortOpt me 970or 971.ShortOpt m 972.BR me . 973. 974.TP 975.B mm 976The classical 977.I mm 978document format; see 979.BR \%groff_mm (@MAN7EXT@). 980It can be specified on the command line as 981.ShortOpt mm 982or 983.ShortOpt m 984.BR mm . 985. 986.TP 987.B ms 988The classical 989.I ms 990document format; see 991.BR \%groff_ms (@MAN7EXT@). 992It can be specified on the command line as 993.ShortOpt ms 994or 995.ShortOpt m 996.BR ms . 997. 998.TP 999.B www 1000HTML-like macros for inclusion in arbitrary groff documents; see 1001.BR \%groff_www (@MAN7EXT@). 1002. 1003.P 1004Details on the naming of macro files and their placement can be found 1005in 1006.BR \%groff_tmac (@MAN5EXT@); 1007this man page also documents some other, minor auxiliary macro packages 1008not mentioned here. 1009. 1010. 1011.\" -------------------------------------------------------------------- 1012.SS "Programming Language" 1013.\" -------------------------------------------------------------------- 1014. 1015General concepts common to all roff programming languages are 1016described in 1017.BR roff (@MAN7EXT@). 1018. 1019.P 1020The groff extensions to the classical troff language are documented in 1021.BR \%groff_diff (@MAN7EXT@). 1022. 1023.P 1024The groff language as a whole is described in the (still incomplete) 1025.IR "groff info file" ; 1026a short (but complete) reference can be found in 1027.BR groff (@MAN7EXT@). 1028. 1029. 1030.\" -------------------------------------------------------------------- 1031.SS Formatters 1032.\" -------------------------------------------------------------------- 1033. 1034The central roff formatter within the groff system is 1035.BR @g@troff (@MAN1EXT@). 1036It provides the features of both the classical troff and nroff, as 1037well as the groff extensions. 1038. 1039The command line option 1040.ShortOpt C 1041switches 1042.B @g@troff 1043into 1044.I "compatibility mode" 1045which tries to emulate classical roff as much as possible. 1046. 1047.P 1048There is a shell script 1049.BR @g@nroff (@MAN1EXT@) 1050that emulates the behavior of classical nroff. 1051. 1052It tries to automatically select the proper output encoding, according to 1053the current locale. 1054. 1055.P 1056The formatter program generates 1057.IR "intermediate output" ; 1058see 1059.BR \%groff_out (@MAN7EXT@). 1060. 1061. 1062.\" -------------------------------------------------------------------- 1063.SS Devices 1064.\" -------------------------------------------------------------------- 1065. 1066In roff, the output targets are called 1067.IR devices . 1068A device can be a piece of hardware, e.g. a printer, or a software 1069file format. 1070. 1071A device is specified by the option 1072.ShortOpt T . 1073The groff devices are as follows. 1074. 1075.TP 1076.B ascii 1077Text output using the 1078.BR ascii (7) 1079character set. 1080. 1081.TP 1082.B cp1047 1083Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix). 1084. 1085.TP 1086.B dvi 1087TeX DVI format. 1088. 1089.TP 1090.B html 1091HTML output. 1092. 1093.TP 1094.B latin1 1095Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see 1096.BR \%iso_8859_1 (7). 1097. 1098.TP 1099.B koi8-r 1100Text output using the Russian KOI8-R character set. 1101. 1102.TP 1103.B lbp 1104Output for Canon CAPSL printers (\%LBP-4 and \%LBP-8 series laser printers). 1105. 1106.TP 1107.B lj4 1108HP LaserJet4-compatible (or other PCL5-compatible) printers. 1109. 1110.TP 1111.B ps 1112PostScript output; suitable for printers and previewers like 1113.BR gv (1). 1114. 1115.TP 1116.B utf8 1117Text output using the Unicode (ISO 10646) character set with \%UTF-8 1118encoding; see 1119.BR unicode (7). 1120. 1121.TP 1122.B X75 112375dpi X Window System output suitable for the previewers 1124.BR \%xditview (1x) 1125and 1126.BR \%gxditview (@MAN1EXT@). 1127A variant for a 12\|pt document base font is 1128.BR \%X75-12 . 1129. 1130.TP 1131.B X100 1132100dpi X Window System output suitable for the previewers 1133.BR \%xditview (1x) 1134and 1135.BR \%gxditview (@MAN1EXT@). 1136A variant for a 12\|pt document base font is 1137.BR \%X100-12 . 1138. 1139.P 1140The postprocessor to be used for a device is specified by the 1141.B postpro 1142command in the device description file; see 1143.BR \%groff_font (@MAN5EXT@). 1144. 1145This can be overridden with the 1146.B \*[@-]X 1147option. 1148. 1149.P 1150The default device is 1151.BR @DEVICE@ . 1152. 1153. 1154.\" -------------------------------------------------------------------- 1155.SS Postprocessors 1156.\" -------------------------------------------------------------------- 1157. 1158groff provides 3\~hardware postprocessors: 1159. 1160.TP 1161.BR \%grolbp (@MAN1EXT@) 1162for some Canon printers, 1163.TP 1164.BR \%grolj4 (@MAN1EXT@) 1165for printers compatible to the HP LaserJet\~4 and PCL5, 1166.TP 1167.BR \%grotty (@MAN1EXT@) 1168for text output using various encodings, e.g. on text-oriented 1169terminals or line-printers. 1170. 1171.P 1172Today, most printing or drawing hardware is handled by the operating 1173system, by device drivers, or by software interfaces, usually accepting 1174PostScript. 1175. 1176Consequently, there isn't an urgent need for more hardware device 1177postprocessors. 1178. 1179.P 1180The groff software devices for conversion into other document file 1181formats are 1182. 1183.TP 1184.BR \%grodvi (@MAN1EXT@) 1185for the DVI format, 1186.TP 1187.BR \%grohtml (@MAN1EXT@) 1188for HTML format, 1189.TP 1190.BR grops (@MAN1EXT@) 1191for PostScript. 1192. 1193.P 1194Combined with the many existing free conversion tools this should 1195be sufficient to convert a troff document into virtually any existing 1196data format. 1197. 1198. 1199.\" -------------------------------------------------------------------- 1200.SS Utilities 1201.\" -------------------------------------------------------------------- 1202. 1203The following utility programs around groff are available. 1204. 1205.TP 1206.BR \%addftinfo (@MAN1EXT@) 1207Add information to troff font description files for use with groff. 1208. 1209.TP 1210.BR \%afmtodit (@MAN1EXT@) 1211Create font description files for PostScript device. 1212. 1213.TP 1214.BR \%groffer (@MAN1EXT@) 1215General viewer program for groff files and man pages. 1216. 1217.TP 1218.BR \%gxditview (@MAN1EXT@) 1219The groff X viewer, the GNU version of xditview. 1220. 1221.TP 1222.BR \%hpftodit (@MAN1EXT@) 1223Create font description files for lj4 device. 1224. 1225.TP 1226.BR \%indxbib (@MAN1EXT@) 1227Make inverted index for bibliographic databases. 1228. 1229.TP 1230.BR lkbib (@MAN1EXT@) 1231Search bibliographic databases. 1232. 1233.TP 1234.BR \%lookbib (@MAN1EXT@) 1235Interactively search bibliographic databases. 1236. 1237.TP 1238.BR \%pfbtops (@MAN1EXT@) 1239Translate a PostScript font in .pfb format to ASCII. 1240. 1241.TP 1242.BR \%tfmtodit (@MAN1EXT@) 1243Create font description files for TeX DVI device. 1244. 1245.TP 1246.BR \%xditview (1x) 1247roff viewer distributed with X window. 1248. 1249. 1250.\" -------------------------------------------------------------------- 1251.SH ENVIRONMENT 1252.\" -------------------------------------------------------------------- 1253. 1254Normally, the path separator in the following environment variables is the 1255colon; this may vary depending on the operating system. 1256. 1257For example, DOS and Windows use a semicolon instead. 1258. 1259.TP 1260.EnvVar GROFF_BIN_PATH 1261This search path, followed by 1262.EnvVar $PATH , 1263will be used for commands that are executed by 1264.BR groff . 1265. 1266If it is not set then the directory where the groff binaries were 1267installed is prepended to 1268.EnvVar PATH . 1269. 1270.TP 1271.EnvVar GROFF_COMMAND_PREFIX 1272When there is a need to run different roff implementations at the same 1273time 1274.I groff 1275provides the facility to prepend a prefix to most of its programs that 1276could provoke name clashings at run time (default is to have none). 1277. 1278Historically, this prefix was the character 1279.BR g , 1280but it can be anything. 1281. 1282For example, 1283.BR gtroff 1284stood for 1285.IR groff 's 1286.BR troff , 1287.BR gtbl 1288for the 1289.I groff 1290version of 1291.BR tbl . 1292. 1293By setting 1294.EnvVar GROFF_COMMAND_PREFIX 1295to different values, the different roff installations can be 1296addressed. 1297. 1298More exactly, if it is set to prefix 1299.I xxx 1300then 1301.B groff 1302as a wrapper program will internally call 1303.IB xxx troff 1304instead of 1305.BR troff . 1306This also applies to the preprocessors 1307.BR \%eqn , 1308.BR \%grn , 1309.BR \%pic , 1310.BR \%refer , 1311.BR \%tbl , 1312.BR \%soelim , 1313and to the utilities 1314.B \%@g@indxbib 1315and 1316.BR \%@g@lookbib . 1317. 1318This feature does not apply to any programs different from the ones 1319above (most notably 1320.B groff 1321itself) since they are unique to the groff package. 1322. 1323. 1324.TP 1325.EnvVar GROFF_FONT_PATH 1326A list of directories in which to search for the 1327.BI dev name 1328directory in addition to the default ones. 1329. 1330See 1331.BR @g@troff (@MAN1EXT@) 1332and 1333.BR \%groff_font (@MAN5EXT@) 1334for more details. 1335. 1336. 1337.TP 1338.EnvVar GROFF_TMAC_PATH 1339A list of directories in which to search for macro files in addition to 1340the default directories. 1341. 1342See 1343.BR @g@troff (@MAN1EXT@) 1344and 1345.BR \%groff_tmac (@MAN5EXT@) 1346for more details. 1347. 1348. 1349.TP 1350.EnvVar GROFF_TMPDIR 1351The directory in which temporary files will be created. 1352. 1353If this is not set but the environment variable 1354.EnvVar TMPDIR 1355instead, temporary files will be created in the directory 1356.EnvVar $TMPDIR . 1357On MS-DOS and Windows\ 32 platforms, the environment variables 1358.EnvVar TMP 1359and 1360.EnvVar TEMP 1361(in that order) are searched also, after 1362.EnvVar GROFF_TMPDIR 1363and 1364.EnvVar TMPDIR . 1365. 1366Otherwise, temporary files will be created in 1367.BR /tmp . 1368The 1369.BR \%@g@refer (@MAN1EXT@), 1370.BR \%groffer (@MAN1EXT@), 1371.BR \%grohtml (@MAN1EXT@), 1372and 1373.BR grops (@MAN1EXT@) 1374commands use temporary files. 1375. 1376. 1377.TP 1378.EnvVar GROFF_TYPESETTER 1379Preset the default device. 1380. 1381If this is not set the 1382.B @DEVICE@ 1383device is used as default. 1384. 1385This device name is overwritten by the option 1386.ShortOpt T . 1387. 1388. 1389.\" -------------------------------------------------------------------- 1390.SH FILES 1391.\" -------------------------------------------------------------------- 1392. 1393There are some directories in which 1394.I groff 1395installs all of its data files. 1396. 1397Due to different installation habits on different operating systems, 1398their locations are not absolutely fixed, but their function is 1399clearly defined and coincides on all systems. 1400. 1401. 1402.\" -------------------------------------------------------------------- 1403.SS "groff Macro Directory" 1404.\" -------------------------------------------------------------------- 1405. 1406This contains all information related to macro packages. 1407. 1408Note that more than a single directory is searched for those files 1409as documented in 1410.BR \%groff_tmac (@MAN5EXT@). 1411. 1412For the groff installation corresponding to this document, it is 1413located at 1414.IR @MACRODIR@ . 1415. 1416The following files contained in the 1417.I groff macro directory 1418have a special meaning: 1419. 1420. 1421.TP 1422.B troffrc 1423Initialization file for troff. 1424. 1425This is interpreted by 1426.B @g@troff 1427before reading the macro sets and any input. 1428. 1429. 1430.TP 1431.B troffrc-end 1432Final startup file for troff, it is parsed after all macro sets have 1433been read. 1434. 1435. 1436.TP 1437.IB name .tmac 1438.TP+ 1439.BI tmac. name 1440Macro file for macro package 1441.IR name . 1442. 1443. 1444.\" -------------------------------------------------------------------- 1445.SS "groff Font Directory" 1446.\" -------------------------------------------------------------------- 1447. 1448This contains all information related to output devices. 1449. 1450Note that more than a single directory is searched for those files; see 1451.BR @g@troff (@MAN1EXT@). 1452. 1453For the groff installation corresponding to this document, it is 1454located at 1455.IR @FONTDIR@ . 1456. 1457The following files contained in the 1458.I groff font directory 1459have a special meaning: 1460. 1461. 1462.TP 1463.BI dev name /DESC 1464Device description file for device 1465.IR name , 1466see 1467.BR \%groff_font (@MAN5EXT@). 1468. 1469. 1470.TP 1471.BI dev name / F 1472Font file for font 1473.I F 1474of device 1475.IR name . 1476. 1477. 1478.\" -------------------------------------------------------------------- 1479.SH EXAMPLES 1480.\" -------------------------------------------------------------------- 1481. 1482The following example illustrates the power of the 1483.B groff 1484program as a wrapper around 1485.BR @g@troff . 1486. 1487.P 1488To process a roff file using the preprocessors 1489.B tbl 1490and 1491.B pic 1492and the 1493.B me 1494macro set, classical troff had to be called by 1495. 1496.P 1497.ShellCommand pic foo.me | tbl | troff \*[@-]me \*[@-]Tlatin1 | grotty 1498. 1499.P 1500Using 1501.BR groff , 1502this pipe can be shortened to the equivalent command 1503.P 1504.ShellCommand groff \*[@-]p \*[@-]t \*[@-]me \*[@-]T latin1 foo.me 1505. 1506.P 1507An even easier way to call this is to use 1508.BR grog (@MAN1EXT@) 1509to guess the preprocessor and macro options and execute the generated 1510command (by using backquotes to specify shell command substitution) 1511.P 1512.ShellCommand \`grog \*[@-]Tlatin1 foo.me\` 1513. 1514.P 1515The simplest way is to view the contents in an automated way by 1516calling 1517. 1518.P 1519.ShellCommand groffer foo.me 1520. 1521. 1522.\" -------------------------------------------------------------------- 1523.SH BUGS 1524.\" -------------------------------------------------------------------- 1525. 1526.P 1527On EBCDIC hosts (e.g. OS/390 Unix), output devices 1528.B ascii 1529and 1530.B latin1 1531aren't available. 1532. 1533Similarly, output for EBCDIC code page 1534.B cp1047 1535is not available on ASCII based operating systems. 1536. 1537.P 1538Report bugs to bug-groff@gnu.org. 1539. 1540Include a complete, self-contained example that will allow the bug to 1541be reproduced, and say which version of groff you are using. 1542. 1543. 1544.\" -------------------------------------------------------------------- 1545.SH AVAILABILITY 1546.\" -------------------------------------------------------------------- 1547. 1548Information on how to get groff and related information is available 1549at the 1550.URL http://\:www.gnu.org/\:software/\:groff "GNU website" . 1551The most recent released version of groff is available for anonymous 1552ftp at the 1553.URL ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz \ 1554 "groff development site" . 1555. 1556.P 1557Three groff mailing lists are available: 1558.TP 1559.MTO bug-groff@gnu.org 1560for reporting bugs, 1561. 1562.TP 1563.MTO groff@gnu.org 1564for general discussion of groff, 1565. 1566.TP 1567.MTO groff-commit@ffii.org 1568a read-only list showing logs of commitments to the CVS repository. 1569. 1570.P 1571Details on CVS access and much more can be found in the file 1572.B README 1573at the top directory of the groff source package. 1574. 1575.P 1576There is a free implementation of the 1577.B grap 1578preprocessor, written by 1579.MTO faber@lunabase.org " Ted Faber" . 1580. 1581The actual version can be found at the 1582. 1583.URL http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ \ 1584 "grap website" . 1585This is the only grap version supported by groff. 1586. 1587. 1588.\" -------------------------------------------------------------------- 1589.SH AUTHORS 1590.\" -------------------------------------------------------------------- 1591. 1592Copyright \(co 1989, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. 1593. 1594.P 1595This document is distributed under the terms of the FDL (GNU Free 1596Documentation License) version 1.1 or later. 1597. 1598You should have received a copy of the FDL on your system, it is also 1599available on-line at the 1600.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 1601. 1602.P 1603This document is based on the original groff man page written by 1604.MTO jjc@jclark.com "James Clark" . 1605. 1606It was rewritten, enhanced, and put under the FDL license by 1607\m[blue]Bernd Warken\m[]. 1608. 1609It is maintained by 1610.MTO wl@gnu.org "Werner Lemberg" . 1611. 1612.P 1613.I groff 1614is a GNU free software project. 1615. 1616All parts of the 1617.I groff package 1618are protected by GNU copyleft licenses. 1619. 1620The software files are distributed under the terms of the GNU General 1621Public License (GPL), while the documentation files mostly use the GNU 1622Free Documentation License (FDL). 1623. 1624. 1625.\" -------------------------------------------------------------------- 1626.SH "SEE ALSO" 1627.\" -------------------------------------------------------------------- 1628. 1629The 1630.IR "groff info file" 1631contains all information on the groff system within a single document. 1632. 1633Beneath the detailed documentation of all aspects, it provides 1634examples and background information. 1635. 1636See 1637.BR info (1) 1638on how to read it. 1639. 1640.P 1641Due to its complex structure, the groff system has many man pages. 1642. 1643They can be read with 1644.BR man (1) 1645or 1646.BR \%groffer (@MAN1EXT@). 1647. 1648.TP 1649Introduction, history and further readings: 1650.BR roff (@MAN7EXT@). 1651. 1652.TP 1653Viewer for groff files: 1654.BR \%groffer (@MAN1EXT@), 1655.BR \%gxditview (@MAN1EXT@), 1656.BR \%xditview (1x). 1657. 1658.TP 1659Wrapper programs for formatters: 1660.BR \%groff (@MAN1EXT@), 1661.BR \%grog (@MAN1EXT@). 1662. 1663.TP 1664Roff preprocessors: 1665.BR \%@g@eqn (@MAN1EXT@), 1666.BR \%@g@grn (@MAN1EXT@), 1667.BR \%@g@pic (@MAN1EXT@), 1668.BR \%@g@refer (@MAN1EXT@), 1669.BR \%@g@soelim (@MAN1EXT@), 1670.BR \%@g@tbl (@MAN1EXT@), 1671.BR grap (1). 1672. 1673.TP 1674Roff language with the groff extensions: 1675.BR \%groff (@MAN7EXT@), 1676.BR \%groff_char (@MAN7EXT@), 1677.BR \%groff_diff (@MAN7EXT@), 1678.BR \%groff_font (@MAN5EXT@). 1679. 1680.TP 1681Roff formatter programs: 1682.BR \%@g@nroff (@MAN1EXT@), 1683.BR \%@g@troff (@MAN1EXT@), 1684.BR ditroff (@MAN7EXT@). 1685. 1686.TP 1687The 1688.I intermediate output 1689language: 1690.BR \%groff_out (@MAN7EXT@). 1691. 1692.TP 1693Postprocessors for the output devices: 1694.BR \%grodvi (@MAN1EXT@), 1695.BR \%grohtml (@MAN1EXT@), 1696.BR \%grolbp (@MAN1EXT@), 1697.BR \%grolj4 (@MAN1EXT@), 1698.BR \%lj4_font (@MAN5EXT@), 1699.BR \%grops (@MAN1EXT@), 1700.BR \%grotty (@MAN1EXT@). 1701. 1702.TP 1703Groff macro packages and macro-specific utilities: 1704.BR \%groff_tmac (@MAN5EXT@), 1705.BR \%groff_man (@MAN7EXT@), 1706.BR \%groff_mdoc (@MAN7EXT@), 1707.BR \%groff_me (@MAN7EXT@), 1708.BR \%groff_mm (@MAN7EXT@), 1709.BR \%groff_mmse (@MAN7EXT@), 1710.BR \%groff_mom (@MAN7EXT@), 1711.BR \%groff_ms (@MAN7EXT@), 1712.BR \%groff_www (@MAN7EXT@), 1713.BR \%groff_trace (@MAN7EXT@), 1714.BR \%mmroff (@MAN7EXT@). 1715. 1716.TP 1717The following utilities are available: 1718.BR \%addftinfo (@MAN1EXT@), 1719.BR \%afmtodit (@MAN1EXT@), 1720.BR \%eqn2graph (@MAN1EXT@), 1721.BR \%grap2graph (@MAN1EXT@), 1722.BR \%groffer (@MAN1EXT@), 1723.BR \%gxditview (@MAN1EXT@), 1724.BR \%hpftodit (@MAN1EXT@), 1725.BR \%@g@indxbib (@MAN1EXT@), 1726.BR \%@g@lookbib (@MAN1EXT@), 1727.BR \%pfbtops (@MAN1EXT@), 1728.BR \%pic2graph (@MAN1EXT@), 1729.BR \%tfmtodit (@MAN1EXT@). 1730. 1731.cp \n[groff_C] 1732. 1733.\" -------------------------------------------------------------------- 1734.\" Emacs setup 1735.\" -------------------------------------------------------------------- 1736. 1737.\" Local Variables: 1738.\" mode: nroff 1739.\" End: 1740