man/roff.man

   1 .\"                        -*- nroff -*-
   2 .ig
   3 roff.7
   4
   5 This file is part of groff, the GNU roff type-setting system.
   6
   7 Copyright (C) 2000 Free Software Foundation, Inc.
   8 written by Bernd Warken <bwarken@mayn.de>
   9
  10 Last update: 17 May 2000
  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 AUTHOR, 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 .if n \{\
  27 .  mso tmac.tty-char
  28 .  ftr CR R
  29 .  ftr CI I
  30 .  ftr CB B
  31 .\}
  32 .
  33 .\" text lines in macro definitions or bracketed sections \{...\}
  34 .de text
  35 .  if 1 \&\\$*\&
  36 ..
  37 .
  38 .de BIR
  39 .ie (\\n[.$] < 3) \
  40 .  BI $@
  41 .el \{\
  42 .  ds @tmp@ \fB\\$1\fP\fI\\$2\fP
  43 .  shift 2
  44 .  text \\*[@tmp@]\fR\\$*\fP
  45 .  rm @tmp@
  46 .\}
  47 ..
  48 .
  49 .de option
  50 .  ds @tmp@ \f(CB\\$1\fP
  51 .  shift 1
  52 .  text \\*[@tmp@]\\$*
  53 .  rm @tmp@
  54 ..
  55 .
  56 .de 'char
  57 .  ds @tmp@ `\f(CB\\$1\fP'
  58 .  shift
  59 .  text \\*[@tmp@]\\$*
  60 .  rm @tmp@
  61 ..
  62 .
  63 .de esc
  64 .  ds @tmp@ \f(CB\e\\$1\fP
  65 .  shift
  66 .  text \\*[@tmp@]\\$*
  67 .  rm @tmp@
  68 ..
  69 .
  70 .de argname
  71 .  ds @tmp@ \f(CI\\$1\fP
  72 .  shift 1
  73 .  text \\*[@tmp@]\\$*
  74 .  rm @tmp@
  75 ..
  76 .
  77 .de prefixednumber
  78 .  ds @tmp@ \&\\$1\ \f(CR\\$2\fP
  79 .  shift 2
  80 .  text \\*[@tmp@]\\$*
  81 .  rm @tmp@
  82 ..
  83 .
  84 .\" --------------------------------------------------------------------
  85 .\" Title
  86 .\" --------------------------------------------------------------------
  87 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  88 .SH NAME
  89 roff \- a survey of the roff typesetting system
  90 .\" --------------------------------------------------------------------
  91 .SH DESCRIPTION
  92 .\" --------------------------------------------------------------------
  93 .I roff
  94 is the general name for a set of type-setting programs, known under
  95 names like
  96 .IR troff ,
  97 .IR nroff ,
  98 .IR groff ,
  99 etc.
 100 .LP
 101 The roff type-setting system consists of a formatting language, macro
 102 packages, preprocessors, postprocessors for output devices, user
 103 front-end programs, and conversion tools.
 104 .LP
 105 The most common roff system today is the free software implementation
 106 .I groff
 107 (from `GNU\ roff').
 108 The pre-groff implementations are referred to as `classical' (dating
 109 back as long as 1973).
 110 .LP
 111 .I groff
 112 is backward-compatible to its classical ancestors, but has many
 113 extensions, and is still evolving.
 114 As it is available for almost every computer system it is the de-facto
 115 roff standard today.
 116 .LP
 117 In spite of its age, roff is in wide use today, e.g., the manual pages
 118 on UNIX systems
 119 .RI ( man-pages )
 120 are written in roff.
 121 The roff output for text devices is still unmatched, and its graphical
 122 output has the same quality as the other free type-setting programs and
 123 is better than some of the commercial systems.
 124 .LP
 125 This document gives only an overview and provides pointers to further
 126 documentation.
 127
 128 This document is not maintained and might be out of date.  For the real
 129 documentation refer to the groff info file that contains the detailed,
 130 actual and concise reference information.
 131 .\" --------------------------------------------------------------------
 132 .SH "FORMATTING LANGUAGE"
 133 .\" --------------------------------------------------------------------
 134 There are three terms that refer to the language of the
 135 .I roff
 136 system.
 137 The term
 138 .I troff language
 139 is used when the classical aspects of
 140 .I roff
 141 are stressed, the term
 142 .I groff language
 143 includes the GNU extensions, whereas
 144 .I roff language
 145 is the general term.
 146 .LP
 147 The main source of documentation for all aspects of the
 148 .I groff language
 149 is the groff info file.  The manual page
 150 .BR groff (@MAN7EXT@)
 151 gives a short description of all predefined language elements.
 152 .LP
 153 Documents using roff are normal text files decorated by formatting
 154 elements.
 155 It is very easy to write high-quality documents by using one of the
 156 macro packages.
 157 These are like high-level programming languages, while the bare roff
 158 language compares to a low-level language like C or assembler.
 159 .LP
 160 The roff language is a full programming language providing low-level
 161 requests, definition of macros, escape sequences, string variables,
 162 number or size registers, and C-like flow controls.
 163 .ig /
 164 In the 1980s, it was even possible to write the common utilities for
 165 system administration by only using troff.
 166 There were contests on writing the most unreadable program fake by
 167 exclusively using troff.
 168 Because of security impacts, these dangerous features were removed in
 169 .IR groff .
 170 ./
 171 .LP
 172 Some clarification on the language elements seems to be wanted.
 173 Requests are basic formatting commands defined by programming languages
 174 like C, C++, etc., whereas macros are formatting commands that are
 175 written in the roff language.
 176 A document writer will not note any difference in usage for requests or
 177 macros, both are written on a line on their own starting with a dot
 178 .'char . .
 179 But the user may define her own macros if desired.
 180 .LP
 181 Escape sequences are in-line elements starting with a backslash
 182 .'char \e .
 183 They are used to implement various features, including the insertion of
 184 non-ASCII characters with
 185 .esc ( ,
 186 the content of strings with
 187 .esc *
 188 and register variables with
 189 .esc n ,
 190 font changes with
 191 .esc f ,
 192 in-line comments with
 193 .esc \(dq ,
 194 the escaping of special control characters like
 195 .esc \e ,
 196 and many other features.
 197 .\" --------------------------------------------------------------------
 198 .SH FORMATTERS
 199 .\" --------------------------------------------------------------------
 200 Formatters are the front-end programs that analyze a groff document and
 201 translate it into a form that is suitable for a special device.
 202 The traditional
 203 .I roff
 204 had two formatters,
 205 .B nroff
 206 for text devices and
 207 .B troff
 208 for graphical devices.
 209 .LP
 210 These programs still exist in the
 211 .I groff
 212 implementation, but usually they are accessed through a program called
 213 .BR groff .
 214 This combined and extended the old functionality into a single program.
 215 It has many command-line options, most of them herited from
 216 .BR troff .
 217 To ease the option jungle, the user-friendly utility
 218 .B grog
 219 (from `groff guess') was created.
 220 It tries to guess from the document which arguments should be used and
 221 displays a suitable command line.
 222 Though not being perfect, it is a good starting point.
 223 .\" --------------------------------------------------------------------
 224 .SH PREPROCESSORS
 225 .\" --------------------------------------------------------------------
 226 The classical preprocessors that are still available in groff.
 227 .RS
 228 .LP
 229 .PD 0
 230 .TP
 231 .I eqn
 232 for including mathematical equations.
 233 .TP
 234 .I grap
 235 for constructing graphical elements (this preprocessor doesn't come with
 236 groff; it is an extra package).
 237 .TP
 238 .I grn
 239 for including gremlin pictures.
 240 .TP
 241 .I pic
 242 for creating diagrams.
 243 .TP
 244 .I refer
 245 for bibliographic references.
 246 .TP
 247 .I soelim
 248 for including other roff files.
 249 .TP
 250 .I tbl
 251 for rectangular tables.
 252 .PD
 253 .RE
 254 .LP
 255 Each of these preprocessors defines its own language that is translated
 256 into roff code when run through the preprocessor program.
 257 So parts written in these languages may be included within a roff
 258 document.
 259 Such an enhanced document is run through one or more corresponding
 260 preprocessors before it is fed into the actual formatter.
 261 .LP
 262 The preprocessor programs extract and transform the document parts
 263 determined for them.
 264 They can be called either in a UNIX pipeline with their program name or
 265 automatically with a groff option.
 266 .LP
 267 .TS
 268 center, box, tab (@);
 269 C | C
 270 CfCB | CfCB.
 271 preprocessor@groff option
 272 =
 273 eqn@\-e
 274 grap@\-G
 275 grn@\-g
 276 pic@\-p
 277 refer@\-R
 278 tbl@\-r
 279 soelim@\-s
 280 .TE
 281 .LP
 282 .
 283 .\" --------------------------------------------------------------------
 284 .SH "MACRO PACKAGES"
 285 .\" --------------------------------------------------------------------
 286 Macro packages are collections of macros that are suitable to format a
 287 special kind of documents in a convenient way.
 288 This greatly eases the usage of roff.
 289 The macro definitions of a package are kept in a file called
 290 .BI tmac. name
 291 where
 292 .I name
 293 is the internal roff name for this package.
 294 All tmac files are stored in a single or few directories at standard
 295 positions.
 296 .LP
 297 A macro package that is used in a document is specified by the command line
 298 option
 299 .option \-m
 300 for the formatter like
 301 .option "troff\ \-m"
 302 .argname name
 303 or
 304 .option "groff\ \-m"
 305 .argname name .
 306 General details on the naming of macro packages and their placement is
 307 found in
 308 .BR tmac (@MAN5EXT@).
 309 .LP
 310 Famous classical macro packages are
 311 .IR man ,
 312 .IR mandoc ,
 313 and
 314 .I mdoc
 315 for manual pages and
 316 .IR me ,
 317 .IR ms ,
 318 and
 319 .I mm
 320 for books, articles, and letters.
 321 Besides these collections, groff provides an increasing number of new
 322 macro packages for various applications, for example integration of or
 323 conversion into other file formats.
 324 .\" --------------------------------------------------------------------
 325 .SH "FILE NAME EXTENSIONS"
 326 .\" --------------------------------------------------------------------
 327 Manual pages (man-pages) take the section number as a file name
 328 extension, e.g., the filename for this document is
 329 .IR roff.7 ,
 330 i.e., it is kept in
 331 .prefixednumber section 7
 332 of the man-pages.
 333 .LP
 334 The classical macro packages take the package name as an extension, e.g.
 335 .IB file. me
 336 for a document using the
 337 .I me
 338 macro package,
 339 .IB file. mm
 340 for
 341 .IR mm ,
 342 .IB file. ms
 343 for
 344 .IR ms ,
 345 .IB file. pic
 346 for
 347 .I pic
 348 files,
 349 etc.
 350 .ig
 351 .LP
 352 But there is no general naming scheme for roff documents, though
 353 .IB file. roff
 354 or
 355 .IB file. rof
 356 seems to be a good choice.
 357 .LP
 358 File name extensions can be very handy in conjunction with the
 359 .BR less (1)
 360 pager.
 361 It provides the possibility to feed all input into a command-line pipe that
 362 is specified in the shell environment variable
 363 .B LESSOPEN
 364 This process is not well documented, so here an example
 365 .B LESSOPEN='|lesspipe %s'
 366 where
 367 .B lesspipe
 368 is either a system supplied command or a shell script of your own.
 369 ..
 370 .\" --------------------------------------------------------------------
 371 .SH EDITING
 372 .\" --------------------------------------------------------------------
 373 Most text editors provide support for editing documents using roff.
 374 Especially useful is the
 375 .B nroff-mode
 376 in all flavors of the Emacs editor.
 377 .\" --------------------------------------------------------------------
 378 .SH ENVIRONMENT
 379 .\" --------------------------------------------------------------------
 380 .TP
 381 .SM
 382 .B GROFF_TMAC_PATH
 383 A colon separated list of directories in which to search for
 384 macro files, see
 385 .BR tmac (@MAN5EXT@).
 386 .TP
 387 .SM
 388 .B GROFF_TYPESETTER
 389 Default device.
 390 .TP
 391 .SM
 392 .B GROFF_FONT_PATH
 393 A colon separated list of directories in which to search for the
 394 .BI dev name
 395 directory.
 396 .B troff
 397 will search in directories given in the
 398 .option \-F
 399 option before these, and in standard directories
 400 .RB ( .:/usr/local/share/groff/font:/usr/lib/font )
 401 after these.
 402 .\" --------------------------------------------------------------------
 403 .SH FILES
 404 .\" --------------------------------------------------------------------
 405 By default,
 406 .I groff
 407 installs all of its library files in a directory tree under
 408 .IR /usr/local/share/groff .
 409 This location might vary for different systems.
 410 In the following, this directory is referred to as
 411 .IR <groff_dir> .
 412 .LP
 413 .TP
 414 .IB <groff_dir> /tmac/troffrc
 415 Initialization file for troff.
 416 .TP
 417 .IB <groff_dir> /tmac/tmac. name
 418 Macro files.
 419 .TP
 420 .IB <groff_dir> /font/dev name /DESC
 421 Device description file for device
 422 .IR name .
 423 .TP
 424 .IB <groff_dir> /font/dev name / F
 425 Font file for font
 426 .I F
 427 of device
 428 .IR name .
 429 .\" --------------------------------------------------------------------
 430 .SH BUGS
 431 .\" --------------------------------------------------------------------
 432 The groff documentation is in evolution at the moment.
 433 It is possible that small inconsistencies between different documents exist
 434 temporarily.
 435 .\" --------------------------------------------------------------------
 436 .SH AUTHOR
 437 .\" --------------------------------------------------------------------
 438 This document is part of groff, the GNU roff distribution.  It was
 439 written by Bernd Warken <bwarken@mayn.de>.
 440 .LP
 441 It is distributed under the terms of the FDL (GNU Free Documentation
 442 License) version 1.1 or later.  You should have received a copy of the
 443 FDL on your system, it is also available on-line under
 444 .RS
 445 .LP
 446 .IR <http://www.gnu.org/copyleft/fdl.html> .
 447 .RE
 448 .\" --------------------------------------------------------------------
 449 .SH "SEE ALSO"
 450 .\" --------------------------------------------------------------------
 451 The main source of information is the
 452 .I groff
 453 .BR info (1)
 454 file.
 455 .LP
 456 The predefined elements of the
 457 .I groff
 458 language are also documented in the manual page
 459 .BR groff (@MAN7EXT@).
 460 .LP
 461 Formatters and their wrappers:
 462 .BR groff (@MAN1EXT@),
 463 .BR grog (@MAN1EXT@),
 464 .BR nroff (@MAN1EXT@),
 465 and
 466 .BR troff (@MAN1EXT@).
 467 .LP
 468 Postprocessors for the output devices:
 469 .BR grodvi (@MAN1EXT@),
 470 .BR grohtml (@MAN1EXT@),
 471 .BR grolbp (@MAN1EXT@),
 472 .BR grolj4 (@MAN1EXT@),
 473 .BR grops (@MAN1EXT@),
 474 and
 475 .BR grotty (@MAN1EXT@).
 476 .LP
 477 Standard preprocessors:
 478 .BR eqn (@MAN1EXT@),
 479 .BR grn (@MAN1EXT@),
 480 .BR grap (1),
 481 .BR pic (@MAN1EXT@),
 482 .BR refer (@MAN1EXT@),
 483 .BR soelim (@MAN1EXT@),
 484 and
 485 .BR tbl (@MAN1EXT@).
 486 .LP
 487 The man pages for macro packages include
 488 .BR groff_tmac (@MAN5EXT@),
 489 .BR groff_man (@MAN7EXT@),
 490 .BR groff_markup (@MAN7EXT@),
 491 .BR groff_mdoc (@MAN7EXT@),
 492 .BR groff_mdoc.samples (@MAN7EXT@),
 493 .BR groff_me (@MAN7EXT@),
 494 .BR groff_mm (@MAN7EXT@),
 495 .BR groff_mmroff (@MAN7EXT@),
 496 .BR groff_ms (@MAN7EXT@),
 497 and
 498 .BR groff_msafer (@MAN7EXT@).
 499 .LP
 500 The following utilities are available:
 501 .BR addftinfo (@MAN1EXT@),
 502 .BR afmtodif (@MAN1EXT@),
 503 .BR hpftodit (@MAN1EXT@),
 504 .BR indxbib (@MAN1EXT@),
 505 .BR lookbib (@MAN1EXT@),
 506 .BR pfbtops (@MAN1EXT@),
 507 .BR tfmtodit (@MAN1EXT@),
 508 and
 509 .BR gxditview (@MAN1EXT@).
 510 .LP
 511 For details on the GNU implementation of the
 512 .I roff
 513 system see
 514 .BR groff_char (@MAN7EXT@),
 515 .BR groff_font (@MAN7EXT@),
 516 .BR groff_out (@MAN7EXT@),
 517 and the file
 518 .I README
 519 in the main directory of the groff source distribution.
 520 These also give details on how to contact or join the
 521 .I groff
 522 developer group.
 523 .LP
 524 Many classical
 525 .troff
 526 documents are still available on-line.
 527 Especially informative are the original Bell Labs proceedings for the old,
 528 free UNIX 7 found at
 529 .I http://cm.bell-labs.com/cm/cs/cstr.html
 530 and the collection of the late Richard S. Stevens at
 531 .IR http://www.kohala.com/start/troff/ .