man/roff.man

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