/contrib/groff/man/roff.man

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