man/roff.man

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