contrib/groff/contrib/groffer/groffer.man

   1 .TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
   2 .SH NAME
   3 groffer \- display groff files and man\~pages on X and tty
   4 .
   5 .SH "SYNOPSIS"
   6 .\" The .SH was moved to this place in order to appease `apropos'.
   7 .
   8 .\" --------------------------------------------------------------------
   9 .\" Legalize
  10 .\" --------------------------------------------------------------------
  11 .
  12 .ig
  13 groffer.1 - man page for groffer (section 1).
  14
  15 Source file position:  <groff_source_top>/contrib/groffer/groffer.man
  16 Installed position:    $prefix/share/man/man1/groffer.1
  17
  18 Version     : groffer 0.9.1
  19 Last update : 30 Sep 2002
  20
  21 This file is part of groff, the GNU roff type-setting system.
  22
  23 Copyright (C) 2001, 2002 Free Software Foundation, Inc.
  24 Written by Bernd Warken <bwarken@mayn.de>
  25
  26 Permission is granted to copy, distribute and/or modify this document
  27 under the terms of the GNU Free Documentation License, Version 1.1 or
  28 any later version published by the Free Software Foundation; with the
  29 Invariant Sections being this .ig-section and AUTHORS, with no
  30 Front-Cover Texts, and with no Back-Cover Texts.
  31
  32 A copy of the Free Documentation License is included as a file called
  33 FDL in the main directory of the groff source package.
  34 ..
  35 .
  36 .\" --------------------------------------------------------------------
  37 .\" Setup
  38 .\" --------------------------------------------------------------------
  39 .
  40 .mso www.tmac
  41 .
  42 .if n \{\
  43 .  mso tty-char.tmac
  44 .  ftr CR R
  45 .  ftr CI I
  46 .  ftr CB B
  47 .\}
  48 .
  49 .if '\*[.T]'dvi' \{\
  50 .  ftr CB CW
  51 .\}
  52 .
  53 .ds @- "\-\""
  54 .ds @-- "\-\^\-\""
  55 .
  56 .ds @b- "\f[CB]-\f[]\""
  57 .ds @b-- "\f[CB]--\f[]\""
  58 .
  59 .ds @i- "\f[CI]-\f[]\""
  60 .ds @i-- "\f[CI]--\f[]\""
  61 .
  62 .ds Ellipsis .\|.\|.\"
  63 .
  64 .\" --------------------------------------------------------------------
  65 .\" setup for the macro definitions below
  66 .\"
  67 .\" naming:  namespace:cathegory_macro.variable_name  (experimental)
  68 .
  69 .\" --------------------------------------------------------------------
  70 .\" configuration of prompt for `.Shell_cmd'* macros
  71 .ds groffer:Shell_cmd.prompt_text sh#\"    prompt for shell commands
  72 .ds groffer:Shell_cmd+.prompt_text >\"     prompt on continuation lines
  73 .ds groffer:Shell_cmd_base.prompt_font I\" font for prompts
  74 .
  75 .\" automatically determine setup from the configuration above
  76 .als @f groffer:Shell_cmd_base.prompt_font\"
  77 .als @t groffer:Shell_cmd.prompt_text\"
  78 .als @t+ groffer:Shell_cmd+.prompt_text\"
  79 .ds groffer:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\"            needed
  80 .ds groffer:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\"          needed
  81 .nr @w \w'\*[groffer:Shell_cmd.prompt]'\"
  82 .nr @w+ \w'\*[groffer:Shell_cmd+.prompt]'\"
  83 .ft \*[@f]
  84 .\" Full prompt width is maximum of texts plus 1m
  85 .nr groffer:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
  86 .ft
  87 .rm @f
  88 .rm @f+
  89 .rm @t
  90 .rm @t+
  91 .rr @w
  92 .rr @w+
  93 .
  94 .\" --------------------------------------------------------------------
  95 .\" static register for inter-macro communication in `.Synopsis'*
  96 .nr groffer:Synopsis.level 0
  97 .
  98 .\" --------------------------------------------------------------------
  99 .\" static registers for inter-macro communication in `.TP'*
 100 .nr groffer:TP.level 0
 101 .rr groffer:TP_header.flag
 102 .rr groffer:TP_body.flag
 103 .rr groffer:TP.indent
 104 .
 105 .
 106 .\" --------------------------------------------------------------------
 107 .\" Macro definitions
 108 .
 109 .\" Ignore all arguments like a comment, even after a .eo call.
 110 .de c
 111 ..
 112 .c --------------------------------------------------------------------
 113 .c .CB  (<text>...)
 114 .c
 115 .c Print in constant-width bold font.
 116 .c
 117 .de CB
 118 .  ft CB
 119 .  Text \\$*
 120 .  ft
 121 ..
 122 .c --------------------------------------------------------------------
 123 .c .CI  (<text>...)
 124 .c
 125 .c Print in constant-width italic font.
 126 .c
 127 .de CI
 128 .  ft CI
 129 .  Text \\$*
 130 .  ft
 131 ..
 132 .c --------------------------------------------------------------------
 133 .c .CR  (<text>...)
 134 .c
 135 .c Print in constant-width roman font.
 136 .c
 137 .de CR
 138 .  ft CR
 139 .  Text \\$*
 140 .  ft
 141 ..
 142 .c --------------------------------------------------------------------
 143 .c .Error  (<text>...)
 144 .c
 145 .c Print error message to terminal and abort.
 146 .c
 147 .de Error
 148 .  tm \\$*
 149 .  ab
 150 ..
 151 .c --------------------------------------------------------------------
 152 .c .Env_var  (<env_var_name> [<punct>])
 153 .c
 154 .c Display an environment variable, with optional punctuation.
 155 .c
 156 .de Env_var
 157 .  nh
 158 .  SM
 159 .  Text \f[CB]\\$1\f[]\\$2
 160 .  hy
 161 ..
 162 .c --------------------------------------------------------------------
 163 .c .Opt_-  ([<punct>])
 164 .c
 165 .c Print `-' (minus sign); optional punctuation.
 166 .c
 167 .de Opt_-
 168 .  ie (\\n[.$] == 0) \
 169 .    Opt_alt - ""
 170 .  el \
 171 .    Opt_alt - "" "\\$1"
 172 ..
 173 .c --------------------------------------------------------------------
 174 .c .Opt_[-]  ([<punct>])
 175 .c
 176 .c Print `Opt_[-]' (minus sign in brackets); optional punctuation.
 177 .c
 178 .de Opt_[-]
 179 .  ie (\\n[.$] == 0) \
 180 .    Opt_[alt] - ""
 181 .  el \
 182 .    Opt_[alt] - "" "\\$1"
 183 ..
 184 .c --------------------------------------------------------------------
 185 .c .Opt_--  ([<punct>])
 186 .c
 187 .c Print `--' (double minus); optional punctuation.
 188 .c
 189 .de Opt_--
 190 .  ie (\\n[.$] == 0) \
 191 .    Opt_alt -- ""
 192 .  el \
 193 .    Opt_alt -- "" "\\$1"
 194 ..
 195 .c --------------------------------------------------------------------
 196 .c .Opt_[--]  ([<punct>])
 197 .c
 198 .c Print `Opt_[--]' (double minus in brackets); optional punctuation.
 199 .c
 200 .de Opt_[--]
 201 .  ie (\\n[.$] == 0) \
 202 .    Opt_[alt] -- ""
 203 .  el \
 204 .    Opt_[alt] -- "" "\\$1"
 205 ..
 206 .c --------------------------------------------------------------------
 207 .c .Opt_alt  ([<minus> <opt>]... [<arg> [<punct>]])
 208 .c
 209 .c Alternate options separated by a vertical bar.
 210 .c
 211 .c Arguments:
 212 .c   minus: either `-' or `--' (font CB).
 213 .c   opt: a name for an option, empty allowed (font CB).
 214 .c   arg: optionally, the argument to the option (font I).
 215 .c   punct: optional punctuation (in the starting font).
 216 .c Result:
 217 .c   The minus/opt argument pairs, each
 218 .c   separated by a vertical bar `|', optionally add 'arg', separated
 219 .c   a space character ` '.
 220 .c
 221 .c Example:
 222 .c  .Opt_alt - T -- device -- device-troff device .
 223 .c  results in
 224 .c  -T|--device|--device-troff device.
 225 .c
 226 .de Opt_alt
 227 .  Opt_alt_base "" | "" \\$@
 228 ..
 229 .c --------------------------------------------------------------------
 230 .c .Opt_[alt]  ([<minus> <opt>]... [<arg> [<punct>]])
 231 .c
 232 .c Alternate options in brackets for section SYNOPSIS.
 233 .c
 234 .c Arguments:
 235 .c   minus: either `-' or `--' (font CB).
 236 .c   opt: a name for an option, empty allowed (font CB).
 237 .c   arg: optionally, the argument to the option (font I).
 238 .c   punct: optional punctuation (in the starting font).
 239 .c Global strings written to:
 240 .c   `@oa_prefix': left enclosing character (`[')
 241 .c   `@oa_sep': separator (`|')
 242 .c   `@oa_postfix': right enclosing character (`]')
 243 .c Result:
 244 .c   The minus/opt argument pairs, each separated by a vertical
 245 .c   bar `|', optionally add 'arg', separated by a space character ` '.
 246 .c
 247 .c Example:
 248 .c  .Opt_[alt] - T -- device -- device-troff device .
 249 .c  results in
 250 .c  [-T|--device|--device-troff device].
 251 .c
 252 .de Opt_[alt]
 253 .  Opt_alt_base [ | ] \\$@
 254 ..
 255 .c --------------------------------------------------------------------
 256 .c .Opt_alt_base  (<pre> <sep> <post> [<minus> <opt>]... [arg [punct]])
 257 .c
 258 .c Alternating options; base macro for many others; do not use directly.
 259 .c
 260 .c Arguments:
 261 .c   <pre>: prefix, resulted is preceded by this.
 262 .c   <sep>: separator between minux/opt pairs.
 263 .c   <post>: postfix, is appended to the result.
 264 .c   <minus>: either `-' or `--' (font CB).
 265 .c   <opt>: a name for an option, empty allowed (font CB).
 266 .c   <arg>: optionally, the argument to the option (font I).
 267 .c   <punct>: optional punctuation (in the starting font).
 268 .c Result:
 269 .c   String `<pre>' followed by the <minus>/<opt> argument pairs, each
 270 .c   separated by string `<sep>', optionally add '<arg>', separated by
 271 .c   a single space ` ', followed by the string `<post>'.
 272 .c
 273 .de Opt_alt_base
 274 .  nr @font \\n[.f]\"
 275 .  if (\\n[.$] < 3) \
 276 .    Error .\\0: not enough arguments.
 277 .  ds @pre \)\\$1\)\"                   prefix
 278 .  ds @sep \)\\$2\)\"                   separator
 279 .  ds @post \)\\$3\)\"                  postfix
 280 .  shift 3
 281 .  nr @count 0
 282 .  ds @res \f[CR]\\*[@pre]\"
 283 .  while (\\n[.$] >= 2) \{\
 284 .    c                                  do the pairs, break on no `-'
 285 .    if !'\\$1'-' \{\
 286 .      if !'\\$1'--' \
 287 .        break
 288 .    \}
 289 .    c                                  separator
 290 .    if (\\n[@count] > 0) \
 291 .      as @res \f[CR]\\*[@sep]\"
 292 .    nr @count +1
 293 .    as @res \f[CB]\\$1\\$2\:\"           combine minus with option name
 294 .    shift 2
 295 .  \}
 296 .  if (\\n[.$] >= 3) \
 297 .    Error .\\0: wrong arguments: \\$@
 298 .  c                                     all pairs are done
 299 .  ie (\\n[.$] == 0) \
 300 .    as @res \f[CR]\\*[@post]\"
 301 .  el \{\
 302 .    c                                   optional option argument
 303 .    if !'\\$1'' \
 304 .      as @res \f[CR] \,\f[I]\\$1\"
 305 .    shift
 306 .    as @res \\f[CR]\\*[@post]\"         postfix
 307 .    if (\\n[.$] >= 1) \{\
 308 .      c                                 add punctuation
 309 .      as @res \f[\\n[@font]]\\$1\"
 310 .    \}
 311 .  \}
 312 .  nh
 313 .  Text \\*[@res]
 314 .  hy
 315 .  ft \\n[@font]
 316 .  rr @count
 317 .  rr @font
 318 .  rm @pre
 319 .  rm @post
 320 .  rm @sep
 321 .  rm @res
 322 ..
 323 .c --------------------------------------------------------------------
 324 .c .Opt_def  ([<minus> <opt>]... [<arg> [<punct>]])
 325 .c
 326 .c Definitions of options in section OPTIONS.
 327 .c
 328 .c Arguments:
 329 .c   minus: either `-' or `--' (font CB).
 330 .c   opt: a name for an option, empty allowed (font CB).
 331 .c   arg: optionally, the argument to the option (font I).
 332 .c   punct: optional punctuation (in the starting font).
 333 .c Result:
 334 .c   The header for an indented paragraph, consisting of
 335 .c   minus/opt argument pairs, each, separated by a space
 336 .c   character ` ', optionally add 'arg', separated a space
 337 .c   character ` '.
 338 .c
 339 .c Example:
 340 .c  .Opt_def - T -- device -- device-troff device .
 341 .c  results in
 342 .c  -T --device --device-troff device.
 343 .c  as the header of for indented paragraph.
 344 .c
 345 .de Opt_def
 346 .  TP
 347 .    Opt_alt_base "" "\~|\~" "" \\$@
 348 ..
 349 .c --------------------------------------------------------------------
 350 .c .Opt_element  ([<minus> <opt>]... [<arg> [<punct>]])
 351 .c
 352 .c Definitions of options in section OPTIONS.
 353 .c
 354 .c Arguments:
 355 .c   minus: either `-' or `--' (font CB).
 356 .c   opt: a name for an option, empty allowed (font CB).
 357 .c   arg: optionally, the argument to the option (font I).
 358 .c   punct: optional punctuation (in the starting font).
 359 .c Result:
 360 .c   The minus/opt argument pairs, each, separated by a space
 361 .c   character ` ', optionally add 'arg', separated a space
 362 .c   character ` '.
 363 .c
 364 .c Example:
 365 .c  .Opt_element - T -- device -- device-troff device .
 366 .c  results in
 367 .c  -T --device --device-troff device.
 368 .c
 369 .de Opt_element
 370 .  Opt_alt_base "" "\~" "" \\$@
 371 ..
 372 .c --------------------------------------------------------------------
 373 .als Opt_list Opt_element
 374 .
 375 .c --------------------------------------------------------------------
 376 .c .Opt_long  ([<name> [<punct>]])
 377 .c
 378 .c Print `--name' somewhere in the text; optional punctuation.
 379 .c
 380 .de Opt_long
 381 .  Opt_alt -- "\\$1" "" "\\$2"
 382 ..
 383 .c --------------------------------------------------------------------
 384 .c .Opt_[long]  ([<name> [<punct>]])
 385 .c
 386 .c Print `--name' somewhere in the text; optional punctuation.
 387 .c
 388 .de Opt_[long]
 389 .  Opt_[alt] -- "\\$1" "" "\\$2"
 390 ..
 391 .c --------------------------------------------------------------------
 392 .c .Opt_short  ([<name> [<punct>]])
 393 .c
 394 .c Print `-name' somewhere in the Text; optional punctuation.
 395 .c
 396 .de Opt_short
 397 .  Opt_alt - "\\$1" "" "\\$2"
 398 ..
 399 .c --------------------------------------------------------------------
 400 .c .Opt_[short]  ([name [punct]])
 401 .c
 402 .c Print `[-name]' somewhere in the Text; optional punctuation.
 403 .c
 404 .de Opt_[short]
 405 .  Opt_[alt] - "\\$1" "" "\\$2"
 406 ..
 407 .c --------------------------------------------------------------------
 408 .c .Shell_cmd  (<CR> [<CI>] ...)
 409 .c
 410 .c A shell command line; display args alternating in fonts CR and CI.
 411 .c
 412 .c Examples:
 413 .c   .Shell_cmd "groffer --dpi 100 file"
 414 .c     result: `sh#  groffer --dpi 100 file'
 415 .c             with 'sh#' in font I, the rest in CR
 416 .c
 417 .c   .Shell_cmd groffer\~--dpi\~100\~file
 418 .c     result: the same as above
 419 .c
 420 .c   .Shell_cmd "groffer --dpi=" value " file"
 421 .c     result: sh#  groffer --dpi=value file
 422 .c             with `groffer --dpi=' and `file' in CR; `value' in CI
 423 .c
 424 .c   .Shell_cmd groffer\~--dpi= value \~file
 425 .c     result: the same as the previous example
 426 .c
 427 .de Shell_cmd
 428 .  groffer:Shell_cmd_base "\*[groffer:Shell_cmd.prompt]" \\$@
 429 ..
 430 .c --------------------------------------------------------------------
 431 .c .Shell_cmd+  (<CR> [<CI>] ...)
 432 .c
 433 .c A continuation line for .Shell_cmd.
 434 .c
 435 .de Shell_cmd+
 436 .  groffer:Shell_cmd_base "\*[groffer:Shell_cmd+.prompt]" \\$@
 437 ..
 438 .c --------------------------------------------------------------------
 439 .c .Shell_cmd_base  (<prompt> [<CR> [<CI>] ...])
 440 .c
 441 .c A shell command line; display args alternating in fonts CR and CI.
 442 .c Internal, do not use directly.
 443 .c
 444 .c Globals: read-only register @.Shell_cmd_width
 445 .c
 446 .de groffer:Shell_cmd_base
 447 .  if (\\n[.$] <= 0) \
 448 .    return
 449 .  nr @+font \\n[.f]\"
 450 .  ds @prompt \\$1\"
 451 .  ft CR
 452 .  c gap between prompt and command
 453 .  nr @+gap \\n[groffer:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
 454 .  ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
 455 .  shift
 456 .  ds @cf CR\"
 457 .  while (\\n[.$] > 0) \{\
 458 .    as @res \\f[\\*[@cf]]\\$1\"
 459 .    shift
 460 .    ie '\\*[@cf]'CR' \
 461 .      ds @cf I\"
 462 .    el \
 463 .      ds @cf CR\"
 464 .  \}
 465 .  br
 466 .  ad l
 467 .  nh
 468 .  nf
 469 .  Text \\*[@res]\"
 470 .  fi
 471 .  hy
 472 .  ad
 473 .  br
 474 .  ft \\n[@+font]
 475 .  rr @+font
 476 .  rr @+gap
 477 .  rm @cf
 478 .  rm @res
 479 ..
 480 .c --------------------------------------------------------------------
 481 .c .Synopsis  ()
 482 .c
 483 .c Begin a synopsis section, to be ended by a ./Synopsis macro.
 484 .c
 485 .de Synopsis
 486 .  if (\\n[groffer:Synopsis.level] > 0) \
 487 .    Error .\\$0: previous .Synopsis was not closed by ./Synopsis.
 488 .  nh
 489 .  ds @1 \\$1\"
 490 .  nr @old_indent \\n(.i
 491 .  ad l
 492 .  in +\w'\fB\\*[@1]\0'u
 493 .  ti \\n[@old_indent]u
 494 .  B \\*[@1]\0\c
 495 .  rr @old_indent
 496 .  rm @1
 497 .  nr groffer:Synopsis.level +1\"        marker for ./Synopsis
 498 ..
 499 .c  --------------------------------------------------------------------
 500 .c ./Synopsis  ()
 501 .c
 502 .c Close a synopsis section opened by the previous .Synopsis macro.
 503 .c
 504 .de /Synopsis
 505 .  if (\\n[groffer:Synopsis.level] <= 0) \
 506 .    Error .\\$0: no previous call of .Synopsis
 507 .  br
 508 .  ad
 509 .  in
 510 .  hy
 511 .  nr groffer:Synopsis.level -1
 512 ..
 513 .c  --------------------------------------------------------------------
 514 .c .Text  (<text>...)
 515 .c
 516 .c Treat the arguments as text, no matter how they look.
 517 .c
 518 .de Text
 519 .  if (\\n[.$] == 0) \
 520 .    return
 521 .  nop \)\\$*\)
 522 ..
 523 .c --------------------------------------------------------------------
 524 .c .Topic  ([<indent>])
 525 .c
 526 .c A bulleted paragraph
 527 .c
 528 .de Topic
 529 .  ie (\\n[.$] = 0) \
 530 .    ds @indent 2m\"
 531 .  el \
 532 .    ds @indent \\$1\"
 533 .  TP \\*[@indent]
 534 .  Text \[bu]
 535 .  rm @indent
 536 ..
 537 .c --------------------------------------------------------------------
 538 .c .TP+  ()
 539 .c
 540 .c Continuation line for .TP header.
 541 .c
 542 .de TP+
 543 .  br
 544 .  ns
 545 .  TP \\$1
 546 ..
 547 .c --------------------------------------------------------------------
 548 .c .TP_header  ([<indent>])
 549 .c
 550 .c Start a multi-line header for a .TP-like paragraph
 551 .c
 552 .de TP_header
 553 .  if (\\n[groffer:TP.level] < 0) \
 554 .    Error .\\$0: wrong level.
 555 .  nr groffer:TP.level +1
 556 .  P
 557 .  ie (\\n[.$] == 0) \
 558 .    rr groffer:TP.indent
 559 .  el \
 560 .    nr groffer:TP.indent \\$1
 561 .  nr groffer:TP_header.flag 1
 562 ..
 563 .c --------------------------------------------------------------------
 564 .c .TP_body  ([<indent>])
 565 .c
 566 .c End a previous .TP-header and beging the body of the paragraph.
 567 .c
 568 .de TP_body
 569 .  if !rgroffer:TP_header.flag \
 570 .    Error .\\$0: no previous call of .TP_header
 571 .  if (\\n[groffer:TP.level] <= 0) \
 572 .    Error .\\$0: wrong level.
 573 .  br
 574 .  ie (\\n[.$] == 0) \{\
 575 .    ie rgroffer:TP.indent \{\
 576 .      RS \\n[groffer:TP.indent]u
 577 .    \}
 578 .    el \
 579 .      RS
 580 .  \}
 581 .  el \
 582 .    RS \\$1u
 583 .  rr groffer:TP.indent
 584 .  rr groffer:TP_header.flag
 585 .  nr groffer:TP_body.flag 1
 586 ..
 587 .c --------------------------------------------------------------------
 588 .c TP_end  ()
 589 .c
 590 .c End of former .TP_body paragraph.
 591 .c
 592 .de TP_end
 593 .  if !rgroffer:TP_body.flag \
 594 .    Error .\\$0: no previous .TP_body.
 595 .  if (\\n[groffer:TP.level] <= 0) \
 596 .    Error TP_end: wrong level.
 597 .  nr groffer:TP.level -1
 598 .  rr grogger:TP.indent
 599 .  rr groffer:TP_header.flag
 600 .  rr groffer:TP_body.flag
 601 .  br
 602 .  RE
 603 ..
 604 .
 605 .\" End of macro definitions
 606 .
 607 .
 608 .\" --------------------------------------------------------------------
 609 .\" SH "SYNOPSIS"
 610 .\" --------------------------------------------------------------------
 611 .
 612 .ad l
 613 .Synopsis groffer
 614 .RI [ viewing_options ]
 615 .RI [ man_options ]
 616 .RI [ groff_options ]
 617 .Opt_[--]
 618 .RI [ "filespec" "\*[Ellipsis]]"
 619 ./Synopsis
 620 .
 621 .Synopsis groffer
 622 .Opt_alt - h -- help
 623 ./Synopsis
 624 .
 625 .Synopsis groffer
 626 .Opt_alt - v -- version
 627 ./Synopsis
 628 .
 629 .
 630 .TP
 631 .I viewing_options
 632 These options determine and configure the display mode.
 633 .
 634 They were synchronized with the options of both
 635 .BR groff (@MAN1EXT@)
 636 and GNU
 637 .BR man (1).
 638 As groff uses almost any letter in its option set, only long option
 639 names are available for most features.
 640 .
 641 If none of these options is used groffer tries to find a suitable
 642 display mode automatically.
 643 .
 644 .
 645 .RS
 646 .
 647 .P
 648 .Opt_[alt] - Q -- source
 649 .Opt_[alt] - T -- device device
 650 .Opt_[alt] -- auto-modes mode1,mode2,\*[Ellipsis]
 651 .Opt_[alt] -- debug
 652 .Opt_[alt] -- default
 653 .Opt_[alt] -- dvi
 654 .Opt_[alt] -- dvi-viewer prog
 655 .Opt_[alt] -- groff
 656 .Opt_[alt] -- location
 657 .Opt_[alt] -- mode display_mode
 658 .Opt_[alt] -- pager program
 659 .Opt_[alt] -- pdf
 660 .Opt_[alt] -- pdf-viewer prog
 661 .Opt_[alt] -- ps
 662 .Opt_[alt] -- ps-viewer prog
 663 .Opt_[alt] -- shell
 664 .Opt_[alt] -- tty
 665 .Opt_[alt] -- www
 666 .Opt_[alt] -- www-viewer prog
 667 .Opt_[alt] -- x
 668 .Opt_[alt] -- x-viewer prog
 669 .
 670 .
 671 .P
 672 The following long options were adapted from the corresponding X
 673 Toolkit options with a single leading minus; see
 674 .BR X (1).
 675 .
 676 .
 677 .P
 678 .Opt_[alt] -- bd
 679 .Opt_[alt] -- bg -- background
 680 .Opt_[alt] -- bw
 681 .Opt_[alt] -- display
 682 .Opt_[alt] -- fg -- foreground
 683 .Opt_[alt] -- ft -- font
 684 .Opt_[alt] -- geometry size_pos
 685 .Opt_[alt] -- resolution value
 686 .Opt_[alt] -- rv
 687 .Opt_[alt] -- title string
 688 .Opt_[alt] -- xrm X_resource
 689 .
 690 .RE
 691 .
 692 .
 693 .TP
 694 .I groff_options
 695 Any combination of (short) options from the
 696 .BR groff (@MAN1EXT@)
 697 program is accepted; the options that are not explicitly handled by
 698 groffer are transparently passed to groff.
 699 .
 700 Due to the automatism in groffer, none of these groff options should
 701 be necessary, except for advanced usage.
 702 .
 703 .
 704 .RS
 705 .
 706 .P
 707 Because of the special outputting behavior of the groff options
 708 .Opt_short V,
 709 .Opt_short X,
 710 and
 711 .Opt_short Z,
 712 groffer was designed to be switched into
 713 .I groff
 714 mode by each of these options; in this mode, the groffer viewing
 715 features are disabled.
 716 .
 717 .P
 718 The other groff options do not switch the mode, but allow to customize
 719 the formatting process.
 720 .
 721 Useful groff formatting options include
 722 .Opt_short m
 723 (to add macro files that cannot be recognized by grog), and
 724 .Opt_short T
 725 (to specify an alternative device for the modes
 726 .I tty
 727 and
 728 .IR x ).
 729 .
 730 .RE
 731 .
 732 .
 733 .TP
 734 .I man_options
 735 These options regulate whether and how man pages are searched.
 736 .
 737 They are compatible with the long options of the
 738 .I GNU man
 739 program.
 740 .
 741 .
 742 .RS
 743 .
 744 .P
 745 .Opt_[alt] -- all
 746 .Opt_[alt] -- ascii
 747 .Opt_[alt] -- apropos
 748 .Opt_[alt] -- ditroff
 749 .Opt_[alt] -- extension suffix
 750 .Opt_[alt] -- locale language
 751 .Opt_[alt] -- local-file
 752 .Opt_[alt] -- man
 753 .Opt_[alt] -- manpath dir1:dir2:\*[Ellipsis]
 754 .Opt_[alt] -- no-location
 755 .Opt_[alt] -- no-man
 756 .Opt_[alt] -- sections sec1:sec2:\*[Ellipsis]
 757 .Opt_[alt] -- systems sys1,sys2,\*[Ellipsis]
 758 .Opt_[alt] -- troff-device device
 759 .Opt_[alt] -- whatis
 760 .
 761 .
 762 .P
 763 The GNU
 764 .I man
 765 long options that are not mentioned are recognized, but they are just
 766 ignored because of alternative implementations.
 767 .
 768 The full set of long and short options of the GNU man program can be
 769 passed via the environment variable
 770 .Env_var $MANOPT ;
 771 see
 772 .BR man (1)
 773 if your system has GNU man installed.
 774 .
 775 .RE
 776 .
 777 .
 778 .TP
 779 .I filespec
 780 is a sequence of file names or templates for searching
 781 man\~pages, see
 782 .BR man (1).
 783 A
 784 .I filespec
 785 can have one of the following forms.
 786 .
 787 .
 788 .RS
 789 .
 790 .TP 10m
 791 .I filename
 792 the path name of an existing file.
 793 .
 794 .
 795 .TP
 796 .Opt_short
 797 stands for standard input (can occur several times).
 798 .
 799 .
 800 .TP
 801 .BI man: name ( section )
 802 search the man\~page
 803 .I name
 804 in section\~\c
 805 .IR section .
 806 .
 807 .
 808 .TP
 809 .BI man: name . section
 810 search the man\~page
 811 .I name
 812 in section\~\c
 813 .IR section .
 814 .
 815 .
 816 .TP
 817 .BI man: name
 818 search the man\~page
 819 .I name
 820 in the lowest available section.
 821 .
 822 .
 823 .TP
 824 .IB name ( section )
 825 search the man\~page
 826 .I name
 827 in section\~\c
 828 .IR section .
 829 .
 830 .
 831 .TP
 832 .IB name . section
 833 search the man\~page
 834 .I name
 835 in section\~\c
 836 .IR section .
 837 .
 838 .
 839 .TP
 840 .I standard_section
 841 if this is `1', \*[Ellipsis], `9', `o', or `n' try to retrieve the
 842 next argument as a man\~page in this section.
 843 .
 844 .
 845 .TP
 846 .I name
 847 search for the man\~page
 848 .I name
 849 in the lowest available section.
 850 .
 851 .
 852 .P
 853 No
 854 .I filespec
 855 parameters means standard input.
 856 .
 857 .RE
 858 .
 859 .
 860 .P
 861 For details on the options, see section
 862 .BR OPTIONS .
 863 .
 864 .
 865 .\" --------------------------------------------------------------------
 866 .SH DESCRIPTION
 867 .\" --------------------------------------------------------------------
 868 .
 869 The
 870 .I groffer
 871 program is part of
 872 .BR groff (@MAN7EXT@).
 873 It can be used to display arbitrary documents written in the
 874 .BR roff (@MAN7EXT@)
 875 formatting language in several different ways, in an X window viewer
 876 program or in a text terminal.
 877 .
 878 The viewer programs can be chosen as the groff native viewer
 879 .BR gxditview (@MAN1EXT@),
 880 a Postcript or dvi display program, or a web browser.
 881 .
 882 .
 883 .P
 884 A search facility for manual pages (
 885 .IR man\~pages )
 886 is provided.
 887 .
 888 Almost the whole functionality of the
 889 .I GNU man
 890 program was provided or suitably adapted.
 891 .
 892 This makes the groffer program a valuable tool on systems with a poor
 893 .I man
 894 system.
 895 .
 896 .
 897 .P
 898 The program always concatenates all input specified by the non-option
 899 parameters of the calling command line or standard input.
 900 .
 901 Compressed standard input or files are decompressed on-the-fly.
 902 .
 903 .
 904 .P
 905 Normally, the input is run through the
 906 .BR groff (@MAN1EXT@)
 907 text processor before being displayed.
 908 .
 909 By using the option
 910 .Opt_short Q ,
 911 the roff source code is displayed without formatting.
 912 .
 913 .
 914 .P
 915 The formatting process can be regulated by all options that are
 916 available groff.
 917 .
 918 By using the
 919 .Opt_short T
 920 option, groffer can be switched to behave exactly like groff without
 921 using its viewer facilities, but additionally with the search and
 922 decompression features.
 923 .
 924 .
 925 .P
 926 All necessary options can be determined automatically.
 927 .
 928 For example, the groffer program internally uses the
 929 .BR grog (@MAN1EXT@)
 930 program to determine from the unformatted document which preprocessors
 931 should be run and which macro files should be included.
 932 .
 933 But all parts of the program can be controlled manually by suitable
 934 options.
 935 .
 936 .
 937 .\" --------------------------------------------------------------------
 938 .SH OPTIONS
 939 .\" --------------------------------------------------------------------
 940 .
 941 The groffer program provides its own parser for command line options
 942 that is compatible to both POSIX
 943 .BR getopts (1)
 944 and GNU
 945 .BR getopt (1).
 946 The command line behaves as usually.
 947 .
 948 For completeness, the details are provided here.
 949 .
 950 .
 951 .\" --------------------------------------------------------------------
 952 .SS "Option Parsing"
 953 .\" --------------------------------------------------------------------
 954 .
 955 The following types of options are supported, equally on all systems
 956 that are able to run the groffer program:
 957 .
 958 .
 959 .Topic
 960 single character options are always preceded by a single minus
 961 character, for example,
 962 .Opt_short c .
 963 .
 964 .
 965 .Topic
 966 the argument for a single character option is the next command line
 967 argument, for example,
 968 .Opt_alt - o\~ arg ,
 969 or can be appended to the option character within the same argument
 970 .Opt_alt - o arg .
 971 .
 972 .
 973 .Topic
 974 clusters of such single character options without an argument,
 975 eventually terminated by a single character option with an argument;
 976 for example,
 977 .Opt_alt - abo arg
 978 is equivalent to
 979 .Opt_short a\~\c
 980 .Opt_short b\~\c
 981 .Opt_short o\~\c
 982 .I arg .
 983 .
 984 .
 985 .Topic
 986 Long options, that means option with names longer than one character
 987 are always prededed by a double minus; an option argument can either
 988 go to the next command line argument or be appended with an equal sign
 989 to the argument; for example,
 990 .Opt_alt -- long= arg
 991 is equivalent to
 992 .Opt_alt -- long\~ arg .
 993 .
 994 .
 995 .Topic
 996 An argument of
 997 .Opt_--
 998 ends option parsing; all further command line arguments are
 999 interpreted as filespec arguments.
1000 .
1001 .
1002 .Topic
1003 By default, all command line arguments that are neither options nor
1004 option arguments are interpreted as filespec parameters and stored
1005 until option parsing has finished.
1006 .
1007 For example, the command line
1008 .Shell_cmd "groffer file1 -a -o arg file 2"
1009 is, by default, equivalent to
1010 .Shell_cmd "groffer -a -o arg -- file1 file 2"
1011 .
1012 .
1013 .Topic
1014 This behavior can be changed by setting the environment variable
1015 .Env_var $POSIXLY_CORRECT
1016 to a non-empty value; in this case, option processing is stopped as
1017 soon as the first non-option argument is found.
1018 .
1019 For example, in posixly correct mode, the command line
1020 .Shell_cmd "groffer file1 -a -o arg file 2"
1021 is equivalent to
1022 .Shell_cmd "groffer -- file1 -a -o arg file 2"
1023 As this leads to unwanted behavior in most cases, most people do not
1024 want to set
1025 .Env_var $POSIXLY_CORRECT .
1026 .
1027 .
1028 .\" --------------------------------------------------------------------
1029 .SS "Compatibility with Options from other Programs"
1030 .\" --------------------------------------------------------------------
1031 .
1032 All short options of
1033 .I groffer
1034 are compatible with the short options of
1035 .BR groff (@MAN1EXT@).
1036 .
1037 Some of the
1038 .I groff
1039 options were given a special meaning within
1040 .IR groffer .
1041 .
1042 All other
1043 .I groff
1044 options are supported by
1045 .IR groffer ,
1046 but they are just transparently transferred to
1047 .I groff
1048 without any intervention.
1049 .
1050 Therefore these transparent options are not documented here, but in
1051 .BR groff (@MAN1EXT@).
1052 .
1053 .
1054 .P
1055 All long options of
1056 .I groffer
1057 are compatible with the long options of
1058 .BR man (1).
1059 .
1060 Most of the
1061 .I man
1062 long options were implemented as native options into
1063 .IR groffer .
1064 .
1065 These options are documented in the following; the other
1066 .I man
1067 options are recognized, but ignored.
1068 .
1069 .
1070 .\" --------------------------------------------------------------------
1071 .SS "Native groffer Options"
1072 .\" --------------------------------------------------------------------
1073 .
1074 .Opt_def - h
1075 Print usage message to standard error and exit.
1076 .
1077 .
1078 .Opt_def - Q
1079 Output the roff source code of the input files unprocessed.
1080 .
1081 This is the equivalent
1082 .Opt_long mode\~source .
1083 .
1084 .
1085 .Opt_def - T devname
1086 Switch to
1087 .Opt_long mode\~device ,
1088 .
1089 thus disabling the
1090 .I groffer
1091 viewing.
1092 .
1093 Instead, the input is formatted and postprocessed using plain
1094 .I groff
1095 with
1096 .I devname
1097 as the output device.
1098 .
1099 The allowed device names are listed in
1100 .BR groff (@MAN1EXT@).
1101 .
1102 Note that this forces all device names that begin with the letter
1103 .I X
1104 to be displayed with
1105 .BR gxditview (@MAN1EXT@);
1106 all other device names generate output for the specified device; this
1107 is printed onto standard output without a pager.
1108 .
1109 .
1110 .Opt_def - v
1111 Print version information onto standard error.
1112 .
1113 .
1114 .Opt_def - V
1115 Switch into
1116 .I groff
1117 mode and format the input with groff option
1118 .Opt_short V ;
1119 this produces the groff calling pipe without formatting the input.
1120 .
1121 This an advanced option from
1122 .BR groff (@MAN1EXT@) ,
1123 only useful for debugging.
1124 .
1125 .
1126 .Opt_def - X
1127 Switch into
1128 .I groff
1129 mode and format the input with groff option
1130 .Opt_short X ;
1131 actually, this formats the input and displays it with
1132 .BR gxditview (@MAN1EXT@) .
1133 .
1134 This differs from groffer's mode
1135 .I x
1136 because groffer's viewer options are not used, but the viewer is
1137 configured like in groff with the groff option
1138 .Opt_short P .
1139 This option is inhereted from
1140 .BR groff (@MAN1EXT@) .
1141 .
1142 .
1143 .Opt_def - Z
1144 Switch into
1145 .I groff
1146 mode and format the input with groff option
1147 .Opt_short Z ;
1148 this produces the groff intermediate output without postprocessing; see
1149 .BR groff_out (@MAN1EXT@) .
1150 This an advanced option from
1151 .BR groff (@MAN1EXT@) ,
1152 useful for debugging.
1153 .
1154 .
1155 .Opt_def -- all
1156 In searching man pages, retrieve all suitable ones instead of only one.
1157 .
1158 .
1159 .Opt_def -- apropos
1160 Instead of displaying, start the `apropos' command for searching
1161 within man page descriptions; only kept for compatibility with `man'.
1162 .
1163 .
1164 .Opt_def -- auto-modes mode1,mode2,\*[Ellipsis]
1165 Set the sequence of modes for default mode to the comma separated list
1166 given in the argument.
1167 .
1168 .
1169 .Opt_def -- background color
1170 This is equivalent to
1171 .Opt_long bg .
1172 .
1173 .
1174 .Opt_def -- bd pixels
1175 Specifies the color of the border surrounding the viewer
1176 window.
1177 .
1178 This is an adaption of the X Toolkit option
1179 .Opt_short bd .
1180 .
1181 The argument is an X color name, see
1182 .BR (1)
1183 for details.
1184 .
1185 .
1186 .Opt_def -- bg color
1187 Set the background color of the viewer window.
1188 .
1189 This is an adaption of the X Toolkit option
1190 .Opt_short bg .
1191 .
1192 The argument is an X color name, see
1193 .BR (1)
1194 for details.
1195 .
1196 .
1197 .Opt_def -- bw pixels
1198 Specifies the width in pixels of the border surrounding the viewer
1199 window (not available for all viewers).
1200 .
1201 This is an adaption of the X Toolkit option
1202 .Opt_short bw .
1203 .
1204 .
1205 .Opt_def -- debug
1206 Print debugging information.
1207 .
1208 Actually, a function call stack is printed if an error occurs.
1209 .
1210 .
1211 .Opt_def -- default
1212 Reset all configuration from previously processed command line options
1213 to the default values.
1214 .
1215 This is useful to wipe out all effects of former options and restart
1216 option processing using only the rest of the command line.
1217 .
1218 .
1219 .Opt_def -- device
1220 Eqivalent to
1221 .Opt_short T .
1222 .
1223 .
1224 .Opt_def -- display X-display
1225 Set the X display on which the viewer program shall be started, see
1226 .BR X (1)
1227 for the syntax of the argument.
1228 .
1229 .
1230 .Opt_def -- ditroff
1231 Eqivalent to
1232 .Opt_short Z .
1233 This is kept for compatibiliy with GNU
1234 .BR man (1).
1235 .
1236 .
1237 .Opt_def -- dvi
1238 Choose dvi mode; the formatted input is displayed with the
1239 by default, the formatted input is displayed with the
1240 .BR xdvi (1)
1241 program.
1242 .
1243 .
1244 .Opt_def -- dvi-viewer prog
1245 Set the viewer program for dvi mode.
1246 .
1247 This can be a file name or a program to be searched in
1248 .Env_var $PATH .
1249 .
1250 Known dvi viewers inlude
1251 .BR xdvi (1)
1252 and
1253 .BR dvilx (1)
1254 .
1255 In each case, arguments can be provided additionally.
1256 .
1257 .
1258 .Opt_def -- extension suffix
1259 Restrict man\~page search to file names that have
1260 .I suffix
1261 appended to their section element.
1262 .
1263 For example, in the file name
1264 .I /usr/share/man/man3/terminfo.3ncurses.gz
1265 the man\~page extension is
1266 .IR ncurses .
1267 .
1268 Originates from GNU
1269 .IR man .
1270 .
1271 .
1272 .Opt_def -- foreground color
1273 This is equivalent to
1274 .Opt_short fg .
1275 .
1276 .
1277 .Opt_def -- fg color
1278 Set the foreground color of the viewer window.
1279 .
1280 This is an adaption of the X Toolkit option
1281 .Opt_short bg .
1282 .
1283 The argument is an X color name, see
1284 .BR (1)
1285 for details.
1286 .
1287 .
1288 .Opt_def -- font font_name
1289 This is equivalent to
1290 .Opt_short ft .
1291 .
1292 .
1293 .Opt_def -- ft font_name
1294 Set the font used by the viewer window.
1295 .
1296 This is an adaption of the X Toolkit option
1297 .Opt_short ft .
1298 .
1299 The argument is an X font name, see
1300 .BR (1)
1301 for details.
1302 .
1303 .
1304 .Opt_def -- geometry size_pos
1305 Set the geometry of the display window, that means its size and its
1306 starting position.
1307 .
1308 See
1309 .BR X (1)
1310 for details on the syntax of the argument.
1311 .
1312 If the actual display mode is not X then this option is ignored.
1313 .
1314 .
1315 .Opt_def -- groff
1316 Set
1317 .I groff
1318 mode.
1319 .
1320 Switch groffer to process the input like
1321 .BR groff (@MAN1EXT@).
1322 .
1323 This disables the groffer viewing features, all groffer viewing
1324 options are ignored.
1325 .
1326 .
1327 .Opt_def -- help
1328 Eqivalent to
1329 .Opt_short h .
1330 .
1331 .
1332 .Opt_def -- location
1333 Print the location of the retrieved files to standard error.
1334 .
1335 .
1336 .Opt_def -- locale language
1337 .
1338 Set the language for man pages.
1339 .
1340 This option originates from GNU
1341 .BR man (1).
1342 .
1343 .
1344 .Opt_def -- man
1345 Check the non-option command line arguments (filespecs) first on being
1346 man\~pages, then whether they represent an existing file.
1347 .
1348 By default, a filespec is first tested if it is an existing file.
1349 .
1350 .
1351 .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'"
1352 Use the specified search path for retrieving man\~pages instead of the
1353 program defaults.
1354 .
1355 If the argument is set to the empty string "" the search for man\~page
1356 is disabled.
1357 .
1358 .
1359 .Opt_def -- mode value
1360 .
1361 Set the display mode.
1362 .
1363 The following mode values are recognized:
1364 .
1365 .
1366 .RS
1367 .
1368 .
1369 .TP
1370 .B auto
1371 Display in the default manner; this actually means to try the modes
1372 .IR ps ,
1373 .IR x ,
1374 and
1375 .I tty
1376 in this sequence.
1377 .
1378 Useful for restoring default mode when a different mode was specified
1379 with
1380 .Env_var $GROFFER_OPT .
1381 .
1382 .
1383 .TP
1384 .B dvi
1385 Display formatted input in a dvi viewer program; equivalent to
1386 .Opt_long dvi .
1387 .
1388 .
1389 .TP
1390 .B pdf
1391 Display formatted input in a PDF (Portable Document Format) viewer
1392 program; equivalent to
1393 .Opt_long pdf .
1394 .
1395 .
1396 .TP
1397 .B ps
1398 Display formatted input in a Postscript viewer program; equivalent to
1399 .Opt_long ps .
1400 .
1401 .
1402 .TP
1403 .B tty
1404 Display formatted input in a text terminal; equivalent to
1405 .Opt_long tty .
1406 .
1407 .
1408 .TP
1409 .B www
1410 Display formatted input in a internet browser program; equivalent to
1411 .Opt_long www .
1412 .
1413 .
1414 .TP
1415 .B x
1416 Display formatted input in a native roff viewer such as
1417 .BR gxditview (@MAN1EXT@); equivalent to
1418 .Opt_long x .
1419 .
1420 .
1421 .P
1422 The following modes do not use the
1423 .I groffer
1424 viewing features.
1425 .
1426 They are only interesting for advanced applications.
1427 .
1428 .
1429 .TP
1430 .B groff
1431 Generate device output with plain
1432 .I groff
1433 without using the special viewing features of
1434 .IR groffer .
1435 If no device was specified by option
1436 .Opt_short T
1437 the
1438 .I groff
1439 default
1440 .B ps
1441 is assumed.
1442 .
1443 .
1444 .TP
1445 .B source
1446 Display source code; same as
1447 .Opt_short Q .
1448 .
1449 .
1450 .RE
1451 .
1452 .
1453 .Opt_def -- no-location
1454 Do not display the location of retireved files; this resets a former
1455 call to
1456 .Opt_long location .
1457 .
1458 .
1459 .Opt_def -- no-man
1460 Do not check for man\~pages.
1461 .
1462 .
1463 .Opt_def -- pager
1464 Set the pager program in tty mode; default is
1465 .IR less .
1466 .
1467 .
1468 .Opt_def -- pdf
1469 Choose pdf mode (Portable Document Format).
1470 .
1471 By default, the input is formatted by groff using the Postscript
1472 device, then it is transformed into the PDF file format using
1473 .BR gs (1)
1474 (this is quite slow), and finally displayed either with the
1475 .BR xpdf (1)
1476 or the
1477 .BR acroread (1)
1478 program; this can be configured with option
1479 .Opt_long viewer-pdf .
1480 .
1481 PDF has a big advantage because the text is displayed graphically and
1482 is searchable nevertheless; but as thtransformation into pdf takes a
1483 considerable amount of time, the pdf mode is not suitable as a default
1484 device for the auto mode.
1485 .
1486 The only device that is compatible to this mode is
1487 .IR ps ,
1488 which is also the default when no device is specified.
1489 .
1490 .
1491 .Opt_def -- pdf-viewer prog
1492 Set the viewer program for
1493 .I pdf
1494 mode.
1495 .
1496 This can be a file name or a program to be searched in
1497 .Env_var $PATH .
1498 .
1499 In each case, arguments can be provided additionally.
1500 .
1501 .
1502 .Opt_def -- ps
1503 Choose ps mode (Postscript).
1504 .
1505 By default, the formatted input is displayed with the
1506 .BR ghostview (@MAN1EXT@)
1507 program; this can be configured with option
1508 .Opt_long viewer-ps .
1509 .
1510 The only device that is compatible to this mode is
1511 .IR ps ,
1512 which is also the default when no device is specified.
1513 .
1514 .
1515 .Opt_def -- ps-viewer prog
1516 Set the viewer program for
1517 .I ps
1518 mode.
1519 .
1520 This can be a file name or a program to be searched in
1521 .Env_var $PATH .
1522 .
1523 Common Postscript viewers inlude
1524 .BR gv (1),
1525 .BR ghostview (1),
1526 and
1527 .BR gs (1),
1528 .
1529 In each case, arguments can be provided additionally.
1530 .
1531 .
1532 .Opt_def -- resolution value
1533 Set X resolution in dpi (dots per inch) in some viewer programs.
1534 .
1535 The only supported dpi values are
1536 .B 75
1537 and
1538 .BR 100 .
1539 This is an adaption of the X Toolkit option
1540 .Opt_short resolution .
1541 .
1542 .
1543 .Opt_def -- rv
1544 Reverse foreground and background color of the viewer window.
1545 .
1546 This is an adaption of the X Toolkit option
1547 .Opt_short rv .
1548 This feature is not available in all viewer programs.
1549 .
1550 .
1551 .Opt_def -- sections
1552 Restrict searching for man pages to the given
1553 .IR sections ,
1554 a colon-separated list.
1555 .
1556 .
1557 .Opt_def -- shell "shell_program"
1558 Specify the shell under which the groffer script should be run.
1559 .
1560 The script first tests whether this option is set (either within
1561 .Env_var $GROFF_OPT
1562 or as a command line option); if so, the script is rerun under the
1563 shell program specified with the option argument.
1564 .
1565 .
1566 .Opt_def -- source
1567 Equivalent to
1568 .Opt_short Q .
1569 .
1570 .
1571 .Opt_def -- systems
1572 Search for man pages for the given operating systems; the argument
1573 .I systems
1574 is a comma-separated list.
1575 .
1576 .
1577 .Opt_def -- title "'some text'"
1578 Set the title for the viewer window.
1579 .
1580 This feature is not available in all viewer programs.
1581 .
1582 .
1583 .Opt_def -- to-postproc opt_or_arg
1584 Eqivalent to
1585 .Opt_short P .
1586 .
1587 .
1588 .Opt_def -- troff-device
1589 Eqivalent to
1590 .Opt_short T .
1591 This option is only kept for compatibility with GNU
1592 .BR man (1).
1593 .
1594 .
1595 .Opt_def -- tty
1596 Choose tty display mode, that means displaying in a text pager even
1597 when in X; eqivalent to
1598 .Opt_long mode\~tty .
1599 .
1600 .
1601 .Opt_def -- version
1602 Eqivalent to
1603 .Opt_short v .
1604 .
1605 .
1606 .Opt_def -- whatis
1607 Instead of displaying the content, get the one-liner description from
1608 the retrieved man page files \[em] or say that it is not a man page.
1609 .
1610 .
1611 .Opt_def -- where
1612 Eqivalent to
1613 .Opt_long location .
1614 .
1615 .
1616 .Opt_def -- www
1617 Choose www mode (html), display in a web browser program, which can be
1618 specified with option
1619 .Opt_long www-viewer .
1620 By default, the existence of a sequence of standard web browsers is
1621 tested, starting with
1622 .BR mozilla (1)
1623 and
1624 .BR netscape (1)
1625 .
1626 .
1627 .Opt_def -- www-viewer prog
1628 Set the web browser program for viewing in
1629 .I www
1630 mode.
1631 .
1632 Each program that accepts html input and allows the
1633 .BI file://localhost/ dir / file
1634 syntax on the command line is suitable; it can be the path name of an
1635 executable file or a program in
1636 .Env_var $PATH .
1637 .
1638 In each case, arguments can be provided additionally.
1639 .
1640 .
1641 .Opt_def -- x
1642 Choose
1643 .I x
1644 mode (view in X roff viewer).
1645 .
1646 By default, the formatted input is displayed with the
1647 .BR gxditview (@MAN1EXT@)
1648 program, being distributed together with groff, or with
1649 .BR xditview (1),
1650 which is distributed as a standard X tool.
1651 .
1652 This can be configured with option
1653 .Opt_long x-viewer .
1654 .
1655 The only devices (option
1656 .Opt_short T )
1657 that are compatible with this mode are
1658 .IR X75 ,
1659 .IR X100 ,
1660 .IR X75-12 ,
1661 .IR X100-12 ,
1662 and
1663 .I ps
1664 (the default device).
1665 .
1666 .
1667 .Opt_def -- x-viewer prog
1668 Set the viewer program for
1669 .I x
1670 mode.
1671 .
1672 Suitable viewer programs are
1673 .BR gxditview (@MAN1EXT@)
1674 and
1675 .BR xditview (1).
1676 .
1677 But the argument can be any executable file or a program in
1678 .Env_var $PATH .
1679 .
1680 In each case, arguments can be provided additionally.
1681 .
1682 .
1683 .TP
1684 .Opt_--
1685 Signals the end of option processing; all remaining arguments are
1686 interpreted as
1687 .I filespec
1688 parameters.
1689 .
1690 .
1691 .P
1692 Besides these, groffer accepts all arguments that are valid for the
1693 .BR groff (@MAN1EXT@)
1694 program.
1695 .
1696 All non-groffer options are sent unmodified via grog to groff.
1697 .
1698 Postprocessors, macro packages, compatibility with classical troff,
1699 and much more can be manually specified.
1700 .
1701 .
1702 .\" --------------------------------------------------------------------
1703 .SH "OUTPUT MODES"
1704 .\" --------------------------------------------------------------------
1705 .
1706 By default, the groffer program formats the input and then
1707 automatically chooses a suitable display mode, but the user can also
1708 choose between the following modes:
1709 .
1710 .Topic
1711 graphically display the formatted input with an X window program,
1712 including
1713 .
1714 .RS
1715 .Topic
1716 with X window roff viewers such as
1717 .BR gxditview (@MAN1EXT@)
1718 .RI ( x
1719 mode),
1720 .
1721 .Topic
1722 in a dvi viewer program
1723 .RI ( dvi
1724 mode),
1725 .
1726 .Topic
1727 in a Postscript viewer
1728 .RI ( ps
1729 mode),
1730 .
1731 .Topic
1732 in a PDF viewer
1733 .RI ( pdf
1734 mode),
1735 .
1736 .Topic
1737 in a web browser
1738 .RI ( www
1739 mode),
1740 .RE
1741 .
1742 .Topic
1743 display formatted input in a pager on the text terminal
1744 .RI ( tty
1745 mode),
1746 .
1747 .Topic
1748 run groffer like groff, but with decompression and man\~page searching
1749 .RI ( groff
1750 mode); this includes things like generating the groff intermediate
1751 output.
1752 .
1753 .Topic
1754 stream the unformatted source code of the input onto standard output
1755 .RI ( source
1756 mode),
1757 .
1758 .
1759 .P
1760 By
1761 .IR default ,
1762 .I groffer
1763 first tries whether
1764 .B x
1765 mode is possible, then
1766 .B ps
1767 mode, and finally
1768 .B tty
1769 mode.
1770 .
1771 This mode testing sequence for
1772 .B default
1773 mode can be changed by specifying a comma separated list of modes
1774 with the option
1775 .Opt_long default-modes.
1776 .
1777 .
1778 .P
1779 The searching for man\~pages and the decompression of the input are
1780 active in every mode.
1781 .
1782 .
1783 .\" --------------------------------------------------------------------
1784 .SS "Graphical Display Modes"
1785 .\" --------------------------------------------------------------------
1786 .
1787 The graphical display modes work only in the X window environment (or
1788 similar implementations within other windowing environments).
1789 .
1790 The environment variable
1791 .Env_var $DISPLAY
1792 or the option
1793 .Opt_long display
1794 are used for specifying the X display to be used; if neither is
1795 specified, groffer assumes that no X is running.
1796 .
1797 .
1798 .P
1799 A certain graphical display mode can be selected by one of the options
1800 .Opt_long dvi ,
1801 .Opt_long pdf ,
1802 .Opt_long ps ,
1803 .Opt_short X ,
1804 and
1805 .Opt_long www .
1806 .
1807 By default, some graphical modes are tried first.  If none succeeds
1808 groffer switches to
1809 .B tty
1810 mode.
1811 .
1812 .
1813 .P
1814 The graphical modes can be customized by options that were named
1815 according to the resource options in the
1816 .BR X (1)
1817 Toolkit but using a leading double minus instead of the single minus
1818 used by X.
1819 .
1820 These include
1821 .Opt_long background ,
1822 .Opt_long foreground ,
1823 .Opt_long geometry ,
1824 .Opt_long resolution ,
1825 .Opt_long title ,
1826 .Opt_long xrm ,
1827 etc.
1828 .
1829 .
1830 .P
1831 The
1832 .I pdf
1833 mode has a major advantage \[em] it is the only graphical diplay mode
1834 that allows to search for text within the viewer; this can be a really
1835 important feature.
1836 .
1837 Unfortunately, it takes a long time to transform the input into the
1838 PDF format, so it was not chosen as the major mode.
1839 .
1840 You can change this by the options
1841 .Opt_long pdf
1842 and
1843 .Opt_long auto-modes .
1844 .
1845 .
1846 .\" --------------------------------------------------------------------
1847 .SS "Displaying on a tty"
1848 .\" --------------------------------------------------------------------
1849 .
1850 If the variable
1851 .Env_var $DISPLAY
1852 is not set or empty, groffer assumes that it should produce output on
1853 a text terminal.
1854 .
1855 This mode can also be forced by option
1856 .Opt_long tty .
1857 .
1858 .
1859 .P
1860 In the actual implementation, the groff output device
1861 .I latin1
1862 is chosen and the processed output is piped into a pager program.
1863 .
1864 This can be changed by specifying option
1865 .Opt_long tty-device .
1866 .
1867 .
1868 .P
1869 The pager to be used can be specified by option
1870 .Opt_long pager
1871 by the environment variable
1872 .Env_var $PAGER .
1873 If this is not set or empty the
1874 .BR less (1)
1875 program is used as the default pager.
1876 .
1877 .
1878 .\" --------------------------------------------------------------------
1879 .SS "Non-displaying Modes"
1880 .\" --------------------------------------------------------------------
1881 .
1882 There are some special modes that do not display the formatted output
1883 in a viewer program.
1884 .
1885 These modes are regarded as advanced, they are useful for debugging
1886 purposes.
1887 .
1888 .
1889 .TP
1890 .I source mode
1891 Instead of displaying the formatted output, it is also possible to
1892 have the roff source code streamed onto the standard output.
1893 .
1894 This mode must be requested by one of the options
1895 .Opt_short Q
1896 or
1897 .Opt_long source .
1898 .
1899 .
1900 .TP
1901 .I groff mode
1902 This mode disables the groffer viewing facilities.
1903 .
1904 The input is handled as usual with decompression and man\~page
1905 searching, but then it is passed to groff using only the options
1906 provided by groff.
1907 .
1908 This enables the user to save the generated output into a file or pipe
1909 it into another program.
1910 .
1911 In this mode, the input is formatted, but not postprocessed; see
1912 .BR groff_out (@MAN5EXT@)
1913 for details.
1914 .
1915 This mode is activated automatically by the three groff options
1916 .Opt_short V
1917 (print roff pipe, no formatting),
1918 .Opt_short X
1919 (display with gxditview in groff's native way, using
1920 .Opt_short P
1921 for customization), and
1922 .Opt_short Z
1923 (disable post-processing, thus producing the groff intermediate output).
1924 .
1925 .
1926 .\" --------------------------------------------------------------------
1927 .SH "FILE PARAMETERS"
1928 .\" --------------------------------------------------------------------
1929 .
1930 The non-option command line parameters determine which files should be
1931 displayed.
1932 .
1933 .
1934 .\" --------------------------------------------------------------------
1935 .SS "Filespecs"
1936 .\" --------------------------------------------------------------------
1937 .
1938 The default behavior of groffer is to first test whether the file
1939 parameter is represents a local file; if not, it is assumed to
1940 represent a filespec for searching one or more man\~page.
1941 .
1942 This behavior can be modified by options.
1943 .
1944 .
1945 .TP
1946 .Opt_long man
1947 forces to interpret all file parameters as filespecs for searching
1948 man\~pages.
1949 .
1950 .TP
1951 .Opt_long no-man
1952 .TP+
1953 .Opt_long local-file
1954 disable the man searching; so only local files are displayed.
1955 .
1956 .
1957 .P
1958 The following parameter formats are recognized to represent a wanted
1959 man\~page.
1960 .
1961 .
1962 .TP
1963 .BI man: name ( section )
1964 the quasi-URL notation used in many Desktop systems to
1965 represent the man\~page
1966 .I name
1967 in
1968 .IR section .
1969 .
1970 .
1971 .TP
1972 .BI man: name
1973 search the man\~page
1974 .I name
1975 in the lowest section.
1976 The corresponding command with the man program would be
1977 .Shell_cmd man\~ name
1978 .
1979 .
1980 .TP
1981 .IB name . section
1982 the man\~page
1983 .I name
1984 in
1985 .IR section .
1986 The corresponding command with the man program would be
1987 .Shell_cmd man\~ section\~name
1988 .
1989 .
1990 .TP
1991 .I name
1992 if
1993 .I name
1994 is not an existing file search for the man\~page
1995 .I name
1996 in the lowest section just like
1997 .Shell_cmd man\~ name
1998 .
1999 .
2000 .TP
2001 .I section name
2002 Even this curious construct known from the various
2003 .I man
2004 programs is handled.
2005 .
2006 For example,
2007 .Shell_cmd "groffer 7 groff"
2008 was modelled according to
2009 .Shell_cmd "man 7 groff"
2010 retrieves the man\~page named
2011 .I groff
2012 in section 7.
2013 .
2014 Only a few standard section names are accepted, being actually the
2015 number sections
2016 .I 1, 2, 3, 4, 5, 6, 7, 8,
2017 and
2018 .IR 9,
2019 and the lower case letters
2020 .I `o'
2021 and
2022 .IR `n' .
2023 .
2024 .
2025 .P
2026 If neither a local file nor a man\~page was retrieved for some file
2027 parameter a warning is issued on standard error, but processing is
2028 continued.
2029 .
2030 .
2031 .\" --------------------------------------------------------------------
2032 .SS "Man\~Page Searching"
2033 .\" --------------------------------------------------------------------
2034 .
2035 The groffer program provides a search facility for system manual pages
2036 (man\~pages).
2037 .
2038 All long options, all environment variables, and most of the
2039 functionality of the GNU
2040 .BR man (1)
2041 program were implemented.
2042 .
2043 .
2044 .P
2045 Preformatted man\~pages (cat\~pages) are intentionally excluded from
2046 the search because groffer is a roff program that wants to format by
2047 its own, not spit out stuff that was digested previously by someone
2048 else.
2049 .
2050 With the excellent performance of the actual computers, the
2051 preformatted man\~pages aren't necessary any longer.
2052 .
2053 Due to their inflexible nature, they tend to provoke some trouble with
2054 changing line lengths and different environments in networks.
2055 .
2056 .
2057 .P
2058 The algorithm for retrieving man\~pages uses five search methods.
2059 .
2060 They are successively tried until a method works.
2061 .
2062 .
2063 .Topic
2064 The search path can be manually specified by using the option
2065 .Opt_long manpath .
2066 An empty argument disables the man\~page searching.
2067 .
2068 This overwrites the other methods.
2069 .
2070 .
2071 .Topic
2072 If this is not available the environment variable
2073 .Env_var $MANPATH
2074 is searched.
2075 .
2076 .
2077 .Topic
2078 If this is empty, the program tries to read it from the environment
2079 variable
2080 .Env_var $MANOPT .
2081 .
2082 .Topic
2083 If this does not work, the
2084 .BR manpath (1)
2085 program for determining a path of man directories is tried.
2086 .
2087 .
2088 .Topic
2089 If this does not work a reasonable default path is searched for
2090 man\~pages.
2091 .
2092 .
2093 .P
2094 After this, the path elements for the language (locale) and operating
2095 system specific man\~pages are added to the man\~path; their sequence
2096 is determined automatically.
2097 .
2098 For example, both
2099 .I /usr/share/man/linux/fr
2100 and
2101 .I /usr/share/man/fr/linux
2102 for french linux man\~pages are found.
2103 .
2104 The language and operating system names are determined from both
2105 environment variables and command line options.
2106 .
2107 .
2108 .P
2109 The locale (language) is determined like in GNU man, that is from
2110 highest to lowest precedence:
2111 .Topic
2112 .Opt_long locale
2113 .
2114 .Topic
2115 .Env_var $GROFFER_OPT
2116 .
2117 .Topic
2118 .Env_var $MANOPT
2119 .
2120 .Topic
2121 .Env_var $LCALL
2122 .
2123 .Topic
2124 .Env_var $LC_MESSAGES
2125 .
2126 .Topic
2127 .Env_var $LANG .
2128 .
2129 .
2130 .P
2131 The language locale is usually specified in the POSIX 1003.1 based
2132 format:
2133 .P
2134 \f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\
2135 \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],
2136 .P
2137 but the two-letter code in
2138 .I <language>
2139 is sufficient for most purposes.
2140 .
2141 .
2142 .P
2143 If no man\~pages for a complicated locale are found the country part
2144 consisting of the first two characters (without the `\f[CB]_\f[]',
2145 `\f[CB].\f[]', and `\f[CB],\f[]', parts) of the locale is searched as
2146 well.
2147 .
2148 .
2149 .P
2150 If still not found the corresponding man\~page in the default language
2151 is used instead.
2152 .
2153 As usual, this default can be specified by one of \f[CR]C\f[] or
2154 \f[CR]POSIX\f[].
2155 .
2156 The man\~pages in the default language are usually in English.
2157 .
2158 .
2159 .P
2160 Several operating systems can be given by appending their names,
2161 separated by a comma.
2162 .
2163 This is then specified by the environment variable
2164 .Env_var $SYSTEM
2165 or by the command line option
2166 .Opt_long systems .
2167 The precedence is similar to the locale case above from highest to
2168 lowest precedence:
2169 .
2170 Topic
2171 .Opt_long systems
2172 .
2173 .Topic
2174 .Env_var $GROFFER_OPT
2175 .
2176 .Topic
2177 .Env_var $MANOPT
2178 .
2179 .Topic
2180 .Env_var $SYSTEM .
2181 .
2182 .
2183 .P
2184 When searching for man\~pages this man\~path with the additional
2185 language and system specific directories is used.
2186 .
2187 .
2188 .P
2189 The search can further be restricted by limiting it to certain
2190 sections.
2191 .
2192 A single section can be specified within a filespec, several sections
2193 as a colon-separated list in command line option
2194 .Opt_long sections
2195 or environment variable
2196 .Env_var $MANSECT .
2197 .
2198 When no section was specified a set of standard sections is searched
2199 until a suitable man\~page was found.
2200 .
2201 .
2202 .P
2203 Finally, the search can be restricted to a so-called
2204 .IR extension .
2205 This is a postfix that acts like a subsection.
2206 .
2207 It can be specified by
2208 .Opt_long extension
2209 or environment variable
2210 .Env_var $EXTENSION .
2211 .
2212 .
2213 .P
2214 For further details on man\~page searching, see
2215 .BR man (1).
2216 .
2217 .
2218 .\" --------------------------------------------------------------------
2219 .SS Decompression
2220 .\" --------------------------------------------------------------------
2221 .
2222 The program has a decompression facility.
2223 .
2224 If standard input or a file that was retrieved from the command line
2225 parameters is compressed with a format that is supported by either
2226 .BR gzip (1)
2227 or
2228 .BR bzip2 (1)
2229 it is decompressed on-the-fly.
2230 .
2231 This includes the GNU
2232 .BR .gz ,
2233 .BR .bz2 ,
2234 and the traditional
2235 .B .Z
2236 compression.
2237 .
2238 The program displays the concatenation of all decompressed input in
2239 the sequence that was specified on the command line.
2240 .
2241 .
2242 .\" --------------------------------------------------------------------
2243 .SH "ENVIRONMENT"
2244 .\" --------------------------------------------------------------------
2245 .
2246 The groffer programs supports many system variables, most of them by
2247 courtesy of other programs.
2248 .
2249 All environment variables of
2250 .BR groff (@MAN1EXT@)
2251 and GNU
2252 .BR man (1)
2253 and some standard system variables are honored.
2254 .
2255 .
2256 .\" --------------------------------------------------------------------
2257 .SS "Native groffer Variables"
2258 .\" --------------------------------------------------------------------
2259 .
2260 .TP
2261 .Env_var $GROFFER_OPT
2262 Store options for a run of groffer.
2263 .
2264 The options specified in this variable are overridden by the options
2265 given on the command line.
2266 .
2267 The content of this variable is run through the shell builitin `eval';
2268 so arguments containing white-space or special shell characters should
2269 be quoted.
2270 .
2271 .
2272 .\" --------------------------------------------------------------------
2273 .SS "System Variables"
2274 .\" --------------------------------------------------------------------
2275 .
2276 The groffer program is a shell script that is run through
2277 .BR /bin/sh ,
2278 which can be internally linked to programs like
2279 .BR bash (1).
2280 The corresponding system environment is automatically effective.
2281 .
2282 The following variables have a special meaning for groffer.
2283 .
2284 .
2285 .TP
2286 .Env_var $DISPLAY
2287 If this variable is set this indicates that the X window system is
2288 running.
2289 .
2290 Testing this variable decides on whether graphical or text output is
2291 generated.
2292 .
2293 This variable should not be changed by the user carelessly, but it can
2294 be used to start the graphical groffer on a remote X terminal.
2295 .
2296 For example, depending on your system, groffer can be started on the
2297 second monitor by the command
2298 .Shell_cmd DISPLAY=:0.1\~groffer\~ what.ever &
2299 .
2300 .
2301 .TP
2302 .Env_var $LC_ALL
2303 .TP+
2304 .Env_var $LC_MESSAGES
2305 .TP+
2306 .Env_var $LANG
2307 If one of these variables is set (in the above sequence), its content
2308 is interpreted as the locale, the language to be used, especially when
2309 retrieving man\~pages.
2310 .
2311 A locale name is typically of the form
2312 .IR language [\c
2313 .B _\c
2314 .IR territory [\c
2315 .B .\c
2316 .IR codeset [\c
2317 .B @\c
2318 .IR modifier ]]],
2319 where
2320 .I language
2321 is an ISO 639 language code,
2322 .I territory
2323 is an ISO 3166 country code, and
2324 .I codeset
2325 is a character set or encoding identifier like ISO-8859-1 or UTF-8;
2326 see
2327 .BR setlocale (3).
2328 .
2329 The locale values\~\c
2330 .B C
2331 and
2332 .B POSIX
2333 stand for the default, i.e. the man\~page directories without a
2334 language prefix.
2335 .
2336 This is the same behavior as when all 3\~variables are unset.
2337 .
2338 .
2339 .TP
2340 .Env_var $PAGER
2341 This variable can be used to set the pager for the tty output.
2342 .
2343 For example, to disable the use of a pager completely set this
2344 variable to the
2345 .BR cat (1)
2346 program
2347 .Shell_cmd PAGER=cat\~groffer\~ anything
2348 .
2349 .
2350 .TP
2351 .Env_var $PATH
2352 All programs within the groffer shell script are called without a
2353 fixed path.
2354 .
2355 Thus this environment variable determines the set of programs used
2356 within the run of groffer.
2357 .
2358 .
2359 .TP
2360 .Env_var $POSIXLY_CORRECT
2361 If set to a non-empty value this chooses the POSIX mode for option
2362 processing, that means that option processing will be finished as soon
2363 as a non-option argument is found.
2364 .
2365 Usually, you do not want to set this environment variable.
2366 .
2367 .
2368 .\" --------------------------------------------------------------------
2369 .SS "Groff Variables"
2370 .\" --------------------------------------------------------------------
2371 .
2372 The groffer program internally calls groff, so all environment
2373 variables documented in
2374 .BR groff (@MAN1EXT@)
2375 are internally used within groffer as well; see there for details.
2376 .
2377 The following variables have a direct meaning for the groffer program.
2378 .
2379 .TP
2380 .Env_var $GROFF_TMPDIR
2381 If the value of this variable is an existing, writable directory,
2382 groffer uses it for storing its temporary files, just as groff does.
2383 .
2384 .
2385 .\" --------------------------------------------------------------------
2386 .SS "Man Variables"
2387 .\" --------------------------------------------------------------------
2388 .
2389 Parts of the functionality of the man program were implemented in
2390 groffer; support for all environment variables documented in
2391 .BR man (1)
2392 was added to groffer, but the meaning was slightly modified due to the
2393 different approach in groffer; but the user interface is the same.
2394 .
2395 The man environment variables can be overwritten by options provided
2396 with
2397 .Env_var $MANOPT ,
2398 which in turn is overwritten by the command line.
2399 .
2400 .
2401 .TP
2402 .Env_var $EXTENSION
2403 Restrict the search for man\~pages to files having this extension.
2404 .
2405 This is overridden by option
2406 .Opt_long extension ;
2407 see there for details.
2408 .
2409 .
2410 .TP
2411 .Env_var $MANOPT
2412 This variable contains options as a preset for
2413 .BR man (1).
2414 As not all of these are relevant for groffer only the essential parts
2415 of its value are extracted.
2416 .
2417 The options specified in this variable overwrite the values of the
2418 other environment variables taht are specific to man.
2419 .
2420 All options specified in this variable are overridden by the options
2421 given on the command line.
2422 .
2423 .
2424 .TP
2425 .Env_var $MANPATH
2426 If set, this variable contains the directories in which the man\~page
2427 trees are stored.
2428 .
2429 This is overridden by option
2430 .Opt_long manpath .
2431 .
2432 .
2433 .TP
2434 .Env_var $MANSECT
2435 If this is a colon separated list of section names, the search for
2436 man\~pages is restricted to those manual sections in that order.
2437 .
2438 This is overridden by option
2439 .Opt_long sections .
2440 .
2441 .
2442 .TP
2443 .Env_var $SYSTEM
2444 If this is set to a comma separated list of names these are interpreted
2445 as man\~page trees for different operating systems.
2446 .
2447 This variable can be overwritten by option
2448 .Opt_long systems ;
2449 see there for details.
2450 .
2451 .
2452 .P
2453 The environment variable
2454 .Env_var $MANROFFSEQ
2455 is ignored by groffer because the necessary preprocessors are
2456 determined automatically.
2457 .
2458 .
2459 .\" --------------------------------------------------------------------
2460 .SH "FILES"
2461 .\" --------------------------------------------------------------------
2462 .
2463 The groffer program can be preconfigured by two configuration files.
2464 .
2465 Both of them are shell scripts that are called at the beginning of
2466 groffer using the `\c
2467 .CB .\~\c
2468 .IR filename '
2469 syntax.
2470 .
2471 .
2472 .TP
2473 .CB /etc/groff/groffer.conf
2474 System-wide configuration file for groffer.
2475 .
2476 .
2477 .TP
2478 .CB $HOME/.groff/groffer.conf
2479 User-specific configuration file for groffer, where
2480 .Env_var $HOME
2481 denotes the user's home directory.
2482 .
2483 This script is called after the system-wide configuration file to
2484 enable overriding by the user.
2485 .
2486 .
2487 .P
2488 It makes sense to use these configuration files for the following
2489 tasks:
2490 .
2491 .Topic
2492 Preset environment variables recognized by groffer; preferably a
2493 variable should only be set when it is unset in order not to override
2494 a user-provided value.
2495 .
2496 .Topic
2497 Preset command line options by prepending them to
2498 .Env_var $GROFFER_OPT ;
2499 prepending should be preferred to appending and setting in order not
2500 to delete the environment variable provided by the
2501 .
2502 .Topic
2503 Write functions for calling viewer programs in a special way and feed
2504 them into the
2505 .Opt_long \f[I]*\f[]-viewer
2506 options.
2507 .
2508 Note that the name of such a function must coincide with some existing
2509 program in the system path
2510 .Env_var $PATH
2511 in order to be recognized by groffer.
2512 .
2513 .
2514 .P
2515 As an example, consider the following configuration file.
2516 .
2517 .P
2518 .ft CR
2519 .nh
2520 .nf
2521 #! /bin/sh
2522 # ~/.groff/groffer.conf
2523 if test "$DISPLAY" = ""; then
2524   DISPLAY='localhost:0.0';
2525 fi;
2526 GROFF_OPT="--resolution=100 $GROFF_OPT";
2527 gxditview()
2528 {
2529   /usr/local/bin/gxditview --fg DarkBlue "$@";
2530 }
2531 .fi
2532 .hy
2533 .ft
2534 .
2535 .
2536 .P
2537 This has the following effects:
2538 .Topic
2539 allows to start groffer in a graphical mode even from a text
2540 terminal;
2541 .Topic
2542 all graphical modes use a resolution of 100 dpi where applicable;
2543 .Topic
2544 the
2545 .BR gxditview (@MAN1EXT@)
2546 program is told to use
2547 .I DarkBlue
2548 as the text color.
2549 .
2550 These configurations can be overridden by command line options and by
2551 environment variable
2552 .Env_var $GROFFER_OPT .
2553 .
2554 .
2555 .\" --------------------------------------------------------------------
2556 .SH "EXAMPLES"
2557 .\" --------------------------------------------------------------------
2558 .
2559 The usage of groffer is very easy.
2560 .
2561 Usually, it is just called with a file name or man\~page.
2562 .
2563 The following examples, however, show that groffer has much more fancy
2564 capabilities.
2565 .
2566 .
2567 .TP
2568 .Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz"
2569 Decompress, format and display the compressed file
2570 .I meintro.ms.gz
2571 in the directory
2572 .IR /usr/local/share/doc/groff ,
2573 using a default graphical viewer when in X window, or the
2574 .BR less (1)
2575 pager program when not in X.
2576 .
2577 .
2578 .TP
2579 .Shell_cmd "groffer\~groff.7\~groff\~\[cq]troff(1)\[cq]\~man:roff"
2580 .
2581 The arguments that are not existing files are looked-up as the
2582 following man\~pages:
2583 .I groff
2584 (in section\~7),
2585 .I groff
2586 (automatic search, should be found in section\~1),
2587 .I troff
2588 (in section\~1),
2589 and
2590 .I roff
2591 (in the section with the lowest number, being\~7 in this case).
2592 .
2593 The quotes around
2594 .I \[cq]troff(1)\[cq]
2595 are necessary because the paranthesis are special shell characters;
2596 escaping them with a backslash character
2597 .I \[rs](
2598 and
2599 .I \[rs])
2600 would be possible, too.
2601 .
2602 The formatted files are concatenated and displayed in one piece.
2603 .
2604 .
2605 .TP
2606 .Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=netscape\~ls"
2607 .
2608 Retrieve the German man\~page for the
2609 .B ls
2610 program (or the English one if there is a German version), decompress
2611 it, format it into the html format and view the result in the default
2612 web browser
2613 .I netscape .
2614 The option
2615 .Opt_long man
2616 guarantees that the man\~page is retrieved, even when a local file
2617 .I ls
2618 exists in the actual directory.
2619 .
2620 .
2621 .TP
2622 .Shell_cmd "groffer\~-Q\~'man:roff(7)'"
2623 .
2624 Print the unformatted content of the man\~page called
2625 .I roff
2626 in section 7 on standard output.
2627 .
2628 .
2629 .TP
2630 .Shell_cmd "groffer\~-Z\~-mfoo"
2631 .
2632 Decompress the standard input, switch to
2633 .I groff
2634 mode, format the input with groff using the macro package foo, but do
2635 not postprocess the result, thus producing the intermediate output.
2636 .
2637 .
2638 .TP
2639 .Shell_cmd "echo\~'\[rs]f[CB]WOW!'\~|"
2640 .TP+
2641 .Shell_cmd+ "groffer --x --bg red --fg yellow --geometry 200x100"
2642 .
2643 Display \f[CB]WOW!\f[] in a small window in constant-width bold font,
2644 using color yellow on red background.
2645 .
2646 .
2647 .\" --------------------------------------------------------------------
2648 .SH "COMPATIBILITY"
2649 .\" --------------------------------------------------------------------
2650 .
2651 The
2652 .B groffer
2653 shell script is compatible to both POSIX and GNU.
2654 .
2655 POSIX compatibility refers to
2656 .B IEEE P1003.2/D11.2
2657 of September 1991, a very early version of this standard.
2658 .
2659 The script uses only a quite restricted set of shell language elements
2660 and shell builtins, common to all POSIX versions; the only external
2661 program used is `sed', again only the most basic POSIX features of
2662 `sed' are used.
2663 .
2664 The groffer script should work on most actual free and commercial
2665 operating systems.
2666 .
2667 .
2668 .P
2669 The groffer program provides its own parser for command line options;
2670 it can handle option arguments and file names containing white space
2671 and a large set of special characters.
2672 .
2673 .
2674 .P
2675 The groffer shell script was tested with the following common
2676 implementations of the POSIX shell:
2677 .BR ash (1),
2678 .BR bash (1),
2679 .BR ksh (1),
2680 and POSIX
2681 .BR sh (1),
2682 and others.
2683 .
2684 Free POSIX compatible shells and shell utilities for most operating
2685 systems are available at the
2686 .URL http://\:www.gnu.org/software/ "GNU software archive" .
2687 .
2688 .
2689 .P
2690 The best performance was obtained with the
2691 .I ash
2692 shell; so groffer tries to run under
2693 .I ash
2694 whenever possible.
2695 .
2696 The procedure to determine the shell to run groffer was programmed to
2697 be as follows:
2698 .
2699 .
2700 .Topic
2701 the argument of the command line option
2702 .Opt_long shell ;
2703 if not set
2704 .
2705 .Topic
2706 the argument of the option
2707 .Opt_long shell
2708 in the environment variable
2709 .Env_var $GROFF_OPT ;
2710 if not set
2711 .
2712 .Topic
2713 try
2714 .IR ash ;
2715 if not available
2716 .
2717 .Topic
2718 continue with the shell under which the script was started in the
2719 first place.
2720 .
2721 .
2722 .\" --------------------------------------------------------------------
2723 .SH "SEE ALSO"
2724 .\" --------------------------------------------------------------------
2725 .
2726 .TP
2727 .BR groff (@MAN1EXT@)
2728 .TP+
2729 .BR troff (@MAN1EXT@)
2730 Details on the options and environment variables available in groff;
2731 all of them can be used with groffer.
2732 .
2733 .
2734 .TP
2735 .BR grog (@MAN1EXT@)
2736 Internally, groffer tries to guess the groff command line options from
2737 the input using this program.
2738 .
2739 .
2740 .TP
2741 .BR groff_out (@MAN5EXT@)
2742 Documentation on the groff intermediate output (ditroff output).
2743 .
2744 .
2745 .TP
2746 .BR xdvi (1)
2747 .TP+
2748 .BR dvilx (1)
2749 Viewers for groffer's
2750 .I dvi
2751 mode.
2752 .
2753 .
2754 .TP
2755 .BR gv (1)
2756 .TP+
2757 .BR ghostview (1)
2758 Viewers for groffer's
2759 .I ps
2760 mode.
2761 .
2762 .
2763 .TP+
2764 .BR gs (1)
2765 Transformer from
2766 .I ps
2767 to
2768 .IR pdf ;
2769 and a
2770 .I ps
2771 viewer.
2772 .
2773 .
2774 .TP
2775 .BR xpdf (1)
2776 Viewers for
2777 .I pdf
2778 files.
2779 .
2780 .
2781 .TP
2782 .BR gxditview (@MAN1EXT@)
2783 .TP+
2784 .BR xditview (1x)
2785 Viewers for groffer's
2786 .I x
2787 mode.
2788 .
2789 .
2790 .TP
2791 .BR gzip (1)
2792 .TP+
2793 .BR bzip2 (1)
2794 The decompression programs supported by groffer.
2795 .
2796 .
2797 .TP
2798 .BR man (1)
2799 The standard program to diplay man\~pages.
2800 .
2801 The information there is only useful if it is the man\~page for
2802 .IR "GNU\~man" .
2803 Then it documents the options and environment variables that are
2804 supported by groffer.
2805 .
2806 .
2807 .\" --------------------------------------------------------------------
2808 .SH "AUTHOR"
2809 .\" --------------------------------------------------------------------
2810 .
2811 Copyright (C) 2001, 2002 Free Software Foundation, Inc.
2812 .
2813 .P
2814 This document is distributed under the terms of the FDL (GNU Free
2815 Documentation License) version 1.1 or later.
2816 .
2817 You should have received a copy of the FDL on your system, it is also
2818 available on-line at the
2819 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
2820 .
2821 .P
2822 This document is part of
2823 .IR groff ,
2824 the GNU roff distribution.
2825 .
2826 It was written by
2827 .MTO bwarken@mayn.de "Bernd Warken" .
2828 .
2829 .
2830 \" --------------------------------------------------------------------
2831 .\" Emacs settings
2832 .\" --------------------------------------------------------------------
2833 .
2834 .\" Local Variables:
2835 .\" mode: nroff
2836 .\" End: