man/roff.7.man

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