man/roff.7.in

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