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