roff.man revision 104862
1.ig 2roff.man 3 4Last update: 22 Apr 2002 5 6This file is part of groff, the GNU roff type-setting system. 7 8Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 9written by Bernd Warken <bwarken@mayn.de> 10maintained by Werner Lemberg <wl@gnu.org> 11 12Permission is granted to copy, distribute and/or modify this document 13under the terms of the GNU Free Documentation License, Version 1.1 or 14any later version published by the Free Software Foundation; with the 15Invariant Sections being this .ig-section and AUTHORS, with no 16Front-Cover Texts, and with no Back-Cover Texts. 17 18A copy of the Free Documentation License is included as a file called 19FDL in the main directory of the groff source package. 20.. 21. 22.\" -------------------------------------------------------------------- 23.\" Setup 24.\" -------------------------------------------------------------------- 25. 26.mso www.tmac 27. 28.if n \{\ 29. mso tty-char.tmac 30. ftr CR R 31. ftr CI I 32. ftr CB B 33.\} 34. 35.if '\*[.T]'dvi' \{\ 36. ftr CB CW 37.\} 38. 39. 40.\" -------------------------------------------------------------------- 41.\" String definitions 42. 43.\" Final `\""' comments are used to make Emacs happy, sic \"" 44. 45.\" The `-' sign for options. 46.ie t \{\ 47. ds @- \-\" 48. ds @-- \-\-\" 49.\} 50.el \{\ 51. ds @- -\" 52. ds @-- --\" 53.\} 54. 55.ds Comment \.\[rs]\[dq]\" 56.ds Ellipsis \.\|.\|.\&\" 57. 58. 59.\" -------------------------------------------------------------------- 60.\" Begin of macro definitions 61. 62.de c 63.\" this is like a comment request when escape mechanism is off 64.. 65. 66.eo 67. 68.c --------------------------------------------------------------------- 69. 70.de Text 71. nop \)\$* 72.. 73. 74.de CodeSkip 75. ie t \ 76. sp 0.2v 77. el \ 78. sp 79.. 80. 81.de Esc 82. ds @1 \$1\" 83. shift 84. Text \f[B]\[rs]\*[@1]\f[]\$* 85. rm @1 86.. 87. 88.de QuotedChar 89. ds @1 \$1 90. shift 91. nop `\f[B]\*[@1]\f[]'\$* 92. rm @1 93.. 94. 95.c -------------------------------------------------------------------- 96. 97.c a shell command line 98.de ShellCommand 99. br 100. ad l 101. nh 102. Text \f[I]sh#\h'1m'\f[]\f[CR]\$*\f[]\&\" 103. ft R 104. ft P 105. hy 106. ad 107.. 108. 109.c -------------------------------------------------------------------- 110. 111.c ShortOpt ([c [punct]]) 112.c 113.c `-c' somewhere in the text. 114.c The second argument is some trailing punctuation. 115.c 116.de ShortOpt 117. ds @1 \$1\" 118. shift 119. nh 120. Text \f[CB]\*[@-]\f[]\f[B]\*[@1]\f[]\/\$* 121. hy 122. rm @1 123.. 124. 125.de TP+ 126. br 127. ns 128. TP \$1 129.. 130. 131.c -------------------------------------------------------------------- 132. 133.c Topic 134.c 135.de Topic 136. TP 2m 137. Text \[bu] 138.. 139. 140.ec 141.\" End of macro definitions 142. 143. 144.\" -------------------------------------------------------------------- 145.\" Title 146.\" -------------------------------------------------------------------- 147. 148.TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 149.SH NAME 150roff \- concepts and history of roff typesetting 151. 152. 153.\" -------------------------------------------------------------------- 154.SH DESCRIPTION 155.\" -------------------------------------------------------------------- 156. 157.I roff 158is the general name for a set of type-setting programs, known under 159names like 160.IR troff , 161.IR nroff , 162.IR ditroff , 163.IR groff , 164etc. 165. 166A roff type-setting system consists of an extensible text formatting 167language and a set of programs for printing and converting to other 168text formats. 169. 170Traditionally, it is the main text processing system of Unix; every 171Unix-like operating system still distributes a roff system as a core 172package. 173. 174.P 175The most common roff system today is the free software implementation 176.IR "GNU roff", 177.BR groff (@MAN1EXT@). 178. 179The pre-groff implementations are referred to as 180.I classical 181(dating back as long as 1973). 182. 183.I groff 184implements the look-and-feel and functionality of its classical 185ancestors, but has many extensions. 186. 187As 188.I groff 189is the only roff system that is available for every (or almost every) 190computer system it is the de-facto roff standard today. 191. 192.P 193In some ancient Unix systems, there was a binary called 194.B roff 195that implemented the even more ancient 196.B runoff 197of the 198.I Multics 199operating system, cf. section 200.BR HISTORY . 201The functionality of this program was very restricted even in 202comparison to ancient troff; it is not supported any longer. 203. 204Consequently, in this document, the term 205.I roff 206always refers to the general meaning of 207.IR "roff system" , 208not to the ancient roff binary. 209. 210.P 211In spite of its age, roff is in wide use today, for example, the manual 212pages on UNIX systems 213.RI ( man\~pages\/ ), 214many software books, system documentation, standards, and corporate 215documents are written in roff. 216. 217The roff output for text devices is still unmatched, and its graphical 218output has the same quality as other free type-setting programs and is 219better than some of the commercial systems. 220. 221.P 222The most popular application of roff is the concept of 223.I manual pages 224or shortly 225.IR "man pages" ; 226this is the standard documentation system on many operating systems. 227. 228.P 229This document describes the historical facts around the development 230of the 231.IR "roff system" ; 232some usage aspects common to all roff versions, details on the roff 233pipeline, which is usually hidden behind front-ends like 234.BR groff (@MAN1EXT@); 235an general overview of the formatting language; some tips for editing 236roff files; and many pointers to further readings. 237. 238. 239.\" -------------------------------------------------------------------- 240.SH "HISTORY" 241.\" -------------------------------------------------------------------- 242. 243The 244.I roff 245text processing system has a very long history, dating back to the 2461960s. 247. 248The roff system itself is intimately connected to the Unix operating 249system, but its roots go back to the earlier operating systems CTSS 250and Multics. 251. 252. 253.\" -------------------------------------------------------------------- 254.SS "The Predecessor runoff" 255.\" -------------------------------------------------------------------- 256. 257.P 258The evolution of 259.I roff 260is intimately related to the history of the operating systems. 261. 262Its predecessor 263.B runoff 264was written by 265.I Jerry Saltzer 266on the 267.I CTSS 268operating system 269.RI ( "Compatible Time Sharing System" ) 270as early as 1961. 271. 272When CTTS was further developed into the operating system 273.URL http://\:www.multicians.org "Multics" , 274the famous predecessor of Unix from 1963, 275.I runoff 276became the main format for documentation and text processing. 277. 278Both operating systems could only be run on very expensive computers 279at that time, so they were mostly used in research and for official 280and military tasks. 281. 282.P 283The possibilities of the 284.I runoff 285language were quite limited as compared to modern roff. 286. 287Only text output was possible in the 1960s. 288. 289This could be implemented by a set of requests of length\~2, many of 290which are still identically used in roff. 291. 292The language was modelled according to the habits of typesetting in 293the pre-computer age, where lines starting with a dot were used in 294manuscripts to denote formatting requests to the person who would 295perform the typesetting manually later on. 296. 297.P 298The runoff program was written in the 299.I PL/1 300language first, later on in 301.IR BCPL , 302the grandmother of the 303.IR C \~\c 304programming language. 305. 306In the Multics operating system, the help system was handled by 307runoff, similar to roff's task to manage the Unix manual pages. 308. 309There are still documents written in the runoff language; for examples 310see Saltzer's home page, cf. section 311.BR "SEE ALSO" . 312. 313. 314.\" -------------------------------------------------------------------- 315.SS "The Classical nroff/troff System" 316.\" -------------------------------------------------------------------- 317. 318In the 1970s, the Multics off-spring 319.I Unix 320became more and more popular because it could be run on affordable 321machines and was easily available for universities at that time. 322. 323At MIT (the Massachusetts Institute of Technology), there was a need to 324drive the Wang 325.I Graphic Systems CAT 326typesetter, a graphical output device from a PDP-11 computer running 327Unix. 328. 329As runoff was too limited for this task it was further developed into 330a more powerful text formatting system by 331.IR "Josef F. Osanna" , 332a main developer of the Multics operating system and programmer of 333several runoff ports. 334. 335.P 336The name 337.I runoff 338was shortened to 339.IR roff . 340The greatly enlarged language of Osanna's concept included already all 341elements of a full 342.IR "roff system" . 343. 344All modern roff systems try to implement compatibility to this system. 345. 346So Joe Osanna can be called the father of all roff systems. 347. 348.P 349This first 350.I roff system 351had three formatter programs. 352. 353.TP 354.B troff 355.RI ( "typesetter roff\/" ) 356generated a graphical output for the 357.I CAT 358typesetter as its only device. 359. 360.TP 361.B nroff 362produced text output suitable for terminals and line printers. 363. 364.TP 365.B roff 366was the reimplementation of the former runoff program with its limited 367features; this program was abandoned in later versions. 368. 369Today, the name 370.I roff 371is used to refer to a troff/\:nroff sytem as a whole. 372. 373.P 374Osanna first version was written in the PDP-11 assembly language and 375released in 1973. 376. 377.I Brian Kernighan 378joined the 379.I roff 380development by rewriting it in the C\~programming language. 381. 382The C\~version was released in 1975. 383. 384.P 385The syntax of the formatting language of the 386.BR nroff / troff 387programs was documented in the famous 388.IR "Troff User's Manual [CSTR\~#54]" , 389first published in 1976, with further revisions up to 1992 by Brian 390Kernighan. 391. 392This document is the specification of the 393.IR "classical troff" . 394All later 395.I roff 396systems tried to establish compatibility with this specification. 397. 398.P 399After Osanna had died in 1977 by a heart-attack at the age of about\~50, 400Kernighan went on with developing troff. 401. 402The next milestone was to equip troff with a general interface to 403support more devices, the intermediate output format and the 404postprocessor system. 405. 406This completed the structure of a 407.I "roff system" 408as it is still in use today; see section 409.BR "USING ROFF" . 410. 411In 1979, these novelties were described in the paper 412.IR "[CSTR\~#97]" . 413This new troff version is the basis for all existing newer troff 414systems, including 415.IR groff . 416. 417On some systems, this 418.I device independent troff 419got a binary of its own, called 420.BR ditroff (@MAN7EXT@). 421. 422All modern 423.B troff 424programs already provide the full ditroff capabilities automatically. 425. 426. 427.\" -------------------------------------------------------------------- 428.SS "Commercialization" 429.\" -------------------------------------------------------------------- 430. 431A major degradation occurred when the easily available Unix\~7 432operating system was commercialized. 433. 434A whole bunch of divergent operating systems emerged, fighting each 435other with incompatibilities in their extensions. 436. 437Luckily, the incompatibilities did not fight the original troff. 438. 439All of the different commercial roff systems made heavy use of 440Osanna/\:Kernighan's open source code and documentation, but sold them 441as \[lq]their\[rq] system \[em] with only minor additions. 442. 443.P 444The source code of both the ancient Unix and classical troff weren't 445available for two decades. 446. 447Fortunately, Caldera bought SCO UNIX in 2001. 448. 449In the following, Caldera made the ancient source code accessible 450on-line for non-commercial use, cf. section 451.BR "SEE ALSO" . 452. 453. 454.\" -------------------------------------------------------------------- 455.SS "Free roff" 456.\" -------------------------------------------------------------------- 457. 458None of the commercial roff systems could attain the status of a 459successor for the general roff development. 460. 461Everyone was only interested in their own stuff. 462. 463This led to a steep downfall of the once excellent 464Unix operating system during the 1980s. 465. 466.P 467As a counter-measure to the galopping commercialization, AT&T Bell 468Labs tried to launch a rescue project with their 469.I Plan\~9 470operating system. 471. 472It is freely available for non-commercial use, even the source code, 473but has a proprietary license that empedes the free development. 474. 475This concept is outdated, so Plan\~9 was not accepted as a platform to 476bundle the main-stream development. 477. 478.P 479The only remedy came from the emerging free operatings systems 480(386BSD, GNU/\:Linux, etc.) and software projects during the 1980s and 4811990s. 482. 483These implemented the ancient Unix features and many extensions, such 484that the old experience is not lost. 485. 486In the 21st century, Unix-like systems are again a major factor in 487computer industry \[em] thanks to free software. 488. 489.P 490The most important free roff project was the GNU port of troff, 491created by James Clark and put under the 492.URL http://\:www.gnu.org/\:copyleft "GNU Public License" . 493. 494It was called 495.I groff 496.RI ( "GNU roff" ). 497See 498.BR groff (@MAN1EXT@) 499for an overview. 500. 501.P 502The groff system is still actively developed. 503. 504It is compatible to the classical troff, but many extensions were 505added. 506. 507It is the first roff system that is available on almost all operating 508systems \[em] and it is free. 509. 510This makes groff the de-facto roff standard today. 511. 512. 513.\" -------------------------------------------------------------------- 514.SH "USING ROFF" 515.\" -------------------------------------------------------------------- 516. 517Most people won't even notice that they are actually using roff. 518. 519When you read a system manual page (man page) roff is working in the 520background. 521. 522Roff documents can be viewed with a native viewer called 523.BR xditview (1x), 524a standard program of the X window distribution, see 525.BR X (7x). 526. 527But using roff explicitly isn't difficult either. 528. 529.P 530Some roff implementations provide wrapper programs that make it easy 531to use the roff system on the shell command line. 532. 533For example, the GNU roff implementation 534.BR groff (@MAN1EXT@) 535provides command line options to avoid the long command pipes of 536classical troff; a program 537.BR grog (@MAN1EXT@) 538tries to guess from the document which arguments should be used for a 539run of groff; people who do not like specifying command line options 540should try the 541.BR groffer (@MAN1EXT@) 542program for graphically displaying groff files and man pages. 543. 544. 545.\" -------------------------------------------------------------------- 546.SS "The roff Pipe" 547.\" -------------------------------------------------------------------- 548. 549Each roff system consists of preprocessors, roff formatter programs, 550and a set of device postprocessors. 551. 552This concept makes heavy use of the 553.I piping 554mechanism, that is, a series of programs is called one after the other, 555where the output of each program in the queue is taken as the input 556for the next program. 557. 558.CodeSkip 559. 560.ds @1 "cat \f[I]file\f[P] |\"" 561.ds @2 "\*[Ellipsis] | \f[I]preproc\f[P] | \*[Ellipsis] |\"" 562.ds @3 "troff \f[I]options\f[P] | \f[I]postproc\f[P]\"" 563. 564.ShellCommand "\*[@1] \*[@2] \*[@3]" 565. 566.rm @1 567.rm @2 568.rm @3 569.P 570The preprocessors generate roff code that is fed into a roff formatter 571(e.g. troff), which in turn generates 572.I intermediate output 573that is fed into a device postprocessor program for printing or final 574output. 575. 576.P 577All of these parts use programming languages of their own; each 578language is totally unrelated to the other parts. 579. 580Moreover, roff macro packages that were tailored for special purposes 581can be included. 582. 583.P 584Most roff documents use the macros of some package, intermixed with 585code for one or more preprocessors, spiced with some elements from the 586plain roff language. 587. 588The full power of the roff formatting language is seldom needed by 589users; only programmers of macro packages need to know about the gory 590details. 591. 592. 593. 594.\" -------------------------------------------------------------------- 595.SS "Preprocessors" 596.\" -------------------------------------------------------------------- 597. 598A roff preprocessor is any program that generates output that 599syntactically obeys the rules of the roff formatting language. 600. 601Each preprocessor defines a language of its own that is translated 602into roff code when run through the preprocessor program. 603. 604Parts written in these languages may be included within a roff 605document; they are identified by special roff requests or macros. 606. 607Each document that is enhanced by preprocessor code must be run 608through all corresponding preprocessors before it is fed into the 609actual roff formatter program, for the formatter just ignores all 610alien code. 611. 612The preprocessor programs extract and transform only the document 613parts that are determined for them. 614. 615.P 616There are a lot of free and commercial roff preprocessors. 617. 618Some of them aren't available on each system, but there is a small 619set of preprocessors that are considered as an integral part of each 620roff system. 621. 622The classical preprocessors are 623. 624 625.de @TP 626.\" local indent for .TP 627.TP \\w'\\f[B]soelim\\f[P]'u+2n 628.. 629.P 630.RS 631.PD 0 632.@TP 633.B tbl 634for tables 635.@TP 636.B eqn 637for mathematical formul\[ae] 638.@TP 639.B pic 640for drawing diagrams 641.@TP 642.B refer 643for bibliographic references 644.@TP 645.B soelim 646for including macro files from standard locations 647.PD 648.RE 649. 650.P 651Other known preprocessors that are not available on all systems 652include 653. 654.P 655.RS 656.PD 0 657.@TP 658.B chem 659for drawing chemical formul\[ae]. 660.@TP 661.B grap 662for constructing graphical elements. 663.@TP 664.B grn 665for including 666.BR gremlin (1) 667pictures. 668.PD 669.RE 670. 671.rm @TP 672. 673.\" -------------------------------------------------------------------- 674.SS "Formatter Programs" 675.\" -------------------------------------------------------------------- 676. 677A 678.I roff formatter 679is a program that parses documents written in the roff formatting 680language or uses some of the roff macro packages. 681. 682It generates 683.IR "intermediate output" , 684which is intended to be fed into a single device postprocessor that 685must be specified by a command-line option to the formatter program. 686. 687The documents must have been run through all necessary preprocessors 688before. 689. 690.P 691The output produced by a roff formatter is represented in yet another 692language, the 693.IR "intermediate output format" 694or 695.IR "troff output" . 696This language was first specified in 697.IR "[CSTR\~#97]" ; 698its GNU extension is documented in 699.BR groff_out (@MAN5EXT@). 700. 701The intermediate output language is a kind of assembly language 702compared to the high-level roff language. 703. 704The generated intermediate output is optimized for a special device, 705but the language is the same for every device. 706. 707.P 708The roff formatter is the heart of the roff system. 709. 710The traditional roff had two formatters, 711.B nroff 712for text devices and 713.B troff 714for graphical devices. 715. 716.P 717Often, the name 718.I troff 719is used as a general term to refer to both formatters. 720. 721. 722.\" -------------------------------------------------------------------- 723.SS "Devices and Postprocessors" 724.\" -------------------------------------------------------------------- 725. 726Devices are hardware interfaces like printers, text or graphical 727terminals, etc., or software interfaces such as a conversion into a 728different text or graphical format. 729. 730.P 731A roff postprocessor is a program that transforms troff output into a 732form suitable for a special device. 733. 734The roff postprocessors are like device drivers for the output target. 735. 736.P 737For each device there is a postprocessor program that fits the device 738optimally. 739. 740The postprocessor parses the generated intermediate output and 741generates device-specific code that is sent directly to the device. 742. 743.P 744The names of the devices and the postprocessor programs are not fixed 745because they greatly depend on the software and hardware abilities of 746the actual computer. 747. 748For example, the classical devices mentioned in 749.I [CSTR\~#54] 750have greatly changed since the classical times. 751. 752The old hardware doesn't exist any longer and the old graphical 753conversions were quite imprecise when compared to their modern 754counterparts. 755. 756.P 757For example, the Postscript device 758.I post 759in classical troff had a resolution 760of 720, while groff's 761.I ps 762device has 72000, a refinement of factor 100. 763. 764.P 765Today the operating systems provide device drivers for most 766printer-like hardware, so it isn't necessary to write a special 767hardware postprocessor for each printer. 768. 769. 770.\" -------------------------------------------------------------------- 771.SH "ROFF PROGRAMMING" 772.\" -------------------------------------------------------------------- 773. 774Documents using roff are normal text files decorated by roff 775formatting elements. 776. 777The roff formatting language is quite powerful; it is almost a full 778programming language and provides elements to enlarge the language. 779. 780With these, it became possible to develop macro packages that are 781tailored for special applications. 782. 783Such macro packages are much handier than plain roff. 784. 785So most people will choose a macro package without worrying about the 786internals of the roff language. 787. 788. 789.\" -------------------------------------------------------------------- 790.SS "Macro Packages" 791.\" -------------------------------------------------------------------- 792. 793Macro packages are collections of macros that are suitable to format a 794special kind of documents in a convenient way. 795. 796This greatly eases the usage of roff. 797. 798The macro definitions of a package are kept in a file called 799.IB name .tmac 800(classically 801.BI tmac. name\c 802). 803. 804All tmac files are stored in one or more directories at standardized 805positions. 806. 807Details on the naming of macro packages and their placement is found 808in 809.BR groff_tmac (@MAN5EXT@). 810. 811.P 812A macro package that is to be used in a document can be announced to 813the formatter by the command line option 814.ShortOpt m , 815see 816.BR troff (@MAN1EXT@), 817or it can be specified within a document using the file inclusion 818requests of the roff language, see 819.BR groff (@MAN7EXT@). 820. 821.P 822Famous classical macro packages are 823.I man 824for traditional man pages, 825.I mdoc 826for BSD-style manual pages; 827the macro sets for books, articles, and letters are 828.I me 829(probably from the first name of its creator 830.I Eric 831Allman), 832.I ms 833(from 834.IR "Manuscript Macros\/" ), 835and 836.I mm 837(from 838.IR "Memorandum Macros\/" ). 839. 840. 841.\" -------------------------------------------------------------------- 842.SS "The roff Formatting Language" 843.\" -------------------------------------------------------------------- 844. 845The classical roff formatting language is documented in the 846.I Troff User's Manual 847.IR "[CSTR\~#54]" . 848. 849The roff language is a full programming language providing requests, 850definition of macros, escape sequences, string variables, number or 851size registers, and flow controls. 852. 853.P 854.I Requests 855are the predefined basic formatting commands similar to the commands 856at the shell prompt. 857. 858The user can define request-like elements using predefined roff 859elements. 860. 861These are then called 862.IR macros . 863. 864A document writer will not note any difference in usage for requests 865or macros; both are written on a line on their own starting with a dot. 866. 867.P 868.I Escape sequences 869are roff elements starting with a backslash 870.QuotedChar \[rs] . 871They can be inserted anywhere, also in the midst of text in a line. 872. 873They are used to implement various features, including the insertion of 874non-ASCII characters with 875.Esc ( , 876font changes with 877.Esc f , 878in-line comments with 879.Esc \[dq] , 880the escaping of special control characters like 881.Esc \[rs] , 882and many other features. 883. 884.P 885.I Strings 886are variables that can store a string. 887. 888A string is stored by the 889.B .ds 890request. 891. 892The stored string can be retrieved later by the 893.B \[rs]* 894escape sequence. 895. 896.P 897.I Registers 898store numbers and sizes. 899. 900A register can be set with the request 901.B .nr 902and its value can be retrieved by the escape sequence 903.BR "\[rs]n" . 904. 905. 906.\" -------------------------------------------------------------------- 907.SH "FILE NAME EXTENSIONS" 908.\" -------------------------------------------------------------------- 909. 910Manual pages (man pages) take the section number as a file name 911extension, e.g., the filename for this document is 912.IR roff.7 , 913i.e., it is kept in section\~7 914of the man pages. 915. 916.P 917The classical macro packages take the package name as an extension, e.g. 918.IB file. me 919for a document using the 920.I me 921macro package, 922.IB file. mm 923for 924.IR mm , 925.IB file. ms 926for 927.IR ms , 928.IB file. pic 929for 930.I pic 931files, 932etc. 933. 934.P 935But there is no general naming scheme for roff documents, though 936.IB file. tr 937for 938.I troff file 939is seen now and then. 940. 941Maybe there should be a standardization for the filename extensions of 942roff files. 943. 944.P 945File name extensions can be very handy in conjunction with the 946.BR less (1) 947pager. 948. 949It provides the possibility to feed all input into a command-line pipe 950that is specified in the shell environment variable 951.BR LESSOPEN . 952This process is not well documented, so here an example: 953. 954.CodeSkip 955.ShellCommand LESSOPEN='|lesspipe %s' 956.CodeSkip 957. 958where 959.B lesspipe 960is either a system supplied command or a shell script of your own. 961. 962. 963.\" -------------------------------------------------------------------- 964.SH "EDITING ROFF" 965.\" -------------------------------------------------------------------- 966. 967The best program for editing a roff document is Emacs (or Xemacs), see 968.BR emacs (1). 969It provides an 970.I nroff 971mode that is suitable for all kinds of roff dialects. 972. 973This mode can be activated by the following methods. 974. 975.P 976When editing a file within Emacs the mode can be changed by typing 977.RI ` "M-x nroff-mode" ', 978where 979.B M-x 980means to hold down the 981.B Meta 982key (or 983.BR Alt ) 984and hitting the 985.BR x\~ key 986at the same time. 987. 988.P 989But it is also possible to have the mode automatically selected when 990the file is loaded into the editor. 991. 992.Topic 993The most general method is to include the following 3 comment lines at 994the end of the file. 995. 996.CodeSkip 997.nf 998.B \*[Comment] Local Variables: 999.B \*[Comment] mode: nroff 1000.B \*[Comment] End: 1001.fi 1002. 1003.Topic 1004There is a set of file name extensions, e.g. the man pages that 1005trigger the automatic activation of the nroff mode. 1006. 1007.Topic 1008Theoretically, it is possible to write the sequence 1009.CodeSkip 1010.B \*[Comment] \%-*-\ nroff\ -*- 1011.CodeSkip 1012as the first line of a file to have it started in nroff mode when 1013loaded. 1014. 1015Unfortunately, some applications such as the 1016.B man 1017program are confused by this; so this is deprecated. 1018. 1019.P 1020All roff formatters provide automated line breaks and horizontal and 1021vertical spacing. 1022. 1023In order to not disturb this, the following tips can be helpful. 1024. 1025.Topic 1026Never include empty or blank lines in a roff document. 1027. 1028Instead, use the empty request (a line consisting of a dot only) or a 1029line comment 1030.B \*[Comment] 1031if a structuring element is needed. 1032. 1033.Topic 1034Never start a line with whitespace because this can lead to 1035unexpected behavior. 1036. 1037Indented paragraphs can be constructed in a controlled way by roff 1038requests. 1039. 1040.Topic 1041Start each sentence on a line of its own, for the spacing after a dot 1042is handled differently depending on whether it terminates an 1043abbreviation or a sentence. 1044. 1045To distinguish both cases, do a line break after each sentence. 1046. 1047.Topic 1048To additionally use the auto-fill mode in Emacs, it is best to insert 1049an empty roff request (a line consisting of a dot only) after each 1050sentence. 1051. 1052.P 1053The following example shows how optimal roff editing could look. 1054. 1055.IP 1056.nf 1057This is an example for a roff document. 1058.Text . 1059This is the next sentence in the same paragraph. 1060.Text . 1061This is a longer sentence stretching over several 1062lines; abbreviations like `cf.' are easily 1063identified because the dot is not followed by a 1064line break. 1065.Text . 1066In the output, this will still go to the same 1067paragraph. 1068.fi 1069. 1070.P 1071Besides Emacs, some other editors provide nroff style files too, e.g.\& 1072.BR vim (1), 1073an extension of the 1074.BR vi (1) 1075program. 1076. 1077. 1078.\" -------------------------------------------------------------------- 1079.SH BUGS 1080.\" -------------------------------------------------------------------- 1081. 1082.I UNIX\[rg] 1083is a registered trademark of the Open Group. 1084. 1085But things have improved considerably after Caldera had bought SCO 1086UNIX in 2001. 1087. 1088. 1089.\" -------------------------------------------------------------------- 1090.SH "SEE ALSO" 1091.\" -------------------------------------------------------------------- 1092. 1093There is a lot of documentation on roff. 1094. 1095The original papers on classical troff are still available, and all 1096aspects of groff are documented in great detail. 1097. 1098. 1099.\" -------------------------------------------------------------------- 1100.SS "Internet sites" 1101.\" -------------------------------------------------------------------- 1102. 1103.TP 1104troff.org 1105.URL http://\:www.troff.org "The historical troff site" 1106provides an overview and pointers to all historical aspects of roff. 1107. 1108This web site is under construction; once, it will be the major source 1109for roff history. 1110. 1111.TP 1112Multics 1113.URL http://\:www.multicians.org "The Multics site" 1114contains a lot of information on the MIT projects, CTSS, Multics, 1115early Unix, including 1116.IR runoff ; 1117especially useful are a glossary and the many links to ancient 1118documents. 1119. 1120.TP 1121Unix Archive 1122.URL http://\:www.tuhs.org/\:Archive/ \ 1123 "The Ancient Unixes Archive" 1124. 1125provides the source code and some binaries of the ancient Unixes 1126(including the source code of troff and its documentation) that were 1127made public by Caldera since 2001, e.g. of the famous Unix version\~7 1128for PDP-11 at the 1129.URL http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7 \ 1130 "Unix V7 site" . 1131. 1132.TP 1133Developers at AT&T Bell Labs 1134.URL http://\:cm.bell-labs.com/\:cm/\:index.html \ 1135 "Bell Labs Computing and Mathematical Sciences Research" 1136. 1137provides a search facility for tracking information on the early 1138developers. 1139. 1140.TP 1141Plan 9 1142.URL http://\:plan9.bell-labs.com "The Plan\~9 operating system" 1143. 1144by AT&T Bell Labs. 1145. 1146.TP 1147runoff 1148.URL http://web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html \ 1149"Jerry Saltzer's home page" 1150. 1151stores some documents using the ancient runoff formatting language. 1152. 1153.TP 1154CSTR Papers 1155.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \ 1156 "The Bell Labs CSTR site" 1157. 1158stores the original troff manuals (CSTR #54, #97, #114, #116, #122) 1159and famous historical documents on programming. 1160. 1161.TP 1162GNU roff 1163.URL http://\:www.gnu.org/\:software/\:groff "The groff web site" 1164provides the free roff implementation groff, the actual standard roff. 1165. 1166. 1167.\" -------------------------------------------------------------------- 1168.SS "Historical roff Documentation" 1169.\" -------------------------------------------------------------------- 1170. 1171Many classical 1172.troff 1173documents are still available on-line. 1174. 1175The two main manuals of the troff language are 1176. 1177.TP 1178[CSTR\~#54] 1179J. F. Osanna, 1180.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \ 1181 "\fINroff/\:Troff User's Manual\fP" ; 1182. 1183Bell Labs, 1976; revised by Brian Kernighan, 1992. 1184 1185. 1186.TP 1187[CSTR\~#97] 1188Brian Kernighan, 1189.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps \ 1190 "\fIA Typesetter-independent TROFF\fP" , 1191. 1192Bell Labs, 1981, revised March 1982. 1193. 1194.P 1195The "little language" roff papers are 1196. 1197.TP 1198[CSTR\~#114] 1199Jon L. Bentley and Brian W. Kernighan, 1200.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:114.ps \ 1201 "\fIGRAP \(em A Language for Typesetting Graphs\fP" ; 1202. 1203Bell Labs, August 1984. 1204. 1205.TP 1206[CSTR\~#116] 1207Brian W. Kernighan, 1208.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:116.ps \ 1209 "\fIPIC -- A Graphics Language for Typesetting\fP" ; 1210. 1211Bell Labs, December 1984. 1212. 1213.TP 1214[CSTR\~#122] 1215J. L. Bentley, L. W. Jelinski, and B. W. Kernighan, 1216.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:122.ps \ 1217"\fICHEM \(em A Program for Typesetting Chemical Structure Diagrams, \ 1218Computers and Chemistry\fP" ; 1219. 1220Bell Labs, April 1986. 1221. 1222. 1223.\" -------------------------------------------------------------------- 1224.SS "Manual Pages" 1225.\" -------------------------------------------------------------------- 1226. 1227Due to its complex structure, a full roff system has many man pages, 1228each describing a single aspect of roff. 1229. 1230Unfortunately, there is no general naming scheme for the 1231documentation among the different roff implementations. 1232. 1233.P 1234In 1235.IR groff , 1236the man page 1237.BR groff (@MAN1EXT@) 1238contains a survey of all documentation available in groff. 1239. 1240.P 1241On other systems, you are on your own, but 1242.BR troff (1) 1243might be a good starting point. 1244. 1245. 1246.\" -------------------------------------------------------------------- 1247.SH AUTHORS 1248.\" -------------------------------------------------------------------- 1249. 1250Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 1251. 1252.P 1253This document is distributed under the terms of the FDL (GNU Free 1254Documentation License) version 1.1 or later. 1255. 1256You should have received a copy of the FDL on your system, it is also 1257available on-line at the 1258.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 1259. 1260.P 1261This document is part of 1262.IR groff , 1263the GNU roff distribution. 1264. 1265It was written by 1266.MTO bwarken@mayn.de "Bernd Warken" ; 1267it is maintained by 1268.MTO wl@gnu.org "Werner Lemberg". 1269. 1270. 1271.\" -------------------------------------------------------------------- 1272.\" Emacs setup 1273.\" -------------------------------------------------------------------- 1274. 1275.\" Local Variables: 1276.\" mode: nroff 1277.\" End: 1278