man/roff.man

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