man/roff.man

   1 .ig
   2 roff.man
   3
   4 Last update: 08 Jan 2002
   5
   6 This file is part of groff, the GNU roff type-setting system.
   7
   8 Copyright (C) 2000, 2001, 2002 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 .\" Setup
  24 .\" --------------------------------------------------------------------
  25 .
  26 .mso www.tmac
  27 .
  28 .if n \{\
  29 .  mso tty-char.tmac
  30 .  ftr CR R
  31 .  ftr CI I
  32 .  ftr CB B
  33 .\}
  34 .
  35 .if '\*[.T]'dvi' \{\
  36 .  ftr CB CW
  37 .\}
  38 .
  39 .
  40 .\" --------------------------------------------------------------------
  41 .\" Begin of macro definitions
  42 .eo
  43 .
  44 .de Text
  45 .  nop \)\$*
  46 ..
  47 .de ellipsis
  48 .  Text .\|.\|.\&\"
  49 ..
  50 .de esc
  51 .  ds @1 \$1\"
  52 .  shift
  53 .  Text \f[B]\[rs]\*[@1]\f[]\$*
  54 .  rm @1
  55 ..
  56 .de option
  57 .  ds @1 \$1\"
  58 .  shift 1
  59 .  Text \f[B]\*[@1]\f[]\$*
  60 .  rm @1
  61 ..
  62 .de quoted_char
  63 .  ds @1 \$1
  64 .  shift
  65 .  nop `\fB\*[@1]\fP'\$*
  66 .  rm @1
  67 ..
  68 .de ShellCommand
  69 .  br
  70 .  IR "shell#" "\h'1m'\f[CB]\$*\f[]\/"
  71 ..
  72 .de TP+
  73 .  br
  74 .  ns
  75 .  TP \$1
  76 ..
  77 .de Topic
  78 .  TP 2m
  79 .  Text \[bu]
  80 ..
  81 .ds comment \[rs]"
  82 .ec
  83 .\" End of macro definitions
  84 .
  85 .
  86 .\" --------------------------------------------------------------------
  87 .\" Title
  88 .\" --------------------------------------------------------------------
  89 .
  90 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  91 .SH NAME
  92 roff \- introduction and overview of roff typesetting
  93 .
  94 .
  95 .\" --------------------------------------------------------------------
  96 .SH DESCRIPTION
  97 .\" --------------------------------------------------------------------
  98 .
  99 .I roff
 100 is the general name for a set of type-setting programs, known under
 101 names like
 102 .IR troff ,
 103 .IR nroff ,
 104 .IR ditroff ,
 105 .IR groff ,
 106 etc.
 107 .
 108 A roff type-setting system consists of an extensible text formatting
 109 language and a set of programs for printing and converting to other
 110 text formats.
 111 .
 112 Traditionally, it is the main text processing system of Unix; every
 113 Unix-like operating system still distributes a roff system as a core
 114 package.
 115 .
 116 .P
 117 The most common roff system today is the free software implementation
 118 GNU roff,
 119 .IR groff .
 120 .
 121 The pre-groff implementations are referred to as
 122 .I classical
 123 (dating back as long as 1973).
 124 .
 125 .I groff
 126 implements the look-and-feel and functionality of its classical
 127 ancestors, but has many extensions.
 128 .
 129 As
 130 .I groff
 131 is the only roff system that is available for every (or almost every)
 132 computer system it is the de-facto roff standard today.
 133 .
 134 .P
 135 In spite of its age, roff is in wide use today, e.g., the manual pages
 136 on UNIX systems
 137 .RI ( man\~pages\/ ),
 138 many software books, system documentation, standards, and corporate
 139 documents are written in roff.
 140 .
 141 The roff output for text devices is still unmatched, and its graphical
 142 output has the same quality as other free type-setting programs and is
 143 better than some of the commercial systems.
 144 .
 145 .P
 146 This document gives only an overview and provides pointers to further
 147 documentation, cf. section
 148 .BR "SEE ALSO" .
 149 .
 150 .
 151 .\" --------------------------------------------------------------------
 152 .SH "HISTORY"
 153 .\" --------------------------------------------------------------------
 154 .
 155 The
 156 .I roff
 157 text processing system has a very long history, dating back to the
 158 1960s.
 159 .
 160 The roff system itself is intimately connected to the Unix operating
 161 system, but roff had roots in the earlier operating systems CTSS and
 162 Multics.
 163 .
 164 .P
 165 .I roff
 166 evolved from its predecessor
 167 .I runoff
 168 written by
 169 .I Jerry Saltzer
 170 on the
 171 .I CTSS
 172 operating system
 173 .RI ( "Compatible Time Sharing System" )
 174 in 1961, which was further developed into the famous Unix predecessor
 175 operating system
 176 .URL http://\:www.multicians.org "Multics" ,
 177 available from 1963.
 178 .
 179 Both operating systems could only be run on very expensive computers
 180 at that time, so they were mostly used in research and for official
 181 and military tasks.
 182 .
 183 .P
 184 The possibilities of the
 185 .I runoff
 186 program were quite limited as compared to roff.
 187 .
 188 Only text output was needed in the 1960s.
 189 .
 190 This could be implemented by a set of requests of length\~2, many of
 191 which are still identically used in roff.
 192 .
 193 The runoff program was first written in
 194 .IR PL/1 ,
 195 later on in
 196 .IR BCPL ,
 197 the grandmother of the
 198 .I C
 199 programming language.
 200 .
 201 In the Multics operating system, the help system was handled by
 202 runoff, similar to roff's task on the Unix manual pages.
 203 .
 204 There are still documents written in the runoff language; for examples
 205 see Saltzer's homepage (follow the links on the Multics web page).
 206 .
 207 .P
 208 In the 1970s, the Multics off-spring
 209 .I Unix
 210 became more and more popular because it could be run on affordable
 211 machines and was free at that time.
 212 .
 213 At MIT (the Massachusetts Institute of Technology), there was a need to
 214 drive the Wang
 215 .I Graphic Systems CAT
 216 typesetter, a graphical output device from a PDP-11 computer running
 217 Unix.
 218 .
 219 As runoff was too limited for this task it was further developed into
 220 a more powerful text formatting system by
 221 .IR "Josef F. Osanna" ,
 222 a main developer of Multics and runoff ports.
 223 .
 224 This was called
 225 .IR roff ,
 226 a short form for
 227 .IR runoff .
 228 .
 229 The first version was written in the PDP-11 assembly language and
 230 released in 1973.
 231 .
 232 .I Brian Kernighan
 233 joined the roff development by rewriting it in the C programming
 234 language.
 235 .
 236 The C version was released in 1975.
 237 .
 238 .P
 239 This first roff system could produce output for only 2\~devices:
 240 .B troff
 241 .RI ( "typesetter roff\/" )
 242 had a graphical output for the
 243 .I CAT
 244 typesetter as its only device, while
 245 .B nroff
 246 produced text output suitable for terminals or line printers.
 247 .
 248 .P
 249 The syntax of the formatting language of the
 250 .BR nroff / troff
 251 programs was documented in the famous
 252 .IR "Troff User's Manual [CSTR\~#54]" ,
 253 first published in 1976, with further revisions up to 1992 by Brian
 254 Kernighan.
 255 .
 256 The system described therein is referred to as the
 257 .IR "classical troff" .
 258 All later
 259 .I roff
 260 systems tried to establish compatibility with this specification.
 261 .
 262 .P
 263 After Osanna had died in 1977 by a heart-attack at the age of about\~50
 264 Kernighan went on with developping troff.
 265 .
 266 The next milestone was to equip troff with a general interface to
 267 support more devices, the intermediate output format and the
 268 postprocessor system.
 269 .
 270 This completed the structure of a
 271 .I "roff system"
 272 as it is still in use today; see section
 273 .IR "USING ROFF" .
 274 .
 275 In 1979, these novelties were described in the paper
 276 .IR "[CSTR\~#97]" .
 277 This new troff version is the basis for all existing newer troff
 278 systems, including
 279 .IR groff .
 280 .
 281 .P
 282 A major catastrophy occurred when the freely available Unix\~7
 283 operating system was commercialized.
 284 .
 285 A whole bunch of divergent operating systems emerged, fighting each
 286 other with incompatibilities, finally causing many different roff
 287 systems.
 288 .
 289 All of them used Osanna/Kernighan's free source code and his troff
 290 papers as their main documentation, but sold them together with
 291 "their" system \[em] with only minor modifications.
 292 .
 293 Though most commercial roff systems added incompatible extensions, all
 294 of them try to achieve compatibility with the original, free troff.
 295 .
 296 Some of these roff implementations were renamed into
 297 .BR ditroff (@MAN1EXT@),
 298 originating from
 299 .IR "device independent troff" .
 300 This name is an exaggeration.
 301 .
 302 .P
 303 As a counter-measure to the galopping commercialization, more and more
 304 free software projects emerged during the 1980s and 1990s.
 305 .
 306 The most important roff project was the GNU port of troff, created by
 307 James Clark.
 308 .
 309 It was called
 310 .I groff
 311 .RI ( "GNU roff" ).
 312 .
 313 The groff system is actively developed.
 314 .
 315 Though being compatible with the classical troff, many extensions were
 316 added that greatly simplify roff programming.
 317 .
 318 It is the first roff system that is available on almost all operating
 319 systems \[em] and it is free.
 320 .
 321 This makes groff the de-facto roff standard today.
 322 .
 323 .
 324 .\" --------------------------------------------------------------------
 325 .SH "USING ROFF"
 326 .\" --------------------------------------------------------------------
 327 .
 328 Most people won't even notice that they are actually using roff.
 329 .
 330 When you read a system manual page (man page) roff is working in the
 331 background.
 332 .
 333 Arbitrary roff documents can be viewed with a native roff viewer
 334 called
 335 .BR xditview (1x),
 336 a standard program of the
 337 .BR X (7x)
 338 window distribution.
 339 .
 340 But using roff explicitly isn't difficult either.
 341 .
 342 .P
 343 Some roff implementations provide wrapper programs that make it easy
 344 to use the roff system on the shell command line.
 345 .
 346 For example, the GNU roff implementation
 347 .BR groff (@MAN1EXT@)
 348 provides command line options to avoid the long command pipes of
 349 classical troff; a program
 350 .BR grog (@MAN1EXT@)
 351 tries to guess from the document which arguments should be used for a
 352 run of groff; people who do not like specifying command line options
 353 should try the
 354 .BR groffer (@MAN1EXT@)
 355 program for graphically displaying groff files and man pages.
 356 .
 357 .
 358 .\" --------------------------------------------------------------------
 359 .SS "The roff Pipe"
 360 .\" --------------------------------------------------------------------
 361 .
 362 Each roff system consists of preprocessors, roff formatter programs,
 363 and a set of device postprocessors.
 364 .
 365 This concept makes heavily use of the
 366 .I piping
 367 mechanism, i.e. a series of programs is called one after the other,
 368 where the output of each program in the queue is taken as the input
 369 for the next program.
 370 .
 371 .P
 372 .B cat
 373 .I file
 374 .B |
 375 .ellipsis
 376 .B | preproc |
 377 .ellipsis
 378 .B | troff
 379 .I options
 380 .B | postproc
 381 .
 382 .P
 383 The preprocessors generate roff code that is fed into a roff formatter
 384 (e.g. troff), which in turn generates
 385 .I intermediate output
 386 that is fed into a device postprocessor program for printing or final
 387 output.
 388 .
 389 .P
 390 All of these parts use programming languages of their own; each
 391 language is totally unrelated to the other parts.
 392 .
 393 Moreover, roff macro packages can be inluded.
 394 .
 395 So most roff documents use the macros of some package, intermixed with
 396 code for one or more preprocessors, but do not need many elements from
 397 the plain roff language.
 398 .
 399 .
 400 .\" --------------------------------------------------------------------
 401 .SS "Preprocessors"
 402 .\" --------------------------------------------------------------------
 403 .
 404 A roff preprocessor is any program that generates output that
 405 syntactically obeys the rules of the roff formatting language.
 406 .
 407 Each preprocessor defines a language of its own that is translated
 408 into roff code when run through the preprocessor program.
 409 .
 410 Parts written in these languages may be included within a roff
 411 document; they are identified by special roff requests or macros.
 412 .
 413 Each document that is enhanced by preprocessor code must be run
 414 through all corresponding preprocessors before it is fed into the
 415 actual roff formatter program; for the formatter just ignores all
 416 alien code.
 417 .
 418 The preprocessor programs extract and transform only the document
 419 parts that are determined for them.
 420 .
 421 .P
 422 There are a lot of free and commercial roff preprocessors.
 423 .
 424 Some of these aren't available on each system, but there is a small
 425 set of preprocessors that are considered as an integral part of each
 426 roff system.
 427 .
 428 The classical preprocessors are
 429 .
 430 .P
 431 .RS
 432 .PD 0
 433 .TP
 434 .B tbl
 435 for tables
 436 .TP
 437 .B eqn
 438 for mathematical formul\[ae]
 439 .TP
 440 .B pic
 441 for drawing diagrams
 442 .TP
 443 .B refer
 444 for bibliographic references
 445 .TP
 446 .B soelim
 447 for including macro files from standard locations
 448 .PD
 449 .RE
 450 .
 451 .P
 452 Other known preprocessors that are not available on all systems
 453 include
 454 .
 455 .P
 456 .RS
 457 .PD 0
 458 .TP
 459 .B chem
 460 for drawing chemical formul\[ae].
 461 .TP
 462 .B grap
 463 for constructing graphical elements.
 464 .TP
 465 .B grn
 466 for including
 467 .BR gremlin (1)
 468 pictures.
 469 .PD
 470 .RE
 471 .
 472 .
 473 .\" --------------------------------------------------------------------
 474 .SS "Formatter Programs"
 475 .\" --------------------------------------------------------------------
 476 .
 477 A
 478 .I roff formatter
 479 is a program that parses documents written in the roff formatting
 480 language or uses some of the roff macro packages.
 481 .
 482 It generates
 483 .IR "intermediate output" ,
 484 which is intended to be fed into a single device postprocessor that
 485 must be specified by a command-line option to the formatter program.
 486 .
 487 The documents must have been run through all necessary preprocessors
 488 before.
 489 .
 490 .P
 491 The output produced by a roff formatter is represented in yet another
 492 language, the
 493 .IR "intermediate output format"
 494 or
 495 .IR "troff output" .
 496 This language was first specified in
 497 .IR "[CSTR\~#97]" ;
 498 its GNU extension is documented in
 499 .BR groff_out (@MAN5EXT@).
 500 .
 501 The intermediate output language is a kind of assembly language
 502 compared to the high-level roff language.
 503 .
 504 The generated intermediate output is optimized for a special device,
 505 but the language is the same for every device.
 506 .
 507 .P
 508 The roff formatter is the heart of the roff system.
 509 .
 510 The traditional roff had two formatters,
 511 .B nroff
 512 for text devices and
 513 .B troff
 514 for graphical devices.
 515 .
 516 .P
 517 Often, the name
 518 .I troff
 519 is used as a general term to refer to both formatters.
 520 .
 521 .
 522 .\" --------------------------------------------------------------------
 523 .SS "Devices and Postprocessors"
 524 .\" --------------------------------------------------------------------
 525 .
 526 Devices are hardware interfaces like printers, text or graphical
 527 terminals, etc., or software interfaces such as a conversion into a
 528 different text or graphical format.
 529 .
 530 .P
 531 A roff postprocessor is a program that transforms troff output into a
 532 form suitable for a special device.
 533 .
 534 The roff postprocessors are like device drivers for the output target.
 535 .
 536 .P
 537 For each device there is a postprocessor program that fits the device
 538 optimally.
 539 .
 540 The postprocessor parses the generated intermediate output and
 541 generates device-specific code that is sent directly to the device.
 542 .
 543 .P
 544 The names of the devices and the postprocessor programs are not fixed
 545 because they greatly depend on the software and hardware abilities of
 546 the actual computer.
 547 .
 548 For example, the classical devices mentioned in
 549 .I [CSTR\~#54]
 550 have greatly changed since the classical times.
 551 .
 552 The old hardware doesn't exist any longer and the old graphical
 553 conversions were quite imprecise when compared to their modern
 554 counterparts.
 555 .
 556 .P
 557 For example, the Postscript device
 558 .I post
 559 in classical troff had a resolution
 560 of 720, while groff
 561 .I ps
 562 has 72000, a refinement of factor 100.
 563 .
 564 .P
 565 Today the operating systems provide device drivers for most
 566 printer-like hardware, so it isn't necessary to write a special
 567 hardware postprocessor for each printer.
 568 .
 569 .
 570 .\" --------------------------------------------------------------------
 571 .SH "ROFF PROGRAMMING"
 572 .\" --------------------------------------------------------------------
 573 .
 574 Documents using roff are normal text files decorated by roff
 575 formatting elements.
 576 .
 577 The roff formatting language is quite powerful; it is almost a full
 578 programming language and provides elements to enlarge the language.
 579 .
 580 With these, it became possible to develop macro packages that are
 581 tailored for special applications.
 582 .
 583 Such macro packages are much handier than plain roff.
 584 .
 585 So most people will choose a macro package without worrying about the
 586 internals of the roff language.
 587 .
 588 .
 589 .\" --------------------------------------------------------------------
 590 .SS "Macro Packages"
 591 .\" --------------------------------------------------------------------
 592 .
 593 Macro packages are collections of macros that are suitable to format a
 594 special kind of documents in a convenient way.
 595 .
 596 This greatly eases the usage of roff.
 597 .
 598 The macro definitions of a package are kept in a file called
 599 .IB name .tmac
 600 (classically
 601 .BI tmac. name\c
 602 ).
 603 .
 604 All tmac files are stored in one or more directories at standardized
 605 positions.
 606 .
 607 Details on the naming of macro packages and their placement is found
 608 in
 609 .BR groff_tmac (@MAN5EXT@).
 610 .
 611 .P
 612 A macro package that is to be used in a document can be announced to
 613 the formatter by the command line option
 614 .option \-m ,
 615 see
 616 .BR troff (@MAN1EXT@),
 617 or it can be specified within a document using the file inclusion
 618 requests of the roff language, see
 619 .BR groff (@MAN7EXT@).
 620 .
 621 .P
 622 Famous classical macro packages are
 623 .I man
 624 for traditional man pages,
 625 .I mdoc
 626 for BSD-style manual pages;
 627 the macro sets for books, articles, and letters are
 628 .I me
 629 (probably from the first name of its creator
 630 .I Eric
 631 Allman),
 632 .I ms
 633 (from
 634 .IR "Manuscript Macros\/" ),
 635 and
 636 .I mm
 637 (from
 638 .IR "Memorandum Macros\/" ).
 639 .
 640 .
 641 .\" --------------------------------------------------------------------
 642 .SS "The roff Formatting Language"
 643 .\" --------------------------------------------------------------------
 644 .
 645 The classical roff formatting language is documented in the
 646 .I Troff User's Manual
 647 .IR "[CSTR\~#54]" .
 648 .
 649 The roff language is a full programming language providing requests,
 650 definition of macros, escape sequences, string variables, number or
 651 size registers, and flow controls.
 652 .
 653 .P
 654 .I Requests
 655 are the predefined basic formatting commands similar to the commands
 656 at the shell prompt.
 657 .
 658 The user can define request-like elements using predefined roff
 659 elements.
 660 .
 661 These are then called
 662 .IR macros .
 663 .
 664 A document writer will not note any difference in usage for requests
 665 or macros; both are written on a line on their own starting with a dot
 666 .quoted_char . .
 667 .
 668 .P
 669 .I Escape sequences
 670 are roff elements starting with a backslash
 671 .quoted_char \[rs] .
 672 They can be inserted anywhere, also in the midst of text in a line.
 673 .
 674 They are used to implement various features, including the insertion of
 675 non-ASCII characters with
 676 .esc ( ,
 677 font changes with
 678 .esc f ,
 679 in-line comments with
 680 .esc \[dq] ,
 681 the escaping of special control characters like
 682 .esc \[rs] ,
 683 and many other features.
 684 .
 685 .P
 686 .I Strings
 687 are variables that can store a string.
 688 .
 689 A string is stored by the
 690 .B .ds
 691 request.
 692 .
 693 The stored string can be retrieved later by the
 694 .B \[rs]*
 695 escape sequence.
 696 .
 697 .P
 698 .I Registers
 699 store numbers and sizes.
 700 .
 701 A register can be set with the request
 702 .B .nr
 703 and its value can be retrieved by the escape sequence
 704 .BR "\[rs]n" .
 705 .
 706 .
 707 .\" --------------------------------------------------------------------
 708 .SH "FILE NAME EXTENSIONS"
 709 .\" --------------------------------------------------------------------
 710 .
 711 Manual pages (man pages) take the section number as a file name
 712 extension, e.g., the filename for this document is
 713 .IR roff.7 ,
 714 i.e., it is kept in section\~7
 715 of the man pages.
 716 .
 717 .P
 718 The classical macro packages take the package name as an extension, e.g.
 719 .IB file. me
 720 for a document using the
 721 .I me
 722 macro package,
 723 .IB file. mm
 724 for
 725 .IR mm ,
 726 .IB file. ms
 727 for
 728 .IR ms ,
 729 .IB file. pic
 730 for
 731 .I pic
 732 files,
 733 etc.
 734 .
 735 .P
 736 But there is no general naming scheme for roff documents, though
 737 .IB file. tr
 738 for
 739 .I troff file
 740 is seen now and then.
 741 .
 742 Maybe there should be a standardization for the filename extensions of
 743 roff files.
 744 .
 745 .P
 746 File name extensions can be very handy in conjunction with the
 747 .BR less (1)
 748 pager.
 749 .
 750 It provides the possibility to feed all input into a command-line pipe
 751 that is specified in the shell environment variable
 752 .BR LESSOPEN .
 753 This process is not well documented, so here an example:
 754 .
 755 .IP
 756 .B LESSOPEN='|lesspipe %s'
 757 .
 758 .P
 759 where
 760 .B lesspipe
 761 is either a system supplied command or a shell script of your own.
 762 .
 763 .
 764 .\" --------------------------------------------------------------------
 765 .SH "EDITING ROFF"
 766 .\" --------------------------------------------------------------------
 767 .
 768 The best program for editing a roff document is Emacs (or Xemacs), see
 769 .BR emacs (1).
 770 It provides an
 771 .I nroff
 772 mode that is suitable for all kinds of roff dialects.
 773 .
 774 This mode can be activated by the following methods.
 775 .
 776 .P
 777 When editing a file within Emacs the mode can be changed by typing
 778 .RI ` "M-x nroff-mode" ',
 779 where
 780 .B M-x
 781 means to hold down the
 782 .B Meta
 783 key (or
 784 .BR Alt )
 785 and hitting the
 786 .BR x\~ key
 787 at the same time.
 788 .
 789 .P
 790 But it is also possible to have the mode automatically selected when
 791 the file is loaded into the editor.
 792 .
 793 .Topic
 794 There is a set of file name extensions, e.g. the man pages that
 795 trigger the automatic activation of the nroff mode.
 796 .Topic
 797 Any file containing the character
 798 sequence
 799 .B \%-*-\ nroff\ -*-
 800 in the first line is switched into nroff mode when loaded.
 801 .
 802 But do not use this, it confuses some applications such as the
 803 .B man
 804 program.
 805 .
 806 .Topic
 807 The best method is to include the following 3 comment lines at the end
 808 of the file.
 809 .
 810 .IP
 811 .nf
 812 .B .\*[comment] Local Variables:
 813 .B .\*[comment] mode: nroff
 814 .B .\*[comment] End:
 815 .fi
 816 .
 817 .P
 818 All roff processors handle automated spacing after the end of a
 819 sentence.
 820 .
 821 The safest way to not disturb this or to mix it up with abbreviations
 822 is to start each sentence on a line of its own without preceding white
 823 space.
 824 .
 825 To additionally use the auto-fill mode in Emacs, it is best to insert
 826 an empty roff request (a line consisting of a dot
 827 .quoted_char .
 828 only) after each sentence.
 829 .
 830 This suits the general roff rule to never use blank lines because they
 831 can produce unexpected behavior in the vertical spacing; so each line
 832 that is supposed to be empty or blank should instead use the line
 833 comment
 834 .B .\*[comment]
 835 or the empty request, a line consisting of a dot only.
 836 .
 837 The following example shows how optimal roff editing could look.
 838 .
 839 .IP
 840 .nf
 841 This is a sentence.
 842 .Text .
 843 This is a longer sentence stretching over
 844 several lines.
 845 .Text .
 846 etc.
 847 .fi
 848 .
 849 .P
 850 Besides Emacs, some other editors provide nroff style files too, e.g.\&
 851 .BR vim (1),
 852 an extension of the
 853 .BR vi (1)
 854 program.
 855 .
 856 .
 857 .\" --------------------------------------------------------------------
 858 .SH BUGS
 859 .\" --------------------------------------------------------------------
 860 .
 861 .I UNIX\[rg]
 862 is a registered trademark of the Open Group.
 863 .
 864 .
 865 .\" --------------------------------------------------------------------
 866 .SH "SEE ALSO"
 867 .\" --------------------------------------------------------------------
 868 .
 869 There is a lot of documentation on roff.
 870 .
 871 The original papers on classical troff are still available, and all
 872 aspects of groff are documented in great detail.
 873 .
 874 .
 875 .\" --------------------------------------------------------------------
 876 .SS "Historical roff Documentation"
 877 .\" --------------------------------------------------------------------
 878 .
 879 Many classical
 880 .troff
 881 documents are still available on-line.
 882 .
 883 .P
 884 The old history is best documented at the
 885 .URL http://\:www.multicians.org "Multics site" .
 886 This contains a lot of information on the MIT projects, CTSS, Multics,
 887 early Unix, including runoff.
 888 .
 889 Especially useful are a glossary and the many links to other documents.
 890 .
 891 .P
 892 The web site
 893 .URL http://\:cm.bell-labs.com/\:cm/\:index.html \
 894      "Bell Labs Computing and Mathematical Sciences Research"
 895 provides a search facility for tracking information on the early
 896 developers.
 897 .
 898 .P
 899 The best documentation on the issues of the original, free Unix with
 900 its standard programs are the papers in the series
 901 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html "Bell Labs CSTR" .
 902 .
 903 These also contain the two main documents of the early nroff/troff,
 904 being
 905 .TP
 906 .I [CSTR\~#54]
 907 The 1992\~revision of Osanna/Kernighan's 1976\~paper
 908 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:54.ps \
 909      "Nroff/\:Troff User's Manual" .
 910 .TP
 911 .I [CSTR\~#97]
 912 Brian Kernighan's 1979\~paper
 913 .URL http://\:cm.bell-labs.com/\:cm/\:cs/\:97.ps \
 914      "A Typesetter-independent TROFF" .
 915 .
 916 .
 917 .\" --------------------------------------------------------------------
 918 .SS "Manual Pages"
 919 .\" --------------------------------------------------------------------
 920 .
 921 The
 922 .I manual pages
 923 or shortly
 924 .I man pages
 925 are the main documentation system on many operating system.
 926 .
 927 Due to its complex structure, a full roff system has many man pages,
 928 each describing a single aspect of roff.
 929 .
 930 .P
 931 A reference to a man page looks like this:
 932 .BR groff (@MAN7EXT@).
 933 .
 934 This refers to the manual page on
 935 .I groff
 936 in section\~\c
 937 .IR 7 .
 938 .
 939 To read the example, call from the shell prompt
 940 .
 941 .P
 942 .ShellCommand man @MAN7EXT@ groff
 943 .
 944 .P
 945 For more details, see the documentation of the
 946 .B man
 947 program in section\~1, i.e.
 948 .BR man (@MAN1EXT@).
 949 .
 950 .P
 951 For the different roff implementations, there is no general naming
 952 scheme for its documentation.
 953 .
 954 In
 955 .IR groff ,
 956 the man page
 957 .BR groff (@MAN1EXT@)
 958 contains a survey of all documentation available in groff.
 959 .
 960 On other systems, you are on your own, but
 961 .BR troff (1)
 962 might be a good starting point.
 963 .
 964 .
 965 .\" --------------------------------------------------------------------
 966 .SH AUTHORS
 967 .\" --------------------------------------------------------------------
 968 .
 969 Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
 970 .
 971 .P
 972 This document is distributed under the terms of the FDL (GNU Free
 973 Documentation License) version 1.1 or later.
 974 .
 975 You should have received a copy of the FDL on your system, it is also
 976 available on-line at the
 977 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
 978 .
 979 .P
 980 This document is part of
 981 .IR groff ,
 982 the GNU roff distribution.
 983 .
 984 It was written by
 985 .MTO bwarken@mayn.de "Bernd Warken" ;
 986 it is maintained by
 987 .MTO wl@gnu.org "Werner Lemberg".
 988 .
 989 .
 990 .\" --------------------------------------------------------------------
 991 .\" Emacs setup
 992 .\" --------------------------------------------------------------------
 993 .
 994 .\" Local Variables:
 995 .\" mode: nroff
 996 .\" End: