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