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