contrib/groff/man/roff.man

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