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