roff.man revision 114402
169626Sru.ig 2104862Sruroff.man 369626Sru 4114402SruLast update: 3 Apr 2003 5104862Sru 669626SruThis file is part of groff, the GNU roff type-setting system. 769626Sru 8114402SruCopyright (C) 2000, 2001, 2002, 2003 Free Software Foundation, Inc. 969626Sruwritten by Bernd Warken <bwarken@mayn.de> 10104862Srumaintained by Werner Lemberg <wl@gnu.org> 1169626Sru 1269626SruPermission is granted to copy, distribute and/or modify this document 1369626Sruunder the terms of the GNU Free Documentation License, Version 1.1 or 1469626Sruany later version published by the Free Software Foundation; with the 15104862SruInvariant Sections being this .ig-section and AUTHORS, with no 1669626SruFront-Cover Texts, and with no Back-Cover Texts. 1769626Sru 1869626SruA copy of the Free Documentation License is included as a file called 1969626SruFDL in the main directory of the groff source package. 2069626Sru.. 2169626Sru. 2269626Sru.\" -------------------------------------------------------------------- 2369626Sru.\" Setup 2469626Sru.\" -------------------------------------------------------------------- 2569626Sru. 26104862Sru.mso www.tmac 27104862Sru. 2869626Sru.if n \{\ 2975584Sru. mso tty-char.tmac 3069626Sru. ftr CR R 3169626Sru. ftr CI I 3269626Sru. ftr CB B 3369626Sru.\} 3469626Sru. 35104862Sru.if '\*[.T]'dvi' \{\ 36104862Sru. ftr CB CW 37104862Sru.\} 38104862Sru. 39104862Sru. 40104862Sru.\" -------------------------------------------------------------------- 41104862Sru.\" String definitions 42104862Sru. 43104862Sru.\" Final `\""' comments are used to make Emacs happy, sic \"" 44104862Sru. 45104862Sru.\" The `-' sign for options. 46104862Sru.ie t \{\ 47104862Sru. ds @- \-\" 48104862Sru. ds @-- \-\-\" 49104862Sru.\} 50104862Sru.el \{\ 51104862Sru. ds @- -\" 52104862Sru. ds @-- --\" 53104862Sru.\} 54104862Sru. 55104862Sru.ds Comment \.\[rs]\[dq]\" 56104862Sru.ds Ellipsis \.\|.\|.\&\" 57104862Sru. 58104862Sru. 59104862Sru.\" -------------------------------------------------------------------- 60104862Sru.\" Begin of macro definitions 61104862Sru. 62104862Sru.de c 63104862Sru.\" this is like a comment request when escape mechanism is off 6469626Sru.. 6569626Sru. 66104862Sru.eo 67104862Sru. 68104862Sru.c --------------------------------------------------------------------- 69104862Sru. 70104862Sru.de Text 71104862Sru. nop \)\$* 7269626Sru.. 7369626Sru. 74104862Sru.de CodeSkip 75104862Sru. ie t \ 76104862Sru. sp 0.2v 77104862Sru. el \ 78104862Sru. sp 79104862Sru.. 80104862Sru. 81104862Sru.de Esc 82104862Sru. ds @1 \$1\" 8369626Sru. shift 84104862Sru. Text \f[B]\[rs]\*[@1]\f[]\$* 85104862Sru. rm @1 8669626Sru.. 8769626Sru. 88104862Sru.de QuotedChar 89104862Sru. ds @1 \$1 9069626Sru. shift 91104862Sru. nop `\f[B]\*[@1]\f[]'\$* 92104862Sru. rm @1 9369626Sru.. 9469626Sru. 95104862Sru.c -------------------------------------------------------------------- 96104862Sru. 97104862Sru.c a shell command line 98104862Sru.de ShellCommand 99104862Sru. br 100104862Sru. ad l 101104862Sru. nh 102104862Sru. Text \f[I]sh#\h'1m'\f[]\f[CR]\$*\f[]\&\" 103104862Sru. ft R 104104862Sru. ft P 105104862Sru. hy 106104862Sru. ad 10769626Sru.. 10869626Sru. 109104862Sru.c -------------------------------------------------------------------- 110104862Sru. 111104862Sru.c ShortOpt ([c [punct]]) 112104862Sru.c 113104862Sru.c `-c' somewhere in the text. 114104862Sru.c The second argument is some trailing punctuation. 115104862Sru.c 116104862Sru.de ShortOpt 117104862Sru. ds @1 \$1\" 118104862Sru. shift 119104862Sru. nh 120104862Sru. Text \f[CB]\*[@-]\f[]\f[B]\*[@1]\f[]\/\$* 121104862Sru. hy 122104862Sru. rm @1 12369626Sru.. 12469626Sru. 125104862Sru.de TP+ 126104862Sru. br 127104862Sru. ns 128104862Sru. TP \$1 12975584Sru.. 13075584Sru. 131104862Sru.c -------------------------------------------------------------------- 132104862Sru. 133104862Sru.c Topic 134104862Sru.c 135104862Sru.de Topic 136104862Sru. TP 2m 137104862Sru. Text \[bu] 138104862Sru.. 139104862Sru. 140104862Sru.ec 141104862Sru.\" End of macro definitions 142104862Sru. 143104862Sru. 14469626Sru.\" -------------------------------------------------------------------- 14569626Sru.\" Title 14669626Sru.\" -------------------------------------------------------------------- 147104862Sru. 14869626Sru.TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 14969626Sru.SH NAME 150104862Sruroff \- concepts and history of roff typesetting 151104862Sru. 152104862Sru. 15369626Sru.\" -------------------------------------------------------------------- 15469626Sru.SH DESCRIPTION 15569626Sru.\" -------------------------------------------------------------------- 156104862Sru. 15769626Sru.I roff 15869626Sruis the general name for a set of type-setting programs, known under 15969626Srunames like 16069626Sru.IR troff , 16169626Sru.IR nroff , 162104862Sru.IR ditroff , 16369626Sru.IR groff , 16469626Sruetc. 165104862Sru. 166104862SruA roff type-setting system consists of an extensible text formatting 167104862Srulanguage and a set of programs for printing and converting to other 168104862Srutext formats. 169104862Sru. 170104862SruTraditionally, it is the main text processing system of Unix; every 171104862SruUnix-like operating system still distributes a roff system as a core 172104862Srupackage. 173104862Sru. 174104862Sru.P 17569626SruThe most common roff system today is the free software implementation 176104862Sru.IR "GNU roff", 177104862Sru.BR groff (@MAN1EXT@). 178104862Sru. 179104862SruThe pre-groff implementations are referred to as 180104862Sru.I classical 181104862Sru(dating back as long as 1973). 182104862Sru. 18369626Sru.I groff 184104862Sruimplements the look-and-feel and functionality of its classical 185104862Sruancestors, but has many extensions. 186104862Sru. 187104862SruAs 18869626Sru.I groff 189104862Sruis the only roff system that is available for every (or almost every) 190104862Srucomputer system it is the de-facto roff standard today. 191104862Sru. 192104862Sru.P 193104862SruIn some ancient Unix systems, there was a binary called 194104862Sru.B roff 195104862Sruthat implemented the even more ancient 196104862Sru.B runoff 197104862Sruof the 198104862Sru.I Multics 199104862Sruoperating system, cf. section 200104862Sru.BR HISTORY . 201104862SruThe functionality of this program was very restricted even in 202104862Srucomparison to ancient troff; it is not supported any longer. 203104862Sru. 204104862SruConsequently, in this document, the term 205104862Sru.I roff 206104862Srualways refers to the general meaning of 207104862Sru.IR "roff system" , 208104862Srunot to the ancient roff binary. 209104862Sru. 210104862Sru.P 211104862SruIn spite of its age, roff is in wide use today, for example, the manual 212104862Srupages on UNIX systems 213104862Sru.RI ( man\~pages\/ ), 214104862Srumany software books, system documentation, standards, and corporate 215104862Srudocuments are written in roff. 216104862Sru. 21769626SruThe roff output for text devices is still unmatched, and its graphical 218104862Sruoutput has the same quality as other free type-setting programs and is 219104862Srubetter than some of the commercial systems. 220104862Sru. 221104862Sru.P 222104862SruThe most popular application of roff is the concept of 223104862Sru.I manual pages 224104862Sruor shortly 225104862Sru.IR "man pages" ; 226104862Sruthis is the standard documentation system on many operating systems. 227104862Sru. 228104862Sru.P 229104862SruThis document describes the historical facts around the development 230104862Sruof the 231104862Sru.IR "roff system" ; 232104862Srusome usage aspects common to all roff versions, details on the roff 233104862Srupipeline, which is usually hidden behind front-ends like 234104862Sru.BR groff (@MAN1EXT@); 235104862Sruan general overview of the formatting language; some tips for editing 236104862Sruroff files; and many pointers to further readings. 237104862Sru. 238104862Sru. 23969626Sru.\" -------------------------------------------------------------------- 240104862Sru.SH "HISTORY" 24169626Sru.\" -------------------------------------------------------------------- 242104862Sru. 243104862SruThe 24469626Sru.I roff 245104862Srutext processing system has a very long history, dating back to the 246104862Sru1960s. 247104862Sru. 248104862SruThe roff system itself is intimately connected to the Unix operating 249104862Srusystem, but its roots go back to the earlier operating systems CTSS 250104862Sruand Multics. 251104862Sru. 252104862Sru. 253104862Sru.\" -------------------------------------------------------------------- 254104862Sru.SS "The Predecessor runoff" 255104862Sru.\" -------------------------------------------------------------------- 256104862Sru. 257104862Sru.P 258104862SruThe evolution of 25969626Sru.I roff 260104862Sruis intimately related to the history of the operating systems. 261104862Sru. 262104862SruIts predecessor 263104862Sru.B runoff 264104862Sruwas written by 265104862Sru.I Jerry Saltzer 266104862Sruon the 267104862Sru.I CTSS 268104862Sruoperating system 269104862Sru.RI ( "Compatible Time Sharing System" ) 270104862Sruas early as 1961. 271104862Sru. 272114402SruWhen CTSS was further developed into the operating system 273104862Sru.URL http://\:www.multicians.org "Multics" , 274104862Sruthe famous predecessor of Unix from 1963, 275104862Sru.I runoff 276104862Srubecame the main format for documentation and text processing. 277104862Sru. 278104862SruBoth operating systems could only be run on very expensive computers 279104862Sruat that time, so they were mostly used in research and for official 280104862Sruand military tasks. 281104862Sru. 282104862Sru.P 283104862SruThe possibilities of the 284104862Sru.I runoff 285104862Srulanguage were quite limited as compared to modern roff. 286104862Sru. 287104862SruOnly text output was possible in the 1960s. 288104862Sru. 289104862SruThis could be implemented by a set of requests of length\~2, many of 290104862Sruwhich are still identically used in roff. 291104862Sru. 292104862SruThe language was modelled according to the habits of typesetting in 293104862Sruthe pre-computer age, where lines starting with a dot were used in 294104862Srumanuscripts to denote formatting requests to the person who would 295104862Sruperform the typesetting manually later on. 296104862Sru. 297104862Sru.P 298104862SruThe runoff program was written in the 299104862Sru.I PL/1 300104862Srulanguage first, later on in 301104862Sru.IR BCPL , 302104862Sruthe grandmother of the 303104862Sru.IR C \~\c 304104862Sruprogramming language. 305104862Sru. 306104862SruIn the Multics operating system, the help system was handled by 307104862Srurunoff, similar to roff's task to manage the Unix manual pages. 308104862Sru. 309104862SruThere are still documents written in the runoff language; for examples 310104862Srusee Saltzer's home page, cf. section 311104862Sru.BR "SEE ALSO" . 312104862Sru. 313104862Sru. 31469626Sru.\" -------------------------------------------------------------------- 315104862Sru.SS "The Classical nroff/troff System" 31669626Sru.\" -------------------------------------------------------------------- 317104862Sru. 318104862SruIn the 1970s, the Multics off-spring 319104862Sru.I Unix 320104862Srubecame more and more popular because it could be run on affordable 321104862Srumachines and was easily available for universities at that time. 322104862Sru. 323104862SruAt MIT (the Massachusetts Institute of Technology), there was a need to 324104862Srudrive the Wang 325104862Sru.I Graphic Systems CAT 326104862Srutypesetter, a graphical output device from a PDP-11 computer running 327104862SruUnix. 328104862Sru. 329104862SruAs runoff was too limited for this task it was further developed into 330104862Srua more powerful text formatting system by 331104862Sru.IR "Josef F. Osanna" , 332104862Srua main developer of the Multics operating system and programmer of 333104862Sruseveral runoff ports. 334104862Sru. 335104862Sru.P 336104862SruThe name 337104862Sru.I runoff 338104862Sruwas shortened to 339104862Sru.IR roff . 340104862SruThe greatly enlarged language of Osanna's concept included already all 341104862Sruelements of a full 342104862Sru.IR "roff system" . 343104862Sru. 344104862SruAll modern roff systems try to implement compatibility to this system. 345104862Sru. 346104862SruSo Joe Osanna can be called the father of all roff systems. 347104862Sru. 348104862Sru.P 349104862SruThis first 350104862Sru.I roff system 351104862Sruhad three formatter programs. 352104862Sru. 353104862Sru.TP 354104862Sru.B troff 355104862Sru.RI ( "typesetter roff\/" ) 356104862Srugenerated a graphical output for the 357104862Sru.I CAT 358104862Srutypesetter as its only device. 359104862Sru. 360104862Sru.TP 361104862Sru.B nroff 362104862Sruproduced text output suitable for terminals and line printers. 363104862Sru. 364104862Sru.TP 365104862Sru.B roff 366104862Sruwas the reimplementation of the former runoff program with its limited 367104862Srufeatures; this program was abandoned in later versions. 368104862Sru. 369104862SruToday, the name 37069626Sru.I roff 371104862Sruis used to refer to a troff/\:nroff sytem as a whole. 372104862Sru. 373104862Sru.P 374104862SruOsanna first version was written in the PDP-11 assembly language and 375104862Srureleased in 1973. 376104862Sru. 377104862Sru.I Brian Kernighan 378104862Srujoined the 379104862Sru.I roff 380104862Srudevelopment by rewriting it in the C\~programming language. 381104862Sru. 382104862SruThe C\~version was released in 1975. 383104862Sru. 384104862Sru.P 385104862SruThe syntax of the formatting language of the 386104862Sru.BR nroff / troff 387104862Sruprograms was documented in the famous 388104862Sru.IR "Troff User's Manual [CSTR\~#54]" , 389104862Srufirst published in 1976, with further revisions up to 1992 by Brian 390104862SruKernighan. 391104862Sru. 392104862SruThis document is the specification of the 393104862Sru.IR "classical troff" . 394104862SruAll later 395104862Sru.I roff 396104862Srusystems tried to establish compatibility with this specification. 397104862Sru. 398104862Sru.P 399104862SruAfter Osanna had died in 1977 by a heart-attack at the age of about\~50, 400104862SruKernighan went on with developing troff. 401104862Sru. 402104862SruThe next milestone was to equip troff with a general interface to 403104862Srusupport more devices, the intermediate output format and the 404104862Srupostprocessor system. 405104862Sru. 406104862SruThis completed the structure of a 407104862Sru.I "roff system" 408104862Sruas it is still in use today; see section 409104862Sru.BR "USING ROFF" . 410104862Sru. 411104862SruIn 1979, these novelties were described in the paper 412104862Sru.IR "[CSTR\~#97]" . 413104862SruThis new troff version is the basis for all existing newer troff 414104862Srusystems, including 415104862Sru.IR groff . 416104862Sru. 417104862SruOn some systems, this 418104862Sru.I device independent troff 419104862Srugot a binary of its own, called 420104862Sru.BR ditroff (@MAN7EXT@). 421104862Sru. 422104862SruAll modern 42369626Sru.B troff 424104862Sruprograms already provide the full ditroff capabilities automatically. 425104862Sru. 426104862Sru. 427104862Sru.\" -------------------------------------------------------------------- 428104862Sru.SS "Commercialization" 429104862Sru.\" -------------------------------------------------------------------- 430104862Sru. 431104862SruA major degradation occurred when the easily available Unix\~7 432104862Sruoperating system was commercialized. 433104862Sru. 434104862SruA whole bunch of divergent operating systems emerged, fighting each 435104862Sruother with incompatibilities in their extensions. 436104862Sru. 437104862SruLuckily, the incompatibilities did not fight the original troff. 438104862Sru. 439104862SruAll of the different commercial roff systems made heavy use of 440104862SruOsanna/\:Kernighan's open source code and documentation, but sold them 441104862Sruas \[lq]their\[rq] system \[em] with only minor additions. 442104862Sru. 443104862Sru.P 444104862SruThe source code of both the ancient Unix and classical troff weren't 445104862Sruavailable for two decades. 446104862Sru. 447104862SruFortunately, Caldera bought SCO UNIX in 2001. 448104862Sru. 449104862SruIn the following, Caldera made the ancient source code accessible 450104862Sruon-line for non-commercial use, cf. section 451104862Sru.BR "SEE ALSO" . 452104862Sru. 453104862Sru. 454104862Sru.\" -------------------------------------------------------------------- 455104862Sru.SS "Free roff" 456104862Sru.\" -------------------------------------------------------------------- 457104862Sru. 458104862SruNone of the commercial roff systems could attain the status of a 459104862Srusuccessor for the general roff development. 460104862Sru. 461104862SruEveryone was only interested in their own stuff. 462104862Sru. 463104862SruThis led to a steep downfall of the once excellent 464104862SruUnix operating system during the 1980s. 465104862Sru. 466104862Sru.P 467104862SruAs a counter-measure to the galopping commercialization, AT&T Bell 468104862SruLabs tried to launch a rescue project with their 469104862Sru.I Plan\~9 470104862Sruoperating system. 471104862Sru. 472104862SruIt is freely available for non-commercial use, even the source code, 473104862Srubut has a proprietary license that empedes the free development. 474104862Sru. 475104862SruThis concept is outdated, so Plan\~9 was not accepted as a platform to 476104862Srubundle the main-stream development. 477104862Sru. 478104862Sru.P 479104862SruThe only remedy came from the emerging free operatings systems 480104862Sru(386BSD, GNU/\:Linux, etc.) and software projects during the 1980s and 481104862Sru1990s. 482104862Sru. 483104862SruThese implemented the ancient Unix features and many extensions, such 484104862Sruthat the old experience is not lost. 485104862Sru. 486104862SruIn the 21st century, Unix-like systems are again a major factor in 487104862Srucomputer industry \[em] thanks to free software. 488104862Sru. 489104862Sru.P 490104862SruThe most important free roff project was the GNU port of troff, 491104862Srucreated by James Clark and put under the 492104862Sru.URL http://\:www.gnu.org/\:copyleft "GNU Public License" . 493104862Sru. 494104862SruIt was called 49569626Sru.I groff 496104862Sru.RI ( "GNU roff" ). 497104862SruSee 498104862Sru.BR groff (@MAN1EXT@) 499104862Srufor an overview. 500104862Sru. 501104862Sru.P 502104862SruThe groff system is still actively developed. 503104862Sru. 504104862SruIt is compatible to the classical troff, but many extensions were 505104862Sruadded. 506104862Sru. 507104862SruIt is the first roff system that is available on almost all operating 508104862Srusystems \[em] and it is free. 509104862Sru. 510104862SruThis makes groff the de-facto roff standard today. 511104862Sru. 512104862Sru. 51369626Sru.\" -------------------------------------------------------------------- 514104862Sru.SH "USING ROFF" 51569626Sru.\" -------------------------------------------------------------------- 516104862Sru. 517104862SruMost people won't even notice that they are actually using roff. 518104862Sru. 519104862SruWhen you read a system manual page (man page) roff is working in the 520104862Srubackground. 521104862Sru. 522104862SruRoff documents can be viewed with a native viewer called 523104862Sru.BR xditview (1x), 524104862Srua standard program of the X window distribution, see 525104862Sru.BR X (7x). 526104862Sru. 527104862SruBut using roff explicitly isn't difficult either. 528104862Sru. 529104862Sru.P 530104862SruSome roff implementations provide wrapper programs that make it easy 531104862Sruto use the roff system on the shell command line. 532104862Sru. 533104862SruFor example, the GNU roff implementation 534104862Sru.BR groff (@MAN1EXT@) 535104862Sruprovides command line options to avoid the long command pipes of 536104862Sruclassical troff; a program 537104862Sru.BR grog (@MAN1EXT@) 538104862Srutries to guess from the document which arguments should be used for a 539104862Srurun of groff; people who do not like specifying command line options 540104862Srushould try the 541104862Sru.BR groffer (@MAN1EXT@) 542104862Sruprogram for graphically displaying groff files and man pages. 543104862Sru. 544104862Sru. 545104862Sru.\" -------------------------------------------------------------------- 546104862Sru.SS "The roff Pipe" 547104862Sru.\" -------------------------------------------------------------------- 548104862Sru. 549104862SruEach roff system consists of preprocessors, roff formatter programs, 550104862Sruand a set of device postprocessors. 551104862Sru. 552104862SruThis concept makes heavy use of the 553104862Sru.I piping 554104862Srumechanism, that is, a series of programs is called one after the other, 555104862Sruwhere the output of each program in the queue is taken as the input 556104862Srufor the next program. 557104862Sru. 558104862Sru.CodeSkip 559104862Sru. 560104862Sru.ds @1 "cat \f[I]file\f[P] |\"" 561104862Sru.ds @2 "\*[Ellipsis] | \f[I]preproc\f[P] | \*[Ellipsis] |\"" 562104862Sru.ds @3 "troff \f[I]options\f[P] | \f[I]postproc\f[P]\"" 563104862Sru. 564104862Sru.ShellCommand "\*[@1] \*[@2] \*[@3]" 565104862Sru. 566104862Sru.rm @1 567104862Sru.rm @2 568104862Sru.rm @3 569104862Sru.P 570104862SruThe preprocessors generate roff code that is fed into a roff formatter 571104862Sru(e.g. troff), which in turn generates 572104862Sru.I intermediate output 573104862Sruthat is fed into a device postprocessor program for printing or final 574104862Sruoutput. 575104862Sru. 576104862Sru.P 577104862SruAll of these parts use programming languages of their own; each 578104862Srulanguage is totally unrelated to the other parts. 579104862Sru. 580104862SruMoreover, roff macro packages that were tailored for special purposes 581104862Srucan be included. 582104862Sru. 583104862Sru.P 584104862SruMost roff documents use the macros of some package, intermixed with 585104862Srucode for one or more preprocessors, spiced with some elements from the 586104862Sruplain roff language. 587104862Sru. 588104862SruThe full power of the roff formatting language is seldom needed by 589104862Sruusers; only programmers of macro packages need to know about the gory 590104862Srudetails. 591104862Sru. 592104862Sru. 593104862Sru. 594104862Sru.\" -------------------------------------------------------------------- 595104862Sru.SS "Preprocessors" 596104862Sru.\" -------------------------------------------------------------------- 597104862Sru. 598104862SruA roff preprocessor is any program that generates output that 599104862Srusyntactically obeys the rules of the roff formatting language. 600104862Sru. 601104862SruEach preprocessor defines a language of its own that is translated 602104862Sruinto roff code when run through the preprocessor program. 603104862Sru. 604104862SruParts written in these languages may be included within a roff 605104862Srudocument; they are identified by special roff requests or macros. 606104862Sru. 607104862SruEach document that is enhanced by preprocessor code must be run 608104862Sruthrough all corresponding preprocessors before it is fed into the 609104862Sruactual roff formatter program, for the formatter just ignores all 610104862Srualien code. 611104862Sru. 612104862SruThe preprocessor programs extract and transform only the document 613104862Sruparts that are determined for them. 614104862Sru. 615104862Sru.P 616104862SruThere are a lot of free and commercial roff preprocessors. 617104862Sru. 618104862SruSome of them aren't available on each system, but there is a small 619104862Sruset of preprocessors that are considered as an integral part of each 620104862Sruroff system. 621104862Sru. 622104862SruThe classical preprocessors are 623104862Sru. 624104862Sru 625104862Sru.de @TP 626104862Sru.\" local indent for .TP 627104862Sru.TP \\w'\\f[B]soelim\\f[P]'u+2n 628104862Sru.. 629104862Sru.P 63069626Sru.RS 63169626Sru.PD 0 632104862Sru.@TP 633104862Sru.B tbl 634104862Srufor tables 635104862Sru.@TP 636104862Sru.B eqn 637104862Srufor mathematical formul\[ae] 638104862Sru.@TP 639104862Sru.B pic 640104862Srufor drawing diagrams 641104862Sru.@TP 642104862Sru.B refer 643104862Srufor bibliographic references 644104862Sru.@TP 645104862Sru.B soelim 646104862Srufor including macro files from standard locations 64769626Sru.PD 64869626Sru.RE 64969626Sru. 650104862Sru.P 651104862SruOther known preprocessors that are not available on all systems 652104862Sruinclude 653104862Sru. 654104862Sru.P 655104862Sru.RS 656104862Sru.PD 0 657104862Sru.@TP 658104862Sru.B chem 659104862Srufor drawing chemical formul\[ae]. 660104862Sru.@TP 661104862Sru.B grap 662104862Srufor constructing graphical elements. 663104862Sru.@TP 664104862Sru.B grn 665104862Srufor including 666104862Sru.BR gremlin (1) 667104862Srupictures. 668104862Sru.PD 669104862Sru.RE 670104862Sru. 671104862Sru.rm @TP 672104862Sru. 67369626Sru.\" -------------------------------------------------------------------- 674104862Sru.SS "Formatter Programs" 67569626Sru.\" -------------------------------------------------------------------- 676104862Sru. 677104862SruA 678104862Sru.I roff formatter 679104862Sruis a program that parses documents written in the roff formatting 680104862Srulanguage or uses some of the roff macro packages. 681104862Sru. 682104862SruIt generates 683104862Sru.IR "intermediate output" , 684104862Sruwhich is intended to be fed into a single device postprocessor that 685104862Srumust be specified by a command-line option to the formatter program. 686104862Sru. 687104862SruThe documents must have been run through all necessary preprocessors 688104862Srubefore. 689104862Sru. 690104862Sru.P 691104862SruThe output produced by a roff formatter is represented in yet another 692104862Srulanguage, the 693104862Sru.IR "intermediate output format" 694104862Sruor 695104862Sru.IR "troff output" . 696104862SruThis language was first specified in 697104862Sru.IR "[CSTR\~#97]" ; 698104862Sruits GNU extension is documented in 699104862Sru.BR groff_out (@MAN5EXT@). 700104862Sru. 701104862SruThe intermediate output language is a kind of assembly language 702104862Srucompared to the high-level roff language. 703104862Sru. 704104862SruThe generated intermediate output is optimized for a special device, 705104862Srubut the language is the same for every device. 706104862Sru. 707104862Sru.P 708104862SruThe roff formatter is the heart of the roff system. 709104862Sru. 710104862SruThe traditional roff had two formatters, 711104862Sru.B nroff 712104862Srufor text devices and 713104862Sru.B troff 714104862Srufor graphical devices. 715104862Sru. 716104862Sru.P 717104862SruOften, the name 718104862Sru.I troff 719104862Sruis used as a general term to refer to both formatters. 720104862Sru. 721104862Sru. 722104862Sru.\" -------------------------------------------------------------------- 723104862Sru.SS "Devices and Postprocessors" 724104862Sru.\" -------------------------------------------------------------------- 725104862Sru. 726104862SruDevices are hardware interfaces like printers, text or graphical 727104862Sruterminals, etc., or software interfaces such as a conversion into a 728104862Srudifferent text or graphical format. 729104862Sru. 730104862Sru.P 731104862SruA roff postprocessor is a program that transforms troff output into a 732104862Sruform suitable for a special device. 733104862Sru. 734104862SruThe roff postprocessors are like device drivers for the output target. 735104862Sru. 736104862Sru.P 737104862SruFor each device there is a postprocessor program that fits the device 738104862Sruoptimally. 739104862Sru. 740104862SruThe postprocessor parses the generated intermediate output and 741104862Srugenerates device-specific code that is sent directly to the device. 742104862Sru. 743104862Sru.P 744104862SruThe names of the devices and the postprocessor programs are not fixed 745104862Srubecause they greatly depend on the software and hardware abilities of 746104862Sruthe actual computer. 747104862Sru. 748104862SruFor example, the classical devices mentioned in 749104862Sru.I [CSTR\~#54] 750104862Sruhave greatly changed since the classical times. 751104862Sru. 752104862SruThe old hardware doesn't exist any longer and the old graphical 753104862Sruconversions were quite imprecise when compared to their modern 754104862Srucounterparts. 755104862Sru. 756104862Sru.P 757104862SruFor example, the Postscript device 758104862Sru.I post 759104862Sruin classical troff had a resolution 760104862Sruof 720, while groff's 761104862Sru.I ps 762104862Srudevice has 72000, a refinement of factor 100. 763104862Sru. 764104862Sru.P 765104862SruToday the operating systems provide device drivers for most 766104862Sruprinter-like hardware, so it isn't necessary to write a special 767104862Sruhardware postprocessor for each printer. 768104862Sru. 769104862Sru. 770104862Sru.\" -------------------------------------------------------------------- 771104862Sru.SH "ROFF PROGRAMMING" 772104862Sru.\" -------------------------------------------------------------------- 773104862Sru. 774104862SruDocuments using roff are normal text files decorated by roff 775104862Sruformatting elements. 776104862Sru. 777104862SruThe roff formatting language is quite powerful; it is almost a full 778104862Sruprogramming language and provides elements to enlarge the language. 779104862Sru. 780104862SruWith these, it became possible to develop macro packages that are 781104862Srutailored for special applications. 782104862Sru. 783104862SruSuch macro packages are much handier than plain roff. 784104862Sru. 785104862SruSo most people will choose a macro package without worrying about the 786104862Sruinternals of the roff language. 787104862Sru. 788104862Sru. 789104862Sru.\" -------------------------------------------------------------------- 790104862Sru.SS "Macro Packages" 791104862Sru.\" -------------------------------------------------------------------- 792104862Sru. 79369626SruMacro packages are collections of macros that are suitable to format a 79469626Sruspecial kind of documents in a convenient way. 795104862Sru. 79669626SruThis greatly eases the usage of roff. 797104862Sru. 79869626SruThe macro definitions of a package are kept in a file called 79975584Sru.IB name .tmac 800104862Sru(classically 80175584Sru.BI tmac. name\c 802104862Sru). 803104862Sru. 804104862SruAll tmac files are stored in one or more directories at standardized 80569626Srupositions. 806104862Sru. 807104862SruDetails on the naming of macro packages and their placement is found 808104862Sruin 80975584Sru.BR groff_tmac (@MAN5EXT@). 810104862Sru. 811104862Sru.P 812104862SruA macro package that is to be used in a document can be announced to 813104862Sruthe formatter by the command line option 814104862Sru.ShortOpt m , 815104862Srusee 816104862Sru.BR troff (@MAN1EXT@), 817104862Sruor it can be specified within a document using the file inclusion 818104862Srurequests of the roff language, see 819104862Sru.BR groff (@MAN7EXT@). 820104862Sru. 821104862Sru.P 82269626SruFamous classical macro packages are 823104862Sru.I man 824104862Srufor traditional man pages, 82569626Sru.I mdoc 826104862Srufor BSD-style manual pages; 827104862Sruthe macro sets for books, articles, and letters are 828104862Sru.I me 829104862Sru(probably from the first name of its creator 830104862Sru.I Eric 831104862SruAllman), 832104862Sru.I ms 833104862Sru(from 834104862Sru.IR "Manuscript Macros\/" ), 83569626Sruand 83669626Sru.I mm 837104862Sru(from 838104862Sru.IR "Memorandum Macros\/" ). 839104862Sru. 840104862Sru. 84169626Sru.\" -------------------------------------------------------------------- 842104862Sru.SS "The roff Formatting Language" 843104862Sru.\" -------------------------------------------------------------------- 844104862Sru. 845104862SruThe classical roff formatting language is documented in the 846104862Sru.I Troff User's Manual 847104862Sru.IR "[CSTR\~#54]" . 848104862Sru. 849104862SruThe roff language is a full programming language providing requests, 850104862Srudefinition of macros, escape sequences, string variables, number or 851104862Srusize registers, and flow controls. 852104862Sru. 853104862Sru.P 854104862Sru.I Requests 855104862Sruare the predefined basic formatting commands similar to the commands 856104862Sruat the shell prompt. 857104862Sru. 858104862SruThe user can define request-like elements using predefined roff 859104862Sruelements. 860104862Sru. 861104862SruThese are then called 862104862Sru.IR macros . 863104862Sru. 864104862SruA document writer will not note any difference in usage for requests 865104862Sruor macros; both are written on a line on their own starting with a dot. 866104862Sru. 867104862Sru.P 868104862Sru.I Escape sequences 869104862Sruare roff elements starting with a backslash 870104862Sru.QuotedChar \[rs] . 871104862SruThey can be inserted anywhere, also in the midst of text in a line. 872104862Sru. 873104862SruThey are used to implement various features, including the insertion of 874104862Srunon-ASCII characters with 875104862Sru.Esc ( , 876104862Srufont changes with 877104862Sru.Esc f , 878104862Sruin-line comments with 879104862Sru.Esc \[dq] , 880104862Sruthe escaping of special control characters like 881104862Sru.Esc \[rs] , 882104862Sruand many other features. 883104862Sru. 884104862Sru.P 885104862Sru.I Strings 886104862Sruare variables that can store a string. 887104862Sru. 888104862SruA string is stored by the 889104862Sru.B .ds 890104862Srurequest. 891104862Sru. 892104862SruThe stored string can be retrieved later by the 893104862Sru.B \[rs]* 894104862Sruescape sequence. 895104862Sru. 896104862Sru.P 897104862Sru.I Registers 898104862Srustore numbers and sizes. 899104862Sru. 900104862SruA register can be set with the request 901104862Sru.B .nr 902104862Sruand its value can be retrieved by the escape sequence 903104862Sru.BR "\[rs]n" . 904104862Sru. 905104862Sru. 906104862Sru.\" -------------------------------------------------------------------- 90769626Sru.SH "FILE NAME EXTENSIONS" 90869626Sru.\" -------------------------------------------------------------------- 909104862Sru. 910104862SruManual pages (man pages) take the section number as a file name 91169626Sruextension, e.g., the filename for this document is 91269626Sru.IR roff.7 , 913104862Srui.e., it is kept in section\~7 914104862Sruof the man pages. 915104862Sru. 916104862Sru.P 91769626SruThe classical macro packages take the package name as an extension, e.g. 91869626Sru.IB file. me 91969626Srufor a document using the 92069626Sru.I me 92169626Srumacro package, 92269626Sru.IB file. mm 92369626Srufor 92469626Sru.IR mm , 92569626Sru.IB file. ms 92669626Srufor 92769626Sru.IR ms , 92869626Sru.IB file. pic 92969626Srufor 93069626Sru.I pic 93169626Srufiles, 93269626Sruetc. 933104862Sru. 934104862Sru.P 93569626SruBut there is no general naming scheme for roff documents, though 936104862Sru.IB file. tr 937104862Srufor 938104862Sru.I troff file 939104862Sruis seen now and then. 940104862Sru. 941104862SruMaybe there should be a standardization for the filename extensions of 942104862Sruroff files. 943104862Sru. 944104862Sru.P 94569626SruFile name extensions can be very handy in conjunction with the 94669626Sru.BR less (1) 94769626Srupager. 948104862Sru. 949104862SruIt provides the possibility to feed all input into a command-line pipe 950104862Sruthat is specified in the shell environment variable 951104862Sru.BR LESSOPEN . 952104862SruThis process is not well documented, so here an example: 953104862Sru. 954104862Sru.CodeSkip 955104862Sru.ShellCommand LESSOPEN='|lesspipe %s' 956104862Sru.CodeSkip 957104862Sru. 95869626Sruwhere 95969626Sru.B lesspipe 96069626Sruis either a system supplied command or a shell script of your own. 961104862Sru. 962104862Sru. 96369626Sru.\" -------------------------------------------------------------------- 964104862Sru.SH "EDITING ROFF" 96569626Sru.\" -------------------------------------------------------------------- 966104862Sru. 967104862SruThe best program for editing a roff document is Emacs (or Xemacs), see 968104862Sru.BR emacs (1). 969104862SruIt provides an 970104862Sru.I nroff 971104862Srumode that is suitable for all kinds of roff dialects. 972104862Sru. 973104862SruThis mode can be activated by the following methods. 974104862Sru. 975104862Sru.P 976104862SruWhen editing a file within Emacs the mode can be changed by typing 977104862Sru.RI ` "M-x nroff-mode" ', 978104862Sruwhere 979104862Sru.B M-x 980104862Srumeans to hold down the 981104862Sru.B Meta 982104862Srukey (or 983104862Sru.BR Alt ) 984104862Sruand hitting the 985104862Sru.BR x\~ key 986104862Sruat the same time. 987104862Sru. 988104862Sru.P 989104862SruBut it is also possible to have the mode automatically selected when 990104862Sruthe file is loaded into the editor. 991104862Sru. 992104862Sru.Topic 993104862SruThe most general method is to include the following 3 comment lines at 994104862Sruthe end of the file. 995104862Sru. 996104862Sru.CodeSkip 997104862Sru.nf 998104862Sru.B \*[Comment] Local Variables: 999104862Sru.B \*[Comment] mode: nroff 1000104862Sru.B \*[Comment] End: 1001104862Sru.fi 1002104862Sru. 1003104862Sru.Topic 1004104862SruThere is a set of file name extensions, e.g. the man pages that 1005104862Srutrigger the automatic activation of the nroff mode. 1006104862Sru. 1007104862Sru.Topic 1008104862SruTheoretically, it is possible to write the sequence 1009104862Sru.CodeSkip 1010104862Sru.B \*[Comment] \%-*-\ nroff\ -*- 1011104862Sru.CodeSkip 1012104862Sruas the first line of a file to have it started in nroff mode when 1013104862Sruloaded. 1014104862Sru. 1015104862SruUnfortunately, some applications such as the 1016104862Sru.B man 1017104862Sruprogram are confused by this; so this is deprecated. 1018104862Sru. 1019104862Sru.P 1020104862SruAll roff formatters provide automated line breaks and horizontal and 1021104862Sruvertical spacing. 1022104862Sru. 1023104862SruIn order to not disturb this, the following tips can be helpful. 1024104862Sru. 1025104862Sru.Topic 1026104862SruNever include empty or blank lines in a roff document. 1027104862Sru. 1028104862SruInstead, use the empty request (a line consisting of a dot only) or a 1029104862Sruline comment 1030104862Sru.B \*[Comment] 1031104862Sruif a structuring element is needed. 1032104862Sru. 1033104862Sru.Topic 1034104862SruNever start a line with whitespace because this can lead to 1035104862Sruunexpected behavior. 1036104862Sru. 1037104862SruIndented paragraphs can be constructed in a controlled way by roff 1038104862Srurequests. 1039104862Sru. 1040104862Sru.Topic 1041104862SruStart each sentence on a line of its own, for the spacing after a dot 1042104862Sruis handled differently depending on whether it terminates an 1043104862Sruabbreviation or a sentence. 1044104862Sru. 1045104862SruTo distinguish both cases, do a line break after each sentence. 1046104862Sru. 1047104862Sru.Topic 1048104862SruTo additionally use the auto-fill mode in Emacs, it is best to insert 1049104862Sruan empty roff request (a line consisting of a dot only) after each 1050104862Srusentence. 1051104862Sru. 1052104862Sru.P 1053104862SruThe following example shows how optimal roff editing could look. 1054104862Sru. 1055104862Sru.IP 1056104862Sru.nf 1057104862SruThis is an example for a roff document. 1058104862Sru.Text . 1059104862SruThis is the next sentence in the same paragraph. 1060104862Sru.Text . 1061104862SruThis is a longer sentence stretching over several 1062104862Srulines; abbreviations like `cf.' are easily 1063104862Sruidentified because the dot is not followed by a 1064104862Sruline break. 1065104862Sru.Text . 1066104862SruIn the output, this will still go to the same 1067104862Sruparagraph. 1068104862Sru.fi 1069104862Sru. 1070104862Sru.P 1071104862SruBesides Emacs, some other editors provide nroff style files too, e.g.\& 1072104862Sru.BR vim (1), 1073104862Sruan extension of the 1074104862Sru.BR vi (1) 1075104862Sruprogram. 1076104862Sru. 1077104862Sru. 107869626Sru.\" -------------------------------------------------------------------- 1079104862Sru.SH BUGS 108069626Sru.\" -------------------------------------------------------------------- 1081104862Sru. 1082104862Sru.I UNIX\[rg] 1083104862Sruis a registered trademark of the Open Group. 1084104862Sru. 1085104862SruBut things have improved considerably after Caldera had bought SCO 1086104862SruUNIX in 2001. 1087104862Sru. 1088104862Sru. 1089104862Sru.\" -------------------------------------------------------------------- 1090104862Sru.SH "SEE ALSO" 1091104862Sru.\" -------------------------------------------------------------------- 1092104862Sru. 1093104862SruThere is a lot of documentation on roff. 1094104862Sru. 1095104862SruThe original papers on classical troff are still available, and all 1096104862Sruaspects of groff are documented in great detail. 1097104862Sru. 1098104862Sru. 1099104862Sru.\" -------------------------------------------------------------------- 1100104862Sru.SS "Internet sites" 1101104862Sru.\" -------------------------------------------------------------------- 1102104862Sru. 110369626Sru.TP 1104104862Srutroff.org 1105104862Sru.URL http://\:www.troff.org "The historical troff site" 1106104862Sruprovides an overview and pointers to all historical aspects of roff. 1107104862Sru. 110869626Sru.TP 1109104862SruMultics 1110104862Sru.URL http://\:www.multicians.org "The Multics site" 1111104862Srucontains a lot of information on the MIT projects, CTSS, Multics, 1112104862Sruearly Unix, including 1113104862Sru.IR runoff ; 1114104862Sruespecially useful are a glossary and the many links to ancient 1115104862Srudocuments. 1116104862Sru. 111769626Sru.TP 1118104862SruUnix Archive 1119104862Sru.URL http://\:www.tuhs.org/\:Archive/ \ 1120104862Sru "The Ancient Unixes Archive" 1121104862Sru. 1122104862Sruprovides the source code and some binaries of the ancient Unixes 1123104862Sru(including the source code of troff and its documentation) that were 1124104862Srumade public by Caldera since 2001, e.g. of the famous Unix version\~7 1125104862Srufor PDP-11 at the 1126104862Sru.URL http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7 \ 1127104862Sru "Unix V7 site" . 1128104862Sru. 1129104862Sru.TP 1130104862SruDevelopers at AT&T Bell Labs 1131104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:index.html \ 1132104862Sru "Bell Labs Computing and Mathematical Sciences Research" 1133104862Sru. 1134104862Sruprovides a search facility for tracking information on the early 1135104862Srudevelopers. 1136104862Sru. 1137104862Sru.TP 1138104862SruPlan 9 1139104862Sru.URL http://\:plan9.bell-labs.com "The Plan\~9 operating system" 1140104862Sru. 1141104862Sruby AT&T Bell Labs. 1142104862Sru. 1143104862Sru.TP 1144104862Srurunoff 1145104862Sru.URL http://web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html \ 1146104862Sru"Jerry Saltzer's home page" 1147104862Sru. 1148104862Srustores some documents using the ancient runoff formatting language. 1149104862Sru. 1150104862Sru.TP 1151104862SruCSTR Papers 1152104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html \ 1153104862Sru "The Bell Labs CSTR site" 1154104862Sru. 1155104862Srustores the original troff manuals (CSTR #54, #97, #114, #116, #122) 1156104862Sruand famous historical documents on programming. 1157104862Sru. 1158104862Sru.TP 1159104862SruGNU roff 1160104862Sru.URL http://\:www.gnu.org/\:software/\:groff "The groff web site" 1161104862Sruprovides the free roff implementation groff, the actual standard roff. 1162104862Sru. 1163104862Sru. 116469626Sru.\" -------------------------------------------------------------------- 1165104862Sru.SS "Historical roff Documentation" 116669626Sru.\" -------------------------------------------------------------------- 1167104862Sru. 1168104862SruMany classical 1169104862Sru.troff 1170104862Srudocuments are still available on-line. 1171104862Sru. 1172104862SruThe two main manuals of the troff language are 1173104862Sru. 117469626Sru.TP 1175104862Sru[CSTR\~#54] 1176104862SruJ. F. Osanna, 1177104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \ 1178104862Sru "\fINroff/\:Troff User's Manual\fP" ; 1179104862Sru. 1180104862SruBell Labs, 1976; revised by Brian Kernighan, 1992. 1181104862Sru 1182104862Sru. 118369626Sru.TP 1184104862Sru[CSTR\~#97] 1185104862SruBrian Kernighan, 1186104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps \ 1187104862Sru "\fIA Typesetter-independent TROFF\fP" , 1188104862Sru. 1189104862SruBell Labs, 1981, revised March 1982. 1190104862Sru. 1191104862Sru.P 1192104862SruThe "little language" roff papers are 1193104862Sru. 119469626Sru.TP 1195104862Sru[CSTR\~#114] 1196104862SruJon L. Bentley and Brian W. Kernighan, 1197104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:114.ps \ 1198104862Sru "\fIGRAP \(em A Language for Typesetting Graphs\fP" ; 1199104862Sru. 1200104862SruBell Labs, August 1984. 1201104862Sru. 120269626Sru.TP 1203104862Sru[CSTR\~#116] 1204104862SruBrian W. Kernighan, 1205104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:116.ps \ 1206104862Sru "\fIPIC -- A Graphics Language for Typesetting\fP" ; 1207104862Sru. 1208104862SruBell Labs, December 1984. 1209104862Sru. 1210104862Sru.TP 1211104862Sru[CSTR\~#122] 1212104862SruJ. L. Bentley, L. W. Jelinski, and B. W. Kernighan, 1213104862Sru.URL http://\:cm.bell-labs.com/\:cm/\:cs/\:122.ps \ 1214104862Sru"\fICHEM \(em A Program for Typesetting Chemical Structure Diagrams, \ 1215104862SruComputers and Chemistry\fP" ; 1216104862Sru. 1217104862SruBell Labs, April 1986. 1218104862Sru. 1219104862Sru. 122069626Sru.\" -------------------------------------------------------------------- 1221104862Sru.SS "Manual Pages" 122269626Sru.\" -------------------------------------------------------------------- 1223104862Sru. 1224104862SruDue to its complex structure, a full roff system has many man pages, 1225104862Srueach describing a single aspect of roff. 1226104862Sru. 1227104862SruUnfortunately, there is no general naming scheme for the 1228104862Srudocumentation among the different roff implementations. 1229104862Sru. 1230104862Sru.P 1231104862SruIn 1232104862Sru.IR groff , 1233104862Sruthe man page 1234104862Sru.BR groff (@MAN1EXT@) 1235104862Srucontains a survey of all documentation available in groff. 1236104862Sru. 1237104862Sru.P 1238104862SruOn other systems, you are on your own, but 1239104862Sru.BR troff (1) 1240104862Srumight be a good starting point. 1241104862Sru. 1242104862Sru. 124369626Sru.\" -------------------------------------------------------------------- 1244104862Sru.SH AUTHORS 124569626Sru.\" -------------------------------------------------------------------- 1246104862Sru. 1247104862SruCopyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 1248104862Sru. 1249104862Sru.P 1250104862SruThis document is distributed under the terms of the FDL (GNU Free 1251104862SruDocumentation License) version 1.1 or later. 1252104862Sru. 1253104862SruYou should have received a copy of the FDL on your system, it is also 1254104862Sruavailable on-line at the 1255104862Sru.URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" . 1256104862Sru. 1257104862Sru.P 1258104862SruThis document is part of 1259104862Sru.IR groff , 1260104862Sruthe GNU roff distribution. 1261104862Sru. 1262104862SruIt was written by 1263104862Sru.MTO bwarken@mayn.de "Bernd Warken" ; 1264104862Sruit is maintained by 1265104862Sru.MTO wl@gnu.org "Werner Lemberg". 1266104862Sru. 1267104862Sru. 126869626Sru.\" -------------------------------------------------------------------- 1269104862Sru.\" Emacs setup 127069626Sru.\" -------------------------------------------------------------------- 127179543Sru. 127279543Sru.\" Local Variables: 127379543Sru.\" mode: nroff 127479543Sru.\" End: 1275