man/roff.man

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