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 Last update: 22 August 2005
  19
  20 Source file position: <groff-source>/contrib/groffer/groffer.man
  21 ..
  22 .de author
  23 This file was written by
  24 .MTO "" "Bernd Warken" .
  25 ..
  26 .de copyleft
  27 Copyright (C) 2001,2002,2004,2005 Free Software Foundation, Inc.
  28 .
  29 .P
  30 This file is part of
  31 .IR \%groffer ,
  32 which is part of
  33 .IR \%groff ,
  34 a free software project.
  35 .
  36 You can redistribute it and/or modify it under the terms of the
  37 .nh
  38 .B GNU General Public License
  39 .hy
  40 as published by the
  41 .nh
  42 .BR "Free Software Foundation" ,
  43 .hy
  44 either version 2, or (at your option) any later version.
  45 .
  46 .P
  47 You should have received a copy of the \f[CR]GNU General Public
  48 License\f[] along with
  49 .IR groff ,
  50 see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
  51 directory of the
  52 .I groff
  53 source package.
  54 .
  55 Or read the
  56 .I man\~page
  57 .BR gpl (1).
  58 You can also write to the
  59 .nh
  60 .B Free Software Foundation, 51 Franklin St - Fifth Floor, Boston,
  61 .BR "MA 02110-1301, USA" .
  62 .hy
  63 ..
  64 .
  65 .\" --------------------------------------------------------------------
  66 .\" Setup
  67 .\" --------------------------------------------------------------------
  68 .
  69 .mso www.tmac
  70 .
  71 .if n \{\
  72 .  mso tty-char.tmac
  73 .  ftr CR R
  74 .  ftr CI I
  75 .  ftr CB B
  76 .\}
  77 .
  78 .if '\*[.T]'dvi' \{\
  79 .  ftr CB CW
  80 .\}
  81 .
  82 .ds Ellipsis ".\|.\|.\""
  83 .
  84 .\" --------------------------------------------------------------------
  85 .\" setup for the macro definitions below
  86 .\"
  87 .\" naming:  namespace:cathegory_macro.variable_name  (experimental)
  88 .
  89 .\" --------------------------------------------------------------------
  90 .\" configuration of prompt for `.Shell_cmd'* macros
  91 .ds groffer:Shell_cmd.prompt_text sh#\"    prompt for shell commands
  92 .ds groffer:Shell_cmd+.prompt_text >\"     prompt on continuation lines
  93 .ds groffer:Shell_cmd_base.prompt_font I\" font for prompts
  94 .
  95 .\" automatically determine setup from the configuration above
  96 .als @f groffer:Shell_cmd_base.prompt_font\"
  97 .als @t groffer:Shell_cmd.prompt_text\"
  98 .als @t+ groffer:Shell_cmd+.prompt_text\"
  99 .ds groffer:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\"            needed
 100 .ds groffer:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\"          needed
 101 .nr @w \w'\*[groffer:Shell_cmd.prompt]'\"
 102 .nr @w+ \w'\*[groffer:Shell_cmd+.prompt]'\"
 103 .ft \*[@f]
 104 .\" Full prompt width is maximum of texts plus 1m
 105 .nr groffer:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
 106 .ft
 107 .rm @f
 108 .rm @f+
 109 .rm @t
 110 .rm @t+
 111 .rr @w
 112 .rr @w+
 113 .
 114 .\" --------------------------------------------------------------------
 115 .\" static register for inter-macro communication in `.Synopsis'*
 116 .nr groffer:Synopsis.level 0
 117 .
 118 .\" --------------------------------------------------------------------
 119 .\" static registers for inter-macro communication in `.TP'*
 120 .nr groffer:TP.level 0
 121 .rr groffer:TP_header.flag
 122 .rr groffer:TP_body.flag
 123 .rr groffer:TP.indent
 124 .
 125 .
 126 .\" --------------------------------------------------------------------
 127 .\" Macro definitions
 128 .
 129 .\" Ignore all arguments like a comment, even after a .eo call.
 130 .de c
 131 ..
 132 .c --------------------------------------------------------------------
 133 .c .CB  (<text>...)
 134 .c
 135 .c Print in constant-width bold font.
 136 .c
 137 .de CB
 138 .  ft CB
 139 .  Text \\$*
 140 .  ft
 141 ..
 142 .c --------------------------------------------------------------------
 143 .c .CI  (<text>...)
 144 .c
 145 .c Print in constant-width italic font.
 146 .c
 147 .de CI
 148 .  ft CI
 149 .  Text \\$*
 150 .  ft
 151 ..
 152 .c --------------------------------------------------------------------
 153 .c .CR  (<text>...)
 154 .c
 155 .c Print in constant-width roman font.
 156 .c
 157 .de CR
 158 .  ft CR
 159 .  Text \\$*
 160 .  ft
 161 ..
 162 .c --------------------------------------------------------------------
 163 .c .Error  (<text>...)
 164 .c
 165 .c Print error message to terminal and abort.
 166 .c
 167 .de Error
 168 .  tm \\$*
 169 .  ab
 170 ..
 171 .c --------------------------------------------------------------------
 172 .c .Env_var  (<env_var_name> [<punct>])
 173 .c
 174 .c Display an environment variable, with optional punctuation.
 175 .c
 176 .de Env_var
 177 .  nh
 178 .  SM
 179 .  Text \f[CB]\\$1\f[]\\$2
 180 .  hy
 181 ..
 182 .c --------------------------------------------------------------------
 183 .c .File_name  (<path_name>)
 184 .c
 185 .c Display a file or directory name in CB font.
 186 .c
 187 .de File_name
 188 .  Header_CB \\$@
 189 ..
 190 .c --------------------------------------------------------------------
 191 .c .Header_CB  (<path_name>)
 192 .c
 193 .c Display a line in CB font, for example after .TP
 194 .c
 195 .de Header_CB
 196 .  nh
 197 .  Text \f[CB]\\$1\f[]\\$2
 198 .  hy
 199 ..
 200 .c --------------------------------------------------------------------
 201 .c .Opt_-  ([<punct>])
 202 .c
 203 .c Print `-' (minus sign); optional punctuation.
 204 .c
 205 .de Opt_-
 206 .  ie (\\n[.$] == 0) \
 207 .    Opt_alt - ""
 208 .  el \
 209 .    Opt_alt - "" "\\$1"
 210 ..
 211 .c --------------------------------------------------------------------
 212 .c .Opt_[-]  ([<punct>])
 213 .c
 214 .c Print `Opt_[-]' (minus sign in brackets); optional punctuation.
 215 .c
 216 .de Opt_[-]
 217 .  ie (\\n[.$] == 0) \
 218 .    Opt_[alt] - ""
 219 .  el \
 220 .    Opt_[alt] - "" "\\$1"
 221 ..
 222 .c --------------------------------------------------------------------
 223 .c .Opt_--  ([<punct>])
 224 .c
 225 .c Print `--' (double minus); optional punctuation.
 226 .c
 227 .de Opt_--
 228 .  ie (\\n[.$] == 0) \
 229 .    Opt_alt -- ""
 230 .  el \
 231 .    Opt_alt -- "" "\\$1"
 232 ..
 233 .c --------------------------------------------------------------------
 234 .c .Opt_[--]  ([<punct>])
 235 .c
 236 .c Print `Opt_[--]' (double minus in brackets); optional punctuation.
 237 .c
 238 .de Opt_[--]
 239 .  ie (\\n[.$] == 0) \
 240 .    Opt_[alt] -- ""
 241 .  el \
 242 .    Opt_[alt] -- "" "\\$1"
 243 ..
 244 .c --------------------------------------------------------------------
 245 .c .Opt_alt  ([<minus> <opt>]... [<arg> [<punct>]])
 246 .c
 247 .c Alternate options separated by a vertical bar.
 248 .c
 249 .c Arguments:
 250 .c   minus: either `-' or `--' (font CB).
 251 .c   opt: a name for an option, empty allowed (font CB).
 252 .c   arg: optionally, the argument to the option (font I).
 253 .c   punct: optional punctuation (in the starting font).
 254 .c Result:
 255 .c   The minus/opt argument pairs, each
 256 .c   separated by a vertical bar `|', optionally add 'arg', separated
 257 .c   a space character ` '.
 258 .c
 259 .c Example:
 260 .c  .Opt_alt - T -- device -- device-troff device .
 261 .c  results in
 262 .c  -T|--device|--device-troff device.
 263 .c
 264 .de Opt_alt
 265 .  Opt_alt_base "" | "" \\$@
 266 ..
 267 .c --------------------------------------------------------------------
 268 .c .Opt_[alt]  ([<minus> <opt>]... [<arg> [<punct>]])
 269 .c
 270 .c Alternate options in brackets for section SYNOPSIS.
 271 .c
 272 .c Arguments:
 273 .c   minus: either `-' or `--' (font CB).
 274 .c   opt: a name for an option, empty allowed (font CB).
 275 .c   arg: optionally, the argument to the option (font I).
 276 .c   punct: optional punctuation (in the starting font).
 277 .c Global strings written to:
 278 .c   `@oa_prefix': left enclosing character (`[')
 279 .c   `@oa_sep': separator (`|')
 280 .c   `@oa_postfix': right enclosing character (`]')
 281 .c Result:
 282 .c   The minus/opt argument pairs, each separated by a vertical
 283 .c   bar `|', optionally add 'arg', separated by a space character ` '.
 284 .c
 285 .c Example:
 286 .c  .Opt_[alt] - T -- device -- device-troff device .
 287 .c  results in
 288 .c  [-T|--device|--device-troff device].
 289 .c
 290 .de Opt_[alt]
 291 .  Opt_alt_base [ | ] \\$@
 292 ..
 293 .c --------------------------------------------------------------------
 294 .c .Opt_alt_base  (<pre> <sep> <post> [<minus> <opt>]... [arg [punct]])
 295 .c
 296 .c Alternating options; base macro for many others; do not use directly.
 297 .c
 298 .c Arguments:
 299 .c   <pre>: prefix, result is preceded by this.
 300 .c   <sep>: separator between minus/opt pairs.
 301 .c   <post>: postfix, is appended to the result.
 302 .c   <minus>: either `-' or `--' (font CB).
 303 .c   <opt>: a name for an option, empty allowed (font CB).
 304 .c   <arg>: optionally, the argument to the option (font I).
 305 .c   <punct>: optional punctuation (in the starting font).
 306 .c Result:
 307 .c   String `<pre>' followed by the <minus>/<opt> argument pairs, each
 308 .c   separated by string `<sep>', optionally add '<arg>', separated by
 309 .c   a single space ` ', followed by the string `<post>'.  Terminated
 310 .c   by the optional punctuation <punct>.
 311 .c
 312 .de Opt_alt_base
 313 .  nr @font \\n[.f]\"
 314 .  if (\\n[.$] < 3) \
 315 .    Error .\\0: not enough arguments.
 316 .  ds @pre \)\\$1\)\"                   prefix
 317 .  ds @sep \)\\$2\)\"                   separator
 318 .  ds @post \)\\$3\)\"                  postfix
 319 .  shift 3
 320 .  nr @count 0
 321 .  ds @res \f[CR]\\*[@pre]\"
 322 .  while (\\n[.$] >= 2) \{\
 323 .    c                                  do the pairs, break on no `-'
 324 .    if !'\\$1'-' \{\
 325 .      if !'\\$1'--' \
 326 .        break
 327 .    \}
 328 .    c                                  separator
 329 .    if (\\n[@count] > 0) \
 330 .      as @res \f[CR]\\*[@sep]\:\"
 331 .    nr @count +1
 332 .    c                                  combine minus with option name
 333 .    as @res \f[CB]\\-\"
 334 .    if '\\$1'--' \
 335 .      as @res \\-\"
 336 .    as @res \\$2\"
 337 .    shift 2
 338 .  \}
 339 .  if (\\n[.$] >= 3) \
 340 .    Error .\\0: wrong arguments: \\$@
 341 .  c                                    all pairs are done
 342 .  ie (\\n[.$] == 0) \
 343 .    as @res \f[CR]\\*[@post]\"
 344 .  el \{\
 345 .    c                                  optional option argument
 346 .    if !'\\$1'' \
 347 .      as @res \f[CR] \,\f[I]\\$1\"
 348 .    shift
 349 .    c                                  postfix
 350 .    as @res \\f[CR]\\*[@post]\"
 351 .    if (\\n[.$] >= 1) \{\
 352 .      c                                add punctuation
 353 .      as @res \f[\\n[@font]]\\$1\"
 354 .    \}
 355 .  \}
 356 .  nh
 357 .  Text \\*[@res]
 358 .  hy
 359 .  ft \\n[@font]
 360 .  rr @count
 361 .  rr @font
 362 .  rm @pre
 363 .  rm @post
 364 .  rm @sep
 365 .  rm @res
 366 ..
 367 .c --------------------------------------------------------------------
 368 .c .Opt_def  ([<minus> <opt>]... [<arg> [<punct>]])
 369 .c
 370 .c Definitions of options in section OPTIONS.
 371 .c
 372 .c Arguments:
 373 .c   minus: either `-' or `--' (font CB).
 374 .c   opt: a name for an option, empty allowed (font CB).
 375 .c   arg: optionally, the argument to the option (font I).
 376 .c   punct: optional punctuation (in the starting font).
 377 .c Result:
 378 .c   The header for an indented paragraph, consisting of
 379 .c   minus/opt argument pairs, each, separated by a space
 380 .c   character ` ', optionally add 'arg', separated a space
 381 .c   character ` '.
 382 .c
 383 .c Example:
 384 .c  .Opt_def - T -- device -- device-troff device .
 385 .c  results in
 386 .c  -T --device --device-troff device.
 387 .c  as the header of for indented paragraph.
 388 .c
 389 .de Opt_def
 390 .  TP
 391 .    Opt_alt_base "" "\~|\~" "" \\$@
 392 ..
 393 .c --------------------------------------------------------------------
 394 .c .Opt_element  ([<minus> <opt>]... [<arg> [<punct>]])
 395 .c
 396 .c Definitions of options in section OPTIONS.
 397 .c
 398 .c Arguments:
 399 .c   minus: either `-' or `--' (font CB).
 400 .c   opt: a name for an option, empty allowed (font CB).
 401 .c   arg: optionally, the argument to the option (font I).
 402 .c   punct: optional punctuation (in the starting font).
 403 .c Result:
 404 .c   The minus/opt argument pairs, each, separated by a space
 405 .c   character ` ', optionally add 'arg', separated a space
 406 .c   character ` '.
 407 .c
 408 .c Example:
 409 .c  .Opt_element - T -- device -- device-troff device .
 410 .c  results in
 411 .c  -T --device --device-troff device.
 412 .c
 413 .de Opt_element
 414 .  Opt_alt_base "" "\~" "" \\$@
 415 ..
 416 .c --------------------------------------------------------------------
 417 .als Opt_list Opt_element
 418 .
 419 .c --------------------------------------------------------------------
 420 .c .Opt_long  ([<name> [<punct>]])
 421 .c
 422 .c Print `--name' somewhere in the text; optional punctuation.
 423 .c
 424 .de Opt_long
 425 .  Opt_alt -- "\\$1" "" "\\$2"
 426 ..
 427 .c --------------------------------------------------------------------
 428 .c .Opt_long_arg  ([<name> <arg> [<punct>]])
 429 .c
 430 .c Print `--name=arg' somewhere in the text; optional punctuation.
 431 .c
 432 .de Opt_long_arg
 433 .  Opt_alt -- "\\$1=\\$2" "" "\\$3"
 434 ..
 435 .c --------------------------------------------------------------------
 436 .c .Opt_[long]  ([<name> [<punct>]])
 437 .c
 438 .c Print `--name' somewhere in the text; optional punctuation.
 439 .c
 440 .de Opt_[long]
 441 .  Opt_[alt] -- "\\$1" "" "\\$2"
 442 ..
 443 .c --------------------------------------------------------------------
 444 .c .Opt_short  ([<name> [<punct>]])
 445 .c
 446 .c Print `-name' somewhere in the Text; optional punctuation.
 447 .c
 448 .de Opt_short
 449 .  Opt_alt - "\\$1" "" "\\$2"
 450 ..
 451 .c --------------------------------------------------------------------
 452 .c .Opt_[short]  ([name [punct]])
 453 .c
 454 .c Print `[-name]' somewhere in the Text; optional punctuation.
 455 .c
 456 .de Opt_[short]
 457 .  Opt_[alt] - "\\$1" "" "\\$2"
 458 ..
 459 .c --------------------------------------------------------------------
 460 .c .Shell_cmd  (<CR> [<CI>] ...)
 461 .c
 462 .c A shell command line; display args alternating in fonts CR and CI.
 463 .c
 464 .c Examples:
 465 .c   .Shell_cmd "groffer --dpi 100 file"
 466 .c     result: `sh#  groffer --dpi 100 file'
 467 .c             with 'sh#' in font I, the rest in CR
 468 .c
 469 .c   .Shell_cmd groffer\~--dpi\~100\~file
 470 .c     result: the same as above
 471 .c
 472 .c   .Shell_cmd "groffer --dpi=" value " file"
 473 .c     result: sh#  groffer --dpi=value file
 474 .c             with `groffer --dpi=' and `file' in CR; `value' in CI
 475 .c
 476 .c   .Shell_cmd groffer\~--dpi= value \~file
 477 .c     result: the same as the previous example
 478 .c
 479 .de Shell_cmd
 480 .  groffer:Shell_cmd_base "\*[groffer:Shell_cmd.prompt]" \\$@
 481 ..
 482 .c --------------------------------------------------------------------
 483 .c .Shell_cmd+  (<CR> [<CI>] ...)
 484 .c
 485 .c A continuation line for .Shell_cmd.
 486 .c
 487 .de Shell_cmd+
 488 .  groffer:Shell_cmd_base "\*[groffer:Shell_cmd+.prompt]" \\$@
 489 ..
 490 .c --------------------------------------------------------------------
 491 .c .Shell_cmd_base  (<prompt> [<CR> [<CI>] ...])
 492 .c
 493 .c A shell command line; display args alternating in fonts CR and CI.
 494 .c Internal, do not use directly.
 495 .c
 496 .c Globals: read-only register @.Shell_cmd_width
 497 .c
 498 .de groffer:Shell_cmd_base
 499 .  if (\\n[.$] <= 0) \
 500 .    return
 501 .  nr @+font \\n[.f]\"
 502 .  ds @prompt \\$1\"
 503 .  ft CR
 504 .  c gap between prompt and command
 505 .  nr @+gap \\n[groffer:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
 506 .  ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
 507 .  shift
 508 .  ds @cf CR\"
 509 .  while (\\n[.$] > 0) \{\
 510 .    as @res \\f[\\*[@cf]]\\$1\"
 511 .    shift
 512 .    ie '\\*[@cf]'CR' \
 513 .      ds @cf I\"
 514 .    el \
 515 .      ds @cf CR\"
 516 .  \}
 517 .  br
 518 .  ad l
 519 .  nh
 520 .  nf
 521 .  Text \\*[@res]\"
 522 .  fi
 523 .  hy
 524 .  ad
 525 .  br
 526 .  ft \\n[@+font]
 527 .  rr @+font
 528 .  rr @+gap
 529 .  rm @cf
 530 .  rm @res
 531 ..
 532 .c --------------------------------------------------------------------
 533 .c .Synopsis  ()
 534 .c
 535 .c Begin a synopsis section, to be ended by a ./Synopsis macro.
 536 .c
 537 .de Synopsis
 538 .  if (\\n[groffer:Synopsis.level] > 0) \
 539 .    Error .\\$0: previous .Synopsis was not closed by ./Synopsis.
 540 .  nh
 541 .  ds @1 \\$1\"
 542 .  nr @old_indent \\n(.i
 543 .  ad l
 544 .  in +\w'\fB\\*[@1]\0'u
 545 .  ti \\n[@old_indent]u
 546 .  B \\*[@1]\0\c
 547 .  rr @old_indent
 548 .  rm @1
 549 .  nr groffer:Synopsis.level +1\"        marker for ./Synopsis
 550 ..
 551 .c  --------------------------------------------------------------------
 552 .c ./Synopsis  ()
 553 .c
 554 .c Close a synopsis section opened by the previous .Synopsis macro.
 555 .c
 556 .de /Synopsis
 557 .  if (\\n[groffer:Synopsis.level] <= 0) \
 558 .    Error .\\$0: no previous call of .Synopsis
 559 .  br
 560 .  ad
 561 .  in
 562 .  hy
 563 .  nr groffer:Synopsis.level -1
 564 ..
 565 .c  --------------------------------------------------------------------
 566 .c .Text  (<text>...)
 567 .c
 568 .c Treat the arguments as text, no matter how they look.
 569 .c
 570 .de Text
 571 .  if (\\n[.$] == 0) \
 572 .    return
 573 .  nh
 574 .  nop \)\\$*\)
 575 .  hy
 576 ..
 577 .c --------------------------------------------------------------------
 578 .c .Topic  ([<indent>])
 579 .c
 580 .c A bulleted paragraph
 581 .c
 582 .de Topic
 583 .  ie (\\n[.$] = 0) \
 584 .    ds @indent 2m\"
 585 .  el \
 586 .    ds @indent \\$1\"
 587 .  TP \\*[@indent]
 588 .  Text \[bu]
 589 .  rm @indent
 590 ..
 591 .c --------------------------------------------------------------------
 592 .c .TP+  ()
 593 .c
 594 .c Continuation line for .TP header.
 595 .c
 596 .de TP+
 597 .  br
 598 .  ns
 599 .  TP \\$1
 600 ..
 601 .c --------------------------------------------------------------------
 602 .c .TP_header  ([<indent>])
 603 .c
 604 .c Start a multi-line header for a .TP-like paragraph
 605 .c
 606 .de TP_header
 607 .  if (\\n[groffer:TP.level] < 0) \
 608 .    Error .\\$0: wrong level.
 609 .  nr groffer:TP.level +1
 610 .  P
 611 .  ie (\\n[.$] == 0) \
 612 .    rr groffer:TP.indent
 613 .  el \
 614 .    nr groffer:TP.indent \\$1
 615 .  nr groffer:TP_header.flag 1
 616 ..
 617 .c --------------------------------------------------------------------
 618 .c .TP_body  ([<indent>])
 619 .c
 620 .c End a previous .TP-header and beging the body of the paragraph.
 621 .c
 622 .de TP_body
 623 .  if !rgroffer:TP_header.flag \
 624 .    Error .\\$0: no previous call of .TP_header
 625 .  if (\\n[groffer:TP.level] <= 0) \
 626 .    Error .\\$0: wrong level.
 627 .  br
 628 .  ie (\\n[.$] == 0) \{\
 629 .    ie rgroffer:TP.indent \{\
 630 .      RS \\n[groffer:TP.indent]u
 631 .    \}
 632 .    el \
 633 .      RS
 634 .  \}
 635 .  el \
 636 .    RS \\$1u
 637 .  rr groffer:TP.indent
 638 .  rr groffer:TP_header.flag
 639 .  nr groffer:TP_body.flag 1
 640 ..
 641 .c --------------------------------------------------------------------
 642 .c TP_end  ()
 643 .c
 644 .c End of former .TP_body paragraph.
 645 .c
 646 .de TP_end
 647 .  if !rgroffer:TP_body.flag \
 648 .    Error .\\$0: no previous .TP_body.
 649 .  if (\\n[groffer:TP.level] <= 0) \
 650 .    Error TP_end: wrong level.
 651 .  nr groffer:TP.level -1
 652 .  rr grogger:TP.indent
 653 .  rr groffer:TP_header.flag
 654 .  rr groffer:TP_body.flag
 655 .  br
 656 .  RE
 657 ..
 658 .
 659 .\" End of macro definitions
 660 .
 661 .
 662 .\" --------------------------------------------------------------------
 663 .\" SH "SYNOPSIS"
 664 .\" --------------------------------------------------------------------
 665 .
 666 .ad l
 667 .Synopsis groffer
 668 .RI [ option... ]
 669 .Opt_[--]
 670 .RI [ "\%filespec" "\*[Ellipsis]]"
 671 ./Synopsis
 672 .
 673 .Synopsis groffer
 674 .Opt_alt - h -- help
 675 ./Synopsis
 676 .
 677 .Synopsis groffer
 678 .Opt_alt - v -- version
 679 ./Synopsis
 680 .
 681 .
 682 .\" --------------------------------------------------------------------
 683 .SH DESCRIPTION
 684 .\" --------------------------------------------------------------------
 685 .
 686 The
 687 .B \%groffer
 688 program is the easiest way to use
 689 .BR \%groff (@MAN1EXT@).
 690 It can display arbitrary documents written in the
 691 .I \%groff
 692 language, see
 693 .BR \%groff (@MAN7EXT@),
 694 or other
 695 .I \%roff
 696 languages, see
 697 .BR \%roff (@MAN7EXT@),
 698 that are compatible to the original
 699 .I \%troff
 700 language.
 701 .
 702 The
 703 .B \%groffer
 704 program also includes many of the features for finding and displaying
 705 the \%\f[CR]Unix\f[] manual pages
 706 .nh
 707 .RI ( man\~pages ),
 708 .hy
 709 such that it can be used as a replacement for a
 710 .BR \%man (1)
 711 program.
 712 .
 713 Moreover, compressed files that can be handled by
 714 .BR \%gzip (1)
 715 or
 716 .BR \%bzip2 (1)
 717 are decompressed on-the-fly.
 718 .
 719 .
 720 .P
 721 The normal usage is quite simple by supplying a file name or name of a
 722 .I \%man\~page
 723 without further options.
 724 .
 725 But the option handling has many possibilities for creating special
 726 behaviors.
 727 .
 728 This can be done either in configuration files, with the shell
 729 environment variable
 730 .BR \%$GROFFER_OPT ,
 731 or on the command line.
 732 .
 733 .
 734 .P
 735 The output can be generated and viewed in several different ways
 736 available for
 737 .IR \%groff .
 738 .
 739 This includes the
 740 .I \%groff
 741 native \%\f[CR]X\~Window\f[] viewer
 742 .BR \%gxditview (@MAN1EXT@),
 743 each
 744 .IR \%Postcript ,
 745 .IR \%pdf ,
 746 or
 747 .I \%dvi
 748 display program, a web browser by generating
 749 .I \%html
 750 in
 751 .IR \%www\~mode ,
 752 or several
 753 .I \%text\~modes
 754 in text terminals.
 755 .
 756 .
 757 .P
 758 Most of the options that must be named when running
 759 .B \%groff
 760 directly are determined automatically for
 761 .BR \%groffer ,
 762 due to the internal usage of the
 763 .BR \%grog (@MAN1EXT@)
 764 program.
 765 .
 766 But all parts can also be controlled manually by arguments.
 767 .
 768 .
 769 .P
 770 Several file names can be specified on the command line arguments.
 771 .
 772 They are transformed into a single document in the normal way of
 773 .BR \%groff .
 774 .
 775 .
 776 .P
 777 Option handling is done in \f[CR]GNU\f[] style.
 778 .
 779 Options and file names can be mixed freely.
 780 .
 781 The option
 782 .RB ` \-\- '
 783 closes the option handling, all following arguments are treated as
 784 file names.
 785 .
 786 Long options can be abbreviated.
 787 .
 788 .
 789 .\" --------------------------------------------------------------------
 790 .SH "OPTION OVERVIEW"
 791 .\" --------------------------------------------------------------------
 792 .
 793 .TP
 794 .I breaking options
 795 .RS
 796 .P
 797 .Opt_[alt] - h -- help
 798 .Opt_[alt] - v -- version
 799 .RE
 800 .
 801 .
 802 .TP
 803 .I \%groffer mode options
 804 .RS
 805 .P
 806 .Opt_[alt] -- auto
 807 .Opt_[alt] -- default
 808 .Opt_[alt] -- default\-modes mode1,mode2,\*[Ellipsis]
 809 .Opt_[alt] -- dvi
 810 .Opt_[alt] -- dvi\-viewer prog
 811 .Opt_[alt] -- dvi\-viewer\-tty prog
 812 .Opt_[alt] -- groff
 813 .Opt_[alt] -- html
 814 .Opt_[alt] -- html\-viewer prog
 815 .Opt_[alt] -- html\-viewer\-tty prog
 816 .Opt_[alt] -- mode display_mode
 817 .Opt_[alt] -- pdf
 818 .Opt_[alt] -- pdf\-viewer prog
 819 .Opt_[alt] -- pdf\-viewer\-tty prog
 820 .Opt_[alt] -- ps
 821 .Opt_[alt] -- ps\-viewer prog
 822 .Opt_[alt] -- ps\-viewer\-tty prog
 823 .Opt_[alt] -- text
 824 .Opt_[alt] -- tty
 825 .Opt_[alt] -- tty\-viewer prog
 826 .Opt_[alt] -- tty\-viewer\-tty prog
 827 .Opt_[alt] -- www
 828 .Opt_[alt] -- www\-viewer prog
 829 .Opt_[alt] -- www\-viewer\- prog
 830 .Opt_[alt] -- x -- X
 831 .Opt_[alt] -- x\-viewer -- X\-viewer prog
 832 .Opt_[alt] -- x\-viewer\-tty -- X\-viewer\-tty prog
 833 .RE
 834 .
 835 .
 836 .TP
 837 .I development options
 838 .RS
 839 .P
 840 .Opt_[alt] -- debug
 841 .Opt_[alt] -- do\-nothing
 842 .Opt_[alt] -- shell prog
 843 .Opt_[alt] - Q -- source
 844 .Opt_[alt] - V
 845 .RE
 846 .
 847 .
 848 .TP
 849 .I options related to \%groff
 850 .RS
 851 .P
 852 .Opt_[alt] - T -- device device
 853 .Opt_[alt] - Z -- intermediate\-output -- ditroff
 854 .P
 855 All further
 856 .B \%groff
 857 short options are accepted.
 858 .RE
 859 .
 860 .
 861 .TP
 862 .I options for man\~pages
 863 .Opt_[alt] -- apropos
 864 .Opt_[alt] -- apropos\-data
 865 .Opt_[alt] -- apropos\-devel
 866 .Opt_[alt] -- apropos\-progs
 867 .Opt_[alt] -- whatis
 868 .Opt_[alt] -- man
 869 .Opt_[alt] -- no-man
 870 .Opt_[alt] -- no-special
 871 .
 872 .
 873 .TP
 874 .I long options taken over from GNU man
 875 .RS
 876 .P
 877 .Opt_[alt] -- all
 878 .Opt_[alt] -- ascii
 879 .Opt_[alt] -- ditroff
 880 .Opt_[alt] -- extension suffix
 881 .Opt_[alt] -- locale language
 882 .Opt_[alt] -- local-file
 883 .Opt_[alt] -- manpath dir1:dir2:\*[Ellipsis]
 884 .Opt_[alt] -- pager program
 885 .Opt_[alt] -- sections sec1:sec2:\*[Ellipsis]
 886 .Opt_[alt] -- systems sys1,sys2,\*[Ellipsis]
 887 .Opt_[alt] -- troff-device device
 888 .P
 889 Further long options of \f[CR]GNU\f[]
 890 .B man
 891 are accepted as well.
 892 .RE
 893 .
 894 .
 895 .TP
 896 .I X Window Toolkit options
 897 .RS
 898 .P
 899 .Opt_[alt] -- bd pixels
 900 .Opt_[alt] -- bg -- background color
 901 .Opt_[alt] -- bw pixels
 902 .Opt_[alt] -- display X-display
 903 .Opt_[alt] -- fg -- foreground color
 904 .Opt_[alt] -- ft -- font font_name
 905 .Opt_[alt] -- geometry size_pos
 906 .Opt_[alt] -- resolution value
 907 .Opt_[alt] -- rv
 908 .Opt_[alt] -- title string
 909 .Opt_[alt] -- xrm X-resource
 910 .RE
 911 .
 912 .
 913 .TP
 914 .I \%filespec arguments
 915 .RS
 916 .P
 917 No
 918 .I \%filespec
 919 parameters means standard input.
 920 .
 921 .
 922 .TP 10m
 923 .Opt_short ""
 924 stands for standard input (can occur several times).
 925 .
 926 .
 927 .TP
 928 .I filename
 929 the path name of an existing file.
 930 .
 931 .
 932 .TP
 933 .BI man: name ( section )
 934 .TP+
 935 .IB name ( section )
 936 search the \%man\~page
 937 .I \%name
 938 in \%man\~section
 939 .IR section .
 940 .
 941 .
 942 .TP
 943 .BI man: name . s
 944 .TP+
 945 .IB name . s
 946 if
 947 .I s
 948 is a character in
 949 .BR \%[1-9on] ,
 950 search for a \%man\~page
 951 .I \%name
 952 in \%man\~section
 953 .IR s .
 954 .
 955 .
 956 .TP
 957 .BI man: name
 958 \%man\~page in the lowest \%man\~section that has
 959 .IR \%name .
 960 .
 961 .
 962 .TP
 963 .I "s name"
 964 if
 965 .I s
 966 is a character in
 967 .BR \%[1-9on] ,
 968 search for a \%man\~page
 969 .I \%name
 970 in \%man\~section
 971 .IR s .
 972 .
 973 .
 974 .TP
 975 .I name
 976 if
 977 .I \%name
 978 is not an existing file search for the man\~page
 979 .I \%name
 980 in the lowest man\~section.
 981 .
 982 .RE
 983 .
 984 .
 985 .\" --------------------------------------------------------------------
 986 .SH "OPTION DETAILS"
 987 .\" --------------------------------------------------------------------
 988 .
 989 The
 990 .B \%groffer
 991 program can usually be run with very few options.
 992 .
 993 But for special purposes, it supports many options.
 994 .
 995 These can be classified in 5 option classes.
 996 .
 997 .
 998 .P
 999 All short options of
1000 .B \%groffer
1001 are compatible with the short options of
1002 .BR \%groff (@MAN1EXT@).
1003 .
1004 All long options of
1005 .B \%groffer
1006 are compatible with the long options of
1007 .BR \%man (1).
1008 .
1009 .
1010 .\" --------------------------------------------------------------------
1011 .SS "groffer breaking Options"
1012 .\" --------------------------------------------------------------------
1013 .
1014 As soon as one of these options is found on the command line it is
1015 executed, printed to standard output, and the running
1016 .B \%groffer
1017 is terminated thereafter.
1018 .
1019 All other arguments are ignored.
1020 .
1021 .
1022 .Opt_def - h -- help
1023 Print a helping information with a short explanation of option sto
1024 standard output.
1025 .
1026 .
1027 .Opt_def - v -- version
1028 Print version information to standard output.
1029 .
1030 .
1031 .\" --------------------------------------------------------------------
1032 .SS "groffer Mode Options"
1033 .\" --------------------------------------------------------------------
1034 .
1035 The display mode and the viewer programs are determined by these
1036 options.
1037 .
1038 If none of these mode and viewer options is specified
1039 .B \%groffer
1040 tries to find a suitable display mode automatically.
1041 .
1042 The default modes are
1043 .I mode x
1044 with
1045 .B gxditview
1046 in \%\f[CR]X\~Window\f[] and
1047 .I mode tty
1048 with device
1049 .I latin1
1050 under
1051 .B less
1052 on a terminal.
1053 .
1054 .
1055 .P
1056 There are two kinds of options for viewers.
1057 .Opt_long \fImode\fP-viewer
1058 chooses the normal viewer programs that run on their own in
1059 \%\f[CR]X\~Window\f[], while
1060 .Opt_long \fImode\fP-viewer-tty
1061 chooses programs that run on the terminal (on tty).
1062 .
1063 Most graphical viewers are programs running in \%\f[CR]X\~Window\f[],
1064 so there aren't many opportunities to call the tty viewers.
1065 .
1066 But they give the chance to view the output source; for example,
1067 .Opt_long ps\-viewer\-tty=less
1068 shows the content of the
1069 .I Postscript
1070 output with the pager
1071 .BR less .
1072 .
1073 .
1074 .P
1075 The \%\f[CR]X\~Window\f[] viewers are not critical, you can use both
1076 .Opt_long *\-viewer
1077 and
1078 .Opt_long *\-viewer\-tty
1079 for them; with
1080 .Opt_long *\-viewer\-tty
1081 the viewer program will not become independently, it just stays
1082 coupled with
1083 .BR groffer .
1084 But the program will not run if you specify a terminal program with
1085 .Opt_long *\-viewer
1086 because this viewer will stay in background without a chance to reach
1087 it.
1088 .
1089 So you really need
1090 .Opt_long *\-viewer\-tty
1091 for viewers that run on tty.
1092 .
1093 .
1094 .Opt_def -- auto
1095 Equivalent to
1096 .Opt_long_arg mode auto .
1097 .
1098 .
1099 .Opt_def -- default
1100 Reset all configuration from previously processed command line options
1101 to the default values.
1102 .
1103 This is useful to wipe out all former options of the configuration, in
1104 .Env_var $GROFFER_OPT ,
1105 and restart option processing using only the rest of the command line.
1106 .
1107 .
1108 .Opt_def -- default\-modes mode1,mode2,\*[Ellipsis]
1109 Set the sequence of modes for
1110 .I \%auto\~mode
1111 to the comma separated list given in the argument.
1112 .
1113 See
1114 .Opt_long mode
1115 for details on modes.  Display in the default manner; actually, this
1116 means to try the modes
1117 .IR x ,
1118 .IR ps ,
1119 and
1120 .I \%tty
1121 in this sequence.
1122 .
1123 .
1124 .
1125 .Opt_def -- dvi
1126 Equivalent to
1127 .Opt_long_arg mode \%dvi .
1128 .
1129 .
1130 .Opt_def -- dvi\-viewer prog
1131 Choose an \%\f[CR]X\~Window\f[] viewer program for
1132 .IR \%dvi\~mode .
1133 .
1134 This can be a file name or a program to be searched in
1135 .Env_var $PATH .
1136 .
1137 Known \%\f[CR]X\~Window\f[]
1138 .I \%dvi
1139 viewers include
1140 .BR \%xdvi (1)
1141 and
1142 .BR \%dvilx (1)
1143 .
1144 In each case, arguments can be provided additionally.
1145 .
1146 .
1147 .Opt_def -- dvi\-viewer\-tty prog
1148 Choose a program running on the terminal for viewing the output of
1149 .IR \%dvi\~mode .
1150 .
1151 This can be a file name or a program to be searched in
1152 .Env_var $PATH ;
1153 arguments can be provided additionally.
1154 .
1155 .
1156 .Opt_def -- groff
1157 Equivalent to
1158 .Opt_long_arg mode groff .
1159 .
1160 .
1161 .Opt_def -- html
1162 Equivalent to
1163 .Opt_long_arg mode html .
1164 .
1165 .
1166 .Opt_def -- html\-viewer
1167 Choose an \%\f[CR]X\~Window\f[] web browser program for viewing in
1168 .I \%html\~mode .
1169 .
1170 It can be the path name of an executable file or a program in
1171 .Env_var $PATH .
1172 .
1173 In each case, arguments can be provided additionally.
1174 .
1175 .
1176 .Opt_def -- html\-viewer\-tty
1177 Choose a terminal program for viewing the output of
1178 .I \%html\~mode .
1179 .
1180 It can be the path name of an executable file or a program in
1181 .Env_var $PATH ;
1182 arguments can be provided additionally.
1183 .
1184 .
1185 .Opt_def -- mode value
1186 .
1187 Set the display mode.
1188 .
1189 The following mode values are recognized:
1190 .
1191 .RS
1192 .
1193 .TP
1194 .Header_CB auto
1195 Select the automatic determination of the display mode.
1196 .
1197 The sequence of modes that are tried can be set with the
1198 .Opt_long default\-modes
1199 option.
1200 .
1201 Useful for restoring the
1202 .I \%default\~mode
1203 when a different mode was specified before.
1204 .
1205 .
1206 .TP
1207 .Header_CB dvi
1208 Display formatted input in a
1209 .I \%dvi
1210 viewer program.
1211 .
1212 By default, the formatted input is displayed with the
1213 .BR \%xdvi (1)
1214 program.
1215 .Opt_long dvi .
1216 .
1217 .
1218 .TP
1219 .Header_CB groff
1220 After the file determination, switch
1221 .B \%groffer
1222 to process the input like
1223 .BR \%groff (@MAN1EXT@)
1224 would do.
1225 .
1226 This disables the
1227 .I \%groffer
1228 viewing features.
1229 .
1230 .
1231 .TP
1232 .Header_CB html
1233 Translate the input into html format and display the result in a web
1234 browser program.
1235 .
1236 By default, the existence of a sequence of standard web browsers is
1237 tested, starting with
1238 .BR \%konqueror (1)
1239 and
1240 .BR \%mozilla (1).
1241 The text html viewer is
1242 .BR \%lynx (1).
1243 .
1244 .
1245 .TP
1246 .Header_CB pdf
1247 Display formatted input in a
1248 .I \%PDF
1249 (Portable Document Format) viewer
1250 program.
1251 .
1252 By default, the input is formatted by
1253 .B \%groff
1254 using the Postscript device, then it is transformed into the PDF file
1255 format using
1256 .BR \%gs (1),
1257 and finally displayed either with the
1258 .BR \%xpdf (1)
1259 or the
1260 .BR \%acroread (1)
1261 program.
1262 .
1263 PDF has a big advantage because the text is displayed graphically and
1264 is searchable as well.
1265 .
1266 But as the transformation takes a considerable amount of time, this
1267 mode is not suitable as a default device for the
1268 .I \%auto\~mode .
1269 .
1270 .
1271 .TP
1272 .Header_CB ps
1273 Display formatted input in a Postscript viewer program.
1274 .
1275 By default, the formatted input is displayed with the
1276 .BR \%ghostview (@MAN1EXT@)
1277 program.
1278 .
1279 .
1280 .TP
1281 .Header_CB text
1282 Format in a
1283 .I \%groff\~text\~mode
1284 and write the result to standard output without a pager or viewer
1285 program.
1286 .
1287 The text device,
1288 .I \%latin1
1289 by default, can be chosen with option
1290 .Opt_short T .
1291 .
1292 .
1293 .TP
1294 .Header_CB tty
1295 Format in a
1296 .I \%groff\~text\~mode
1297 and write the result to standard output using a text pager program,
1298 even when in \%\f[CR]X\~Window\f[].
1299 .
1300 .
1301 .TP
1302 .Header_CB www
1303 Equivalent to
1304 .Opt_long_arg mode html .
1305 .
1306 .
1307 .TP
1308 .Header_CB x
1309 Display the formatted input in a native
1310 .I roff
1311 viewer.
1312 .
1313 By default, the formatted input is displayed with the
1314 .BR \%gxditview (@MAN1EXT@)
1315 program being distributed together with
1316 .BR \%groff .
1317 But the standard \%\f[CR]X\~Window\f[] tool
1318 .BR \%xditview (1)
1319 can also be chosen with the option
1320 .Opt_long x\-viewer .
1321 The default resolution is
1322 .BR 75\~dpi ,
1323 but
1324 .B 100\~dpi
1325 are also possible.
1326 .
1327 The default
1328 .I groff
1329 device
1330 for the resolution of
1331 .B 75\~dpi
1332 is
1333 .BR X75\-12 ,
1334 for
1335 .B 100\~dpi
1336 it is
1337 .BR X100 .
1338 .
1339 The corresponding
1340 .I "groff intermediate output"
1341 for the actual device is generated and the result is displayed.
1342 .
1343 For a resolution of
1344 .BR 100\~dpi ,
1345 the default width of the geometry of the display program is chosen to
1346 .BR 850\~dpi .
1347 .
1348 .
1349 .TP
1350 .Header_CB X
1351 Equivalent to
1352 .Opt_long_arg mode x .
1353 .
1354 .
1355 .P
1356 The following modes do not use the
1357 .I \%groffer
1358 viewing features.
1359 .
1360 They are only interesting for advanced applications.
1361 .
1362 .
1363 .TP
1364 .Header_CB groff
1365 Generate device output with plain
1366 .I \%groff
1367 without using the special viewing features of
1368 .IR \%groffer .
1369 If no device was specified by option
1370 .Opt_short T
1371 the
1372 .I \%groff
1373 default
1374 .B \%ps
1375 is assumed.
1376 .
1377 .
1378 .TP
1379 .Header_CB source
1380 Display the source code of the input without formatting; equivalent to
1381 .Opt_short Q .
1382 .
1383 .
1384 .RE
1385 .
1386 .
1387 .Opt_def -- pdf
1388 Equivalent to
1389 .Opt_long_arg mode pdf .
1390 .
1391 .
1392 .Opt_def -- pdf\-viewer prog
1393 Choose an \%\f[CR]X\~Window\f[] viewer program for
1394 .IR \%pdf\~mode .
1395 .
1396 This can be a file name or a program to be searched in
1397 .Env_var $PATH ;
1398 arguments can be provided additionally.
1399 .
1400 .
1401 .Opt_def -- pdf\-viewer\-tty prog
1402 Choose a terminal viewer program for
1403 .IR \%pdf\~mode .
1404 .
1405 This can be a file name or a program to be searched in
1406 .Env_var $PATH ;
1407 arguments can be provided additionally.
1408 .
1409 .
1410 .Opt_def -- ps
1411 Equivalent to
1412 .Opt_long_arg mode ps .
1413 .
1414 .
1415 .Opt_def -- ps\-viewer prog
1416 Choose an \%\f[CR]X\~Window\f[] viewer program for
1417 .IR \%ps\~mode .
1418 .
1419 This can be a file name or a program to be searched in
1420 .Env_var $PATH .
1421 .
1422 Common Postscript viewers inlude
1423 .BR \%gv (1),
1424 .BR \%ghostview (1),
1425 and
1426 .BR \%gs (1),
1427 .
1428 In each case, arguments can be provided additionally.
1429 .
1430 .
1431 .Opt_def -- ps\-viewer\-tty prog
1432 Choose a terminal viewer program for
1433 .IR \%ps\~mode .
1434 .
1435 This can be a file name or a program to be searched in
1436 .Env_var $PATH ;
1437 arguments can be provided additionally.
1438 .
1439 .
1440 .Opt_def -- text
1441 Equivalent to
1442 .Opt_long_arg mode text .
1443 .
1444 .
1445 .Opt_def -- tty
1446 Equivalent to
1447 .Opt_long_arg mode tty .
1448 .
1449 .
1450 .Opt_def -- tty\-viewer prog
1451 Choose a text pager for mode
1452 .IR tty .
1453 The standard pager is
1454 .BR less (1).
1455 This option is eqivalent to
1456 .I man
1457 option
1458 .Opt_long_arg pager prog .
1459 The option argument can be a file name or a program to be searched in
1460 .Env_var $PATH ;
1461 arguments can be provided additionally.
1462 .
1463 .
1464 .Opt_def -- tty\-viewer\-tty prog
1465 This is equivalent to
1466 .Opt_long tty\-viewer
1467 because the programs for
1468 .I tty
1469 mode run on a terminal anyway.
1470 .
1471 .
1472 .Opt_def -- www
1473 Equivalent to
1474 .Opt_long_arg mode html .
1475 .
1476 .
1477 .Opt_def -- www\-viewer prog
1478 Equivalent to
1479 .Opt_long html\-viewer .
1480 .
1481 .
1482 .Opt_def -- www\-viewer\-tty prog
1483 Equivalent to
1484 .Opt_long html\-viewer\-tty .
1485 .
1486 .
1487 .Opt_def -- X -- x
1488 Equivalent to
1489 .Opt_long_arg mode x .
1490 .
1491 .
1492 .Opt_def -- X\-viewer -- x\-viewer prog
1493 Choose an \%\f[CR]X\~Window\f[] viewer program for
1494 .IR \%x\~mode .
1495 Suitable viewer programs are
1496 .BR \%gxditview (@MAN1EXT@)
1497 which is the default and
1498 .BR \%xditview (1).
1499 The argument can be any executable file or a program in
1500 .Env_var $PATH ;
1501 arguments can be provided additionally.
1502 .
1503 .
1504 .Opt_def -- X\-viewer\-tty -- x\-viewer\-tty prog
1505 Choose a terminal viewer program for
1506 .IR \%x\~mode .
1507 The argument can be any executable file or a program in
1508 .Env_var $PATH ;
1509 arguments can be provided additionally.
1510 .
1511 .
1512 .TP
1513 .Opt_--
1514 Signals the end of option processing; all remaining arguments are
1515 interpreted as
1516 .I \%filespec
1517 parameters.
1518 .
1519 .
1520 .P
1521 Besides these,
1522 .B \%groffer
1523 accepts all short options that are valid for the
1524 .BR \%groff (@MAN1EXT@)
1525 program.
1526 .
1527 All
1528 .RB \%non- groffer
1529 options are sent unmodified via
1530 .B \%grog
1531 to
1532 .BR \%groff .
1533 .
1534 So postprocessors, macro packages, compatibility with
1535 .I classical
1536 .IR \%troff ,
1537 and much more can be manually specified.
1538 .
1539 .
1540 .\" --------------------------------------------------------------------
1541 .SH "Options for Development"
1542 .\" --------------------------------------------------------------------
1543 .
1544 .Opt_def -- debug
1545 Enable five debugging informations.
1546 .
1547 The temporary files are kept and not deleted, the name of the
1548 temporary directory and the shell name for
1549 .File_name groffer2.sh
1550 are printed, the parameters are printed at several steps of
1551 development, and a function stack is output with function
1552 \f[CR]error_user()\f[] as well.
1553 .
1554 Neither the function call stack that is printed at each opening and
1555 closing of a function call nor the landmark information that is
1556 printed to determine how far the program is running are used.
1557 .
1558 This seems to be the most useful among all debugging options.
1559 .
1560 .
1561 .Opt_def -- debug\-all
1562 Enable all seven debugging informations including the function call
1563 stack and the landmark information.
1564 .
1565 .
1566 .Opt_def -- debug\-keep
1567 Enable two debugging information, the printing of the name of the
1568 temporary directory and the keeping of the temporary files.
1569 .
1570 .
1571 .Opt_def -- debug\-lm
1572 Enable one debugging information, the landmark information.
1573 .
1574 .
1575 .Opt_def -- debug\-params
1576 Enable one debugging information, the parameters at several steps.
1577 .
1578 .
1579 .Opt_def -- debug\-shell
1580 Enable one debugging information, the shell name for
1581 .File_name groffer2.sh .
1582 .
1583 .
1584 .Opt_def -- debug\-stacks
1585 Enable one debugging information, the function call stack.
1586 .
1587 .
1588 .Opt_def -- debug\-tmpdir
1589 Enable one debugging information, the name of the temporary directory.
1590 .
1591 .
1592 .Opt_def -- debug\-user
1593 Enable one debugging information, the function stack with
1594 \f[CR]error_user()\f[].
1595 .
1596 .
1597 .Opt_def -- do-nothing
1598 This is like
1599 .Opt_long version ,
1600 but without the output; no viewer is started.
1601 .
1602 This makes only sense in development.
1603 .
1604 .
1605 .Opt_def -- print=text
1606 Just print the argument to standard error.
1607 .
1608 This is good for parameter check.
1609 .
1610 .
1611 .Opt_def -- shell "shell_program"
1612 Specify the shell under which the
1613 .File_name \%groffer2.sh
1614 script should be run.
1615 .
1616 This option overwrites the automatic shell determination of the
1617 program.
1618 .
1619 If the argument
1620 .I shell_program
1621 is empty a former shell option and the automatic shell determination
1622 is cancelled and the default shell is restored.
1623 .
1624 Some shells run considerably faster than the standard shell.
1625 .
1626 .
1627 .Opt_def - Q -- source
1628 Output the roff source code of the input files without further
1629 processing.
1630 .
1631 This is the equivalent
1632 .Opt_long_arg mode source .
1633 .
1634 .
1635 .Opt_def - V
1636 This is an advanced option for debugging only.
1637 .
1638 Instead of displaying the formatted input, a lot of
1639 .I \%groffer
1640 specific information is printed to standard output:
1641 .
1642 .RS
1643 .Topic
1644 the output file name in the temporary directory,
1645 .
1646 .Topic
1647 the display mode of the actual
1648 .B \%groffer
1649 run,
1650 .
1651 .Topic
1652 the display program for viewing the output with its arguments,
1653 .
1654 .Topic
1655 the active parameters from the config files, the arguments in
1656 .Env_var $GROFFER_OPT ,
1657 and the arguments of the command line,
1658 .
1659 .Topic
1660 the pipeline that would be run by the
1661 .B \%groff
1662 program, but without executing it.
1663 .RE
1664 .
1665 .
1666 .P
1667 Other useful debugging options are the
1668 .B \%groff
1669 option
1670 .Opt_short Z
1671 and
1672 .Opt_long_arg mode groff .
1673 .
1674 .
1675 .\" --------------------------------------------------------------------
1676 .SH "Options related to groff"
1677 .\" --------------------------------------------------------------------
1678 .
1679 All short options of
1680 .B \%groffer
1681 are compatible with the short options of
1682 .BR \%groff (@MAN1EXT@).
1683 .
1684 The following of
1685 .B \%groff
1686 options have either an additional special meaning within
1687 .B \%groffer
1688 or make sense for normal usage.
1689 .
1690 .
1691 .P
1692 Because of the special outputting behavior of the
1693 .B \%groff
1694 option
1695 .Opt_short Z
1696 .B \%groffer
1697 was designed to be switched into
1698 .I \%groff\~mode ;
1699 the
1700 .I \%groffer
1701 viewing features are disabled there.
1702 .
1703 The other
1704 .B \%groff
1705 options do not switch the mode, but allow to customize the formatting
1706 process.
1707 .
1708 .
1709 .Opt_def - a
1710 This generates an ascii approximation of output in the
1711 .IR \%text\~modes .
1712 .
1713 That could be important when the text pager has problems with control
1714 sequences in
1715 .IR "tty mode" .
1716 .
1717 .
1718 .Opt_def - m file
1719 Add
1720 .I \%file
1721 as a
1722 .I \%groff
1723 macro file.
1724 .
1725 This is useful in case it cannot be recognized automatically.
1726 .
1727 .
1728 .Opt_def - P opt_or_arg
1729 Send the argument
1730 .I \%opt_or_arg
1731 as an option or option argument to the actual
1732 .B \%groff
1733 postprocessor.
1734 .
1735 .
1736 .Opt_def - T -- device devname
1737 .
1738 This option determines
1739 .BR \%groff 's
1740 output device.
1741 .
1742 The most important devices are the text output devices for referring
1743 to the different character sets, such as
1744 .BR \%ascii ,
1745 .BR \%utf8 ,
1746 .BR \%latin1 ,
1747 and others.
1748 .
1749 Each of these arguments switches
1750 .B \%groffer
1751 into a
1752 .I \%text\~mode
1753 using this device, to
1754 .I \%mode\~tty
1755 if the actual mode is not a
1756 .IR \%text\~mode .
1757 .
1758 The following
1759 .I \%devname
1760 arguments are mapped to the corresponding
1761 .B \%groffer
1762 .Opt_long_arg mode \fIdevname\fR
1763 option:
1764 .BR \%dvi ,
1765 .BR \%html ,
1766 and
1767 .BR \%ps .
1768 All
1769 .B \%X*
1770 arguments are mapped to
1771 .IR \%mode\~x .
1772 Each other
1773 .I \%devname
1774 argument switches to
1775 .I \%mode\~groff
1776 using this device.
1777 .
1778 .
1779 .Opt_def - X
1780 is equivalent to
1781 .BR "groff \-X" .
1782 It displays the
1783 .I groff intermediate output
1784 with
1785 .BR gxditview .
1786 As the quality is relatively bad this option is deprecated; use
1787 .Opt_long X
1788 instead because the
1789 .I \%x\~mode
1790 uses an
1791 .IR X *
1792 device for a better display.
1793 .
1794 .
1795 .Opt_def - Z -- intermediate-output -- ditroff
1796 Switch into
1797 .I \%groff\~mode
1798 and format the input with the
1799 .I \%groff intermediate output
1800 without postprocessing; see
1801 .BR \%groff_out (@MAN5EXT@).
1802 This is equivalent to option
1803 .Opt_long ditroff
1804 of
1805 .IR \%man ,
1806 which can be used as well.
1807 .
1808 .
1809 .P
1810 All other
1811 .B \%groff
1812 options are supported by
1813 .BR \%groffer ,
1814 but they are just transparently transferred to
1815 .B \%groff
1816 without any intervention.
1817 .
1818 The options that are not explicitly handled by
1819 .B \%groffer
1820 are transparently passed to
1821 .BR \%groff .
1822 .
1823 Therefore these transparent options are not documented here, but in
1824 .BR \%groff (@MAN1EXT@).
1825 Due to the automatism in
1826 .BR \%groffer ,
1827 none of these
1828 .B \%groff
1829 options should be needed, except for advanced usage.
1830 .
1831 .
1832 .\" --------------------------------------------------------------------
1833 .SS "Options for man\~pages"
1834 .\" --------------------------------------------------------------------
1835 .
1836 .Opt_def -- apropos
1837 Start the
1838 .BR \%apropos (1)
1839 command or facility of
1840 .BR \%man (1)
1841 for searching the
1842 .I \%filespec
1843 arguments within all
1844 .I \%man\~page
1845 descriptions.
1846 .
1847 Each
1848 .I \%filespec
1849 argument is taken for search as it is; section specific parts are not
1850 handled, such that
1851 .B 7 groff
1852 searches for the two arguments
1853 .B 7
1854 and
1855 .B groff
1856 with a large result; for the
1857 .I \%filespec
1858 .B groff.7
1859 nothing will be found.
1860 .
1861 The display differs from the
1862 .B \%apropos
1863 program by the following concepts:
1864 .RS
1865 .Topic
1866 construct a
1867 .I \%groff
1868 frame to the output of
1869 .BR \%apropos ,
1870 .Topic
1871 each
1872 .I \%filespec
1873 argument is searched on its own.
1874 .Topic
1875 the restriction by
1876 .Opt_long sections
1877 is handled as well,
1878 .Topic
1879 wildcard characters are allowed and handled without a further option.
1880 .RE
1881 .
1882 .
1883 .Opt_def -- apropos\-data
1884 Show only the
1885 .B \%apropos
1886 descriptions for data documents, these are the
1887 .BR \%man (7)
1888 sections 4, 5, and 7.
1889 .
1890 Direct section declarations are ignored, wildcards are accepted.
1891 .
1892 .
1893 .Opt_def -- apropos\-devel
1894 Show only the
1895 .B \%apropos
1896 descriptions for development documents, these are the
1897 .BR man (7)
1898 sections 2, 3, and 9.
1899 .
1900 Direct section declarations are ignored, wildcards are accepted.
1901 .
1902 .
1903 .Opt_def -- apropos\-progs
1904 Show only the
1905 .B \%apropos
1906 descriptions for documents on programs, these are the
1907 .BR \%man (7)
1908 sections 1, 6, and 8.
1909 .
1910 Direct section declarations are ignored, wildcards are accepted.
1911 .
1912 .
1913 .Opt_def -- whatis
1914 For each
1915 .I \%filespec
1916 argument search all
1917 .I \%man\~pages
1918 and display their description \[em] or say that it is not a
1919 .IR \%man\~page .
1920 This differs from
1921 .IR man 's
1922 .B whatis
1923 output by the following concepts
1924 .RS
1925 .Topic
1926 each retrieved file name is added,
1927 .Topic
1928 local files are handled as well,
1929 .Topic
1930 the display is framed by a
1931 .I groff
1932 output format,
1933 .Topic
1934 wildcard characters are allowed without a further option.
1935 .RE
1936 .
1937 .
1938 .P
1939 The following two options were added to
1940 .B \%groffer
1941 for choosing whether the file name arguments are interpreted as names
1942 for local files or as a search pattern for
1943 .IR \%man\~pages .
1944 .
1945 The default is looking up for local files.
1946 .
1947 .
1948 .Opt_def -- man
1949 Check the non-option command line arguments
1950 .nh
1951 .RI ( filespecs )
1952 .hy
1953 first on being
1954 .IR \%man\~pages ,
1955 then whether they represent an existing file.
1956 .
1957 By default, a
1958 .I \%filespec
1959 is first tested whether it is an existing file.
1960 .
1961 .
1962 .Opt_def -- no-man -- local-file
1963 Do not check for
1964 .IR \%man\~pages .
1965 .
1966 .Opt_long local-file
1967 is the corresponding
1968 .B man
1969 option.
1970 .
1971 .
1972 .Opt_def -- no-special
1973 Disable former calls of
1974 .Opt_long all ,
1975 .Opt_long apropos* ,
1976 and
1977 .Opt_long whatis .
1978 .
1979 .
1980 .\" --------------------------------------------------------------------
1981 .SS "Long options taken over from GNU man"
1982 .\" --------------------------------------------------------------------
1983 .
1984 The long options of
1985 .B \%groffer
1986 were synchronized with the long options of \f[CR]GNU\f[]
1987 .BR man .
1988 .
1989 All long options of \f[CR]GNU\f[]
1990 .B man
1991 are recognized, but not all of these options are important to
1992 .BR \%groffer ,
1993 so most of them are just ignored.
1994 .
1995 .
1996 .P
1997 In the following, the
1998 .B man
1999 options that have a special meaning for
2000 .B \%groffer
2001 are documented.
2002 .
2003 .
2004 .P
2005 The full set of long and short options of the \f[CR]GNU\f[]
2006 .B man
2007 program can be passed via the environment variable
2008 .Env_var $MANOPT ;
2009 see
2010 .BR \%man (1)
2011 if your system has \f[CR]GNU\f[]
2012 .B man
2013 installed.
2014 .
2015 .
2016 .Opt_def -- all
2017 In searching
2018 .IR \%man\~pages ,
2019 retrieve all suitable documents instead of only one.
2020 .
2021 .
2022 .Opt_def - 7 -- ascii
2023 In
2024 .IR \%text\~modes ,
2025 display ASCII translation of special characters for critical environment.
2026 .
2027 This is equivalent to
2028 .BR "groff -mtty_char" ;
2029 see
2030 .BR groff_tmac (@MAN5EXT@).
2031 .
2032 .
2033 .Opt_def -- ditroff
2034 Eqivalent to
2035 .B \%groffer
2036 .Opt_short Z .
2037 .
2038 .
2039 .Opt_def -- extension suffix
2040 Restrict
2041 .I \%man\~page
2042 search to file names that have
2043 .I \%suffix
2044 appended to their section element.
2045 .
2046 For example, in the file name
2047 .I \%/usr/share/man/man3/terminfo.3ncurses.gz
2048 the
2049 .I \%man\~page
2050 extension is
2051 .IR \%ncurses .
2052 .
2053 .
2054 .Opt_def -- locale language
2055 .
2056 Set the language for
2057 .IR \%man\~pages .
2058 .
2059 This has the same effect, but overwrites
2060 .Env_var $LANG
2061 .
2062 .
2063 .Opt_def -- location
2064 Print the location of the retrieved files to standard error.
2065 .
2066 .
2067 .Opt_def -- no-location
2068 Do not display the location of retrieved files; this resets a former
2069 call to
2070 .Opt_long location .
2071 .
2072 This was added by
2073 .BR \%groffer .
2074 .
2075 .
2076 .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'"
2077 Use the specified search path for retrieving
2078 .I \%man\~pages
2079 instead of the program defaults.
2080 .
2081 If the argument is set to the empty string "" the search for
2082 .I \%man\~page
2083 is disabled.
2084 .
2085 .
2086 .Opt_def -- pager
2087 Set the pager program in
2088 .IR \%tty\~mode ;
2089 default is
2090 .BR \%less .
2091 This is equivalent to
2092 .Opt_long tty\-viewer .
2093 .
2094 .
2095 .Opt_def -- sections "'sec1:sec2:\*[Ellipsis]'"
2096 Restrict searching for
2097 .I \%man\~pages
2098 to the given
2099 .IR sections ,
2100 a colon-separated list.
2101 .
2102 .
2103 .Opt_def -- systems "'sys1,sys2,\*[Ellipsis]'"
2104 Search for
2105 .I \%man\~pages
2106 for the given operating systems; the argument
2107 .I \%systems
2108 is a comma-separated list.
2109 .
2110 .
2111 .Opt_def -- where
2112 Eqivalent to
2113 .Opt_long location .
2114 .
2115 .
2116 .\" --------------------------------------------------------------------
2117 .SS "X\~\%Window\~\%Toolkit Options"
2118 .\" --------------------------------------------------------------------
2119 .
2120 The following long options were adapted from the corresponding
2121 \%\f[CR]X\~\Window\~Toolkit\f[] options.
2122 .
2123 .B \%groffer
2124 will pass them to the actual viewer program if it is an
2125 \%\f[CR]X\~Window\f[] program.
2126 .
2127 Otherwise these options are ignored.
2128 .
2129 .
2130 .P
2131 Unfortunately these options use the old style of a single minus for
2132 long options.
2133 .
2134 For
2135 .B \%groffer
2136 that was changed to the standard with using a double minus for long
2137 options, for example,
2138 .B \%groffer
2139 uses the option
2140 .Opt_long font
2141 for the \%\f[CR]X\~Window\f[] option
2142 .Opt_short font .
2143 .
2144 .
2145 .P
2146 See
2147 .BR \%X (1),
2148 .BR \%X (7),
2149 and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
2150 for more details on these options and their arguments.
2151 .
2152 .
2153 .Opt_def -- background color
2154 Set the background color of the viewer window.
2155 .
2156 .
2157 .Opt_def -- bd pixels
2158 Specifies the color of the border surrounding the viewer window.
2159 .
2160 .
2161 .Opt_def -- bg color
2162 This is equivalent to
2163 .Opt_long background .
2164 .
2165 .
2166 .Opt_def -- bw pixels
2167 Specifies the width in pixels of the border surrounding the viewer
2168 window.
2169 .
2170 .
2171 .Opt_def -- display X-display
2172 Set the \%\f[CR]X\~Window\f[] display on which the viewer program
2173 shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
2174 syntax of the argument.
2175 .
2176 .
2177 .Opt_def -- foreground color
2178 Set the foreground color of the viewer window.
2179 .
2180 .
2181 .Opt_def -- fg color
2182 This is equivalent to
2183 .Opt_short foreground .
2184 .
2185 .
2186 .Opt_def -- font font_name
2187 Set the font used by the viewer window.
2188 .
2189 The argument is an \%\f[CR]X\~Window\f[] font name.
2190 .
2191 .
2192 .Opt_def -- ft font_name
2193 This is equivalent to
2194 .Opt_long ft .
2195 .
2196 .
2197 .Opt_def -- geometry size_pos
2198 Set the geometry of the display window, that means its size and its
2199 starting position.
2200 .
2201 See
2202 .BR \%X (7)
2203 for the syntax of the argument.
2204 .
2205 .
2206 .Opt_def -- resolution value
2207 Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
2208 viewer programs.
2209 .
2210 The only supported dpi values are
2211 .B 75
2212 and
2213 .BR 100 .
2214 .
2215 Actually, the default resolution for
2216 .B \%groffer
2217 is set to
2218 .BR 75\~dpi .
2219 The resolution also sets the default device in
2220 .IR "mode x" .
2221 .
2222 .
2223 .Opt_def -- rv
2224 Reverse foreground and background color of the viewer window.
2225 .
2226 .
2227 .Opt_def -- title "'some text'"
2228 Set the title for the viewer window.
2229 .
2230 .
2231 .Opt_def -- xrm "'resource'"
2232 Set \f[CR]\%X\~Window\f[] resource.
2233 .
2234 .
2235 .\" --------------------------------------------------------------------
2236 .SS "Filespec Arguments"
2237 .\" --------------------------------------------------------------------
2238 .
2239 A
2240 .I \%filespec
2241 parameter is an argument that is not an option or option argument.
2242 .
2243 It means an input source.
2244 .
2245 In
2246 .BR \%groffer ,
2247 .I \%filespec
2248 parameters are a file name or a template for searching
2249 .IR \%man\~pages .
2250 .
2251 These input sources are collected and composed into a single output
2252 file such as
2253 .B \%groff
2254 does.
2255 .
2256 .
2257 .P
2258 The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
2259 the first non-option argument as
2260 .I \%filespec
2261 arguments is ignored.
2262 .
2263 The \f[CR]GNU\f[] behavior to recognize options even when mixed with
2264 .I \%filespec
2265 arguments is used througout.
2266 .
2267 But, as usual, the double minus argument
2268 .Opt_long
2269 ends the option handling and interprets all following arguments as
2270 .I \%filespec
2271 arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
2272 .
2273 .
2274 .P
2275 For the following, it is necessary to know that on each system the
2276 .I \%man\~pages
2277 are sorted according to their content into several sections.
2278 .
2279 The
2280 .I classical man sections
2281 have a single-character name, either a digit from
2282 .B 1
2283 to
2284 .B 9
2285 or one of the characters
2286 .B n
2287 or
2288 .BR o .
2289 .
2290 In the following, a stand-alone character
2291 .I s
2292 stands for a
2293 .IR "classical man section" .
2294 The internal precedence of
2295 .B \%man
2296 for searching
2297 .I \%man\~pages
2298 with the same name within several sections goes according to the
2299 classical single-character sequence.
2300 .
2301 On some systems, this single character can be extended by a following
2302 string.
2303 .
2304 But the special
2305 .B \%groffer
2306 .I \%man\~page
2307 facility is based on the classical single character sections.
2308 .
2309 .
2310 .P
2311 Each
2312 .I \%filespec
2313 parameter can have one of the following forms in decreasing sequence.
2314 .
2315 .
2316 .Topic
2317 No
2318 .I \%filespec
2319 parameters means that
2320 .B \%groffer
2321 waits for standard input.
2322 .
2323 The minus option
2324 .Opt_short ""
2325 stands for standard input, too; it can occur several times.
2326 .
2327 .
2328 .Topic
2329 Next a
2330 .I \%filespec
2331 is tested whether it is the path name of an existing file.
2332 .
2333 Otherwise it is assumed to be a searching pattern for a
2334 .IR \%man\~page .
2335 .
2336 .
2337 .Topic
2338 .BI \%man: name ( section )
2339 and
2340 .IB \%name ( section )
2341 search the \%man\~page
2342 .I \%name
2343 in \%man\~section\~\c
2344 .IR \%section ,
2345 where
2346 .I \%section
2347 can be any string, but it must exist in the
2348 .I \%man
2349 system.
2350 .
2351 .
2352 .Topic
2353 Next some patterns based on the
2354 .I classical man sections
2355 are checked.
2356 .
2357 .BI \%man: name . s
2358 and
2359 .IB \%name . s
2360 search for a \%man\~page
2361 .I \%name
2362 in \%man\~section
2363 .I s
2364 if
2365 .I s
2366 is a
2367 .I classical man section
2368 mentioned above.
2369 .
2370 Otherwise a
2371 .I \%man\~page
2372 named
2373 .IR \%name.s
2374 is searched in the lowest
2375 .B man\~section .
2376 .
2377 .
2378 .Topic
2379 Now
2380 .BI \%man: name
2381 searches for a
2382 .I \%man\~page
2383 in the lowest
2384 .I \%man\~section
2385 that has a document called
2386 .IR \%name .
2387 .
2388 .
2389 .Topic
2390 The pattern
2391 .I \%s\~name
2392 originates from a strange argument parsing of the
2393 .B man
2394 program.
2395 .
2396 If
2397 .I s
2398 is a
2399 .I classical man section
2400 interpret it as a search for a
2401 .I \%man\~page
2402 called
2403 .I \%name
2404 in man\~section
2405 .IR s ,
2406 otherwise interpret both
2407 .I s
2408 and
2409 .I \%name
2410 as two independent
2411 .I \%filespec
2412 arguments.
2413 .
2414 .
2415 .Topic
2416 We are left with the argument
2417 .I \%name
2418 which is not an existing file.
2419 .
2420 So this searches for the
2421 .I \%man\~page
2422 called
2423 .I \%name
2424 in the lowest
2425 .I \%man\~section
2426 that has a document for this name.
2427 .
2428 .
2429 .P
2430 Wildcards in
2431 .I \%filespec
2432 arguments are only accepted for
2433 .Opt_long apropos*
2434 and
2435 .Opt_long whatis ;
2436 for normal display, they are interpreted as characters.
2437 .
2438 .
2439 .P
2440 Several file name arguments can be supplied.
2441 .
2442 They are mixed by
2443 .B \%groff
2444 into a single document.
2445 .
2446 Note that the set of option arguments must fit to all of these file
2447 arguments.
2448 .
2449 So they should have at least the same style of the
2450 .I \%groff
2451 language.
2452 .
2453 .
2454 .\" --------------------------------------------------------------------
2455 .SH "OUTPUT MODES"
2456 .\" --------------------------------------------------------------------
2457 .
2458 By default, the
2459 .B \%groffer
2460 program collects all input into a single file, formats it with the
2461 .B \%groff
2462 program for a certain device, and then chooses a suitable viewer
2463 program.
2464 .
2465 The device and viewer process in
2466 .B \%groffer
2467 is called a
2468 .IR \%mode .
2469 .
2470 The mode and viewer of a running
2471 .B \%groffer
2472 program is selected automatically, but the user can also choose it
2473 with options.
2474 .
2475 .
2476 The modes are selected by option the arguments of
2477 .Opt_long_arg mode \fIanymode .
2478 Additionally, each of this argument can be specified as an option of
2479 its own, such as
2480 .Opt_long \fIanymode .
2481 Most of these modes have a viewer program, which can be chosen by an
2482 option that is constructed like
2483 .Opt_long \fIanymode\fR\-viewer .
2484 .
2485 .
2486 .P
2487 Several different modes are offered, graphical modes for
2488 \f[CR]\%X\~Window\f[],
2489 .IR \%text\~modes ,
2490 and some direct
2491 .I \%groff\~modes
2492 for debugging and development.
2493 .
2494 .
2495 .P
2496 By default,
2497 .B \%groffer
2498 first tries whether
2499 .I \%x\~mode
2500 is possible, then
2501 .IR \%ps\~mode ,
2502 and finally
2503 .IR \%tty\~mode .
2504 .
2505 This mode testing sequence for
2506 .I \%auto\~mode
2507 can be changed by specifying a comma separated list of modes with the
2508 option
2509 .Opt_long default\-modes.
2510 .
2511 .
2512 .P
2513 The searching for
2514 .I \%man\~pages
2515 and the decompression of the input are active in every mode.
2516 .
2517 .
2518 .\" --------------------------------------------------------------------
2519 .SS "Graphical Display Modes"
2520 .\" --------------------------------------------------------------------
2521 .
2522 The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
2523 environment (or similar implementations within other windowing
2524 environments).
2525 .
2526 The environment variable
2527 .Env_var $DISPLAY
2528 and the option
2529 .Opt_long display
2530 are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
2531 .
2532 If this environment variable is empty
2533 .B \%groffer
2534 assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
2535 .IR \%text\~mode .
2536 .
2537 You can change this automatic behavior by the option
2538 .Opt_long default\-modes .
2539 .
2540 .
2541 .P
2542 Known viewers for the graphical display modes and their standard
2543 \%\f[CR]X\~Window\f[] viewer progams are
2544 .
2545 .Topic
2546 \%\f[CR]X\~Window\f[]
2547 .I roff
2548 viewers such as
2549 .BR \%gxditview (@MAN1EXT@)
2550 or
2551 .BR \%xditview (1)
2552 (in
2553 .IR \%x\~mode ),
2554 .
2555 .Topic
2556 in a Postscript viewer
2557 .nh
2558 .RI ( \%ps\~mode ),
2559 .hy
2560 .
2561 .Topic
2562 in a dvi viewer program
2563 .nh
2564 .RI ( \%dvi\~mode ),
2565 .hy
2566 .
2567 .Topic
2568 in a PDF viewer
2569 .nh
2570 .RI ( \%pdf\~mode ),
2571 .hy
2572 .
2573 .Topic
2574 in a web browser
2575 .nh
2576 .RI ( html
2577 or
2578 .IR \%www\~mode ).
2579 .hy
2580 .RE
2581 .
2582 .
2583 .P
2584 The
2585 .I \%pdf\~mode
2586 has a major advantage \[em] it is the only graphical diplay mode that
2587 allows to search for text within the viewer; this can be a really
2588 important feature.
2589 .
2590 Unfortunately, it takes some time to transform the input into the PDF
2591 format, so it was not chosen as the major mode.
2592 .
2593 .
2594 .P
2595 These graphical viewers can be customized by options of the
2596 \%\f[CR]X\~Window\~Toolkit\f[].
2597 .
2598 But the
2599 .B \%groffer
2600 options use a leading double minus instead of the single minus used by
2601 the \%\f[CR]X\~Window\~Toolkit\f[].
2602 .
2603 .
2604 .\" --------------------------------------------------------------------
2605 .SS "Text modes"
2606 .\" --------------------------------------------------------------------
2607 .
2608 There are two modes for text output,
2609 .I \%mode\~text
2610 for plain output without a pager and
2611 .I \%mode\~tty
2612 for a text output on a text terminal using some pager program.
2613 .
2614 .
2615 .P
2616 If the variable
2617 .Env_var \%$DISPLAY
2618 is not set or empty,
2619 .B \%groffer
2620 assumes that it should use
2621 .IR \%tty\~\%mode .
2622 .
2623 .
2624 .P
2625 In the actual implementation, the
2626 .I groff
2627 output device
2628 .I \%latin1
2629 is chosen for
2630 .IR \%text\~modes .
2631 .
2632 This can be changed by specifying option
2633 .Opt_short T
2634 or
2635 .Opt_long device .
2636 .
2637 .
2638 .P
2639 The pager to be used can be specified by one of the options
2640 .Opt_long pager
2641 and
2642 .Opt_long tty\-viewer ,
2643 or by the environment variable
2644 .Env_var $PAGER .
2645 If all of this is not used the
2646 .BR \%less (1)
2647 program with the option
2648 .Opt_short r
2649 for correctly displaying control sequences is used as the default
2650 pager.
2651 .
2652 .
2653 .\" --------------------------------------------------------------------
2654 .SS "Special Modes for Debugging and Development"
2655 .\" --------------------------------------------------------------------
2656 .
2657 These modes use the
2658 .I \%groffer
2659 file determination and decompression.
2660 .
2661 This is combined into a single input file that is fed directly into
2662 .B \%groff
2663 with different strategy without the
2664 .I \%groffer
2665 viewing facilities.
2666 .
2667 These modes are regarded as advanced, they are useful for debugging
2668 and development purposes.
2669 .
2670 .
2671 .P
2672 The
2673 .I \%source\~mode
2674 with option
2675 .Opt_short Q
2676 and
2677 .Opt_long source
2678 just displays the decompressed input.
2679 .
2680 .
2681 .P
2682 The
2683 .I \%groff\~mode
2684 passes the input to
2685 .B \%groff
2686 using only some suitable options provided to
2687 .BR \%groffer .
2688 .
2689 This enables the user to save the generated output into a file or pipe
2690 it into another program.
2691 .
2692 .
2693 .P
2694 In
2695 .IR \%groff\~\%mode ,
2696 the option
2697 .Opt_short Z
2698 disables post-processing, thus producing the
2699 .nh
2700 .I groff intermediate
2701 .IR output .
2702 .hy
2703 .
2704 In this mode, the input is formatted, but not postprocessed; see
2705 .BR \%groff_out (@MAN5EXT@)
2706 for details.
2707 .
2708 .
2709 .P
2710 All
2711 .B \%groff
2712 short options are supported by
2713 .BR \%groffer .
2714 .
2715 .
2716 .\" --------------------------------------------------------------------
2717 .SH "MAN\~PAGE\~SEARCHING"
2718 .\" --------------------------------------------------------------------
2719 .
2720 The default behavior of
2721 .B \%groffer
2722 is to first test whether a file parameter represents a local file; if
2723 it is not an existing file name, it is assumed to represent a name of
2724 a
2725 .IR \%man\~page .
2726 .
2727 This behavior can be modified by the following options.
2728 .
2729 .
2730 .TP
2731 .Opt_long man
2732 forces to interpret all file parameters as
2733 .I \%filespecs
2734 for searching
2735 .IR \%man\~pages .
2736 .
2737 .TP
2738 .Opt_long no\-man
2739 .TP+
2740 .Opt_long local\-file
2741 disable the
2742 .I man
2743 searching; so only local files are displayed.
2744 .
2745 .
2746 .P
2747 If neither a local file nor a
2748 .I \%man\~page
2749 was retrieved for some file parameter a warning is issued on standard
2750 error, but processing is continued.
2751 .
2752 .
2753 .P
2754 The
2755 .B \%groffer
2756 program provides a search facility for
2757 .IR \%man\~pages .
2758 .
2759 All long options, all environment variables, and most of the
2760 functionality of the \f[CR]GNU\f[]
2761 .BR \%man (1)
2762 program were implemented.
2763 .
2764 This inludes the extended file names of
2765 .IR \%man\~pages ,
2766 for example, the
2767 .I \%man\~page
2768 of
2769 .B \%groff
2770 in man\~section 7 may be stored under
2771 .File_name /usr/share/man/man7/groff.7.gz ,
2772 where
2773 .File_name /usr/share/man/
2774 is part of the man\~path, the subdirectory
2775 .I \%man7
2776 and the file extension
2777 .I .7
2778 refer to the man\~section 7;
2779 .I \%.gz
2780 shows the compression of the file.
2781 .
2782 .
2783 .P
2784 The
2785 .I cat\~pages
2786 (preformatted
2787 .IR \%man\~pages )
2788 are intentionally excluded from the search because
2789 .B \%groffer
2790 is a
2791 .I roff
2792 program that wants to format by its own.
2793 .
2794 With the excellent performance of the actual computers, the
2795 preformatted
2796 .I \%man\~pages
2797 aren't necessary any longer.
2798 .
2799 .
2800 .P
2801 The algorithm for retrieving
2802 \I \%man\~pages
2803 uses five search methods.
2804 .
2805 They are successively tried until a method works.
2806 .
2807 .
2808 .Topic
2809 The search path can be manually specified by using the option
2810 .Opt_long manpath .
2811 An empty argument disables the
2812 .I \%man\~page
2813 searching.
2814 .
2815 This overwrites the other methods.
2816 .
2817 .
2818 .Topic
2819 If this is not available the environment variable
2820 .Env_var $MANPATH
2821 is searched.
2822 .
2823 .
2824 .Topic
2825 If this is empty, the program tries to read it from the environment
2826 variable
2827 .Env_var $MANOPT .
2828 .
2829 .
2830 .Topic
2831 If this does not work a reasonable default path from
2832 .Env_var $PATH
2833 is searched for
2834 .IR \%man\~pages .
2835 .
2836 .
2837 .Topic
2838 If this does not work, the
2839 .BR \%manpath (1)
2840 program for determining a path of
2841 .I man
2842 directories is tried.
2843 .
2844 .
2845 .P
2846 After this, the path elements for the language (locale) and operating
2847 system specific
2848 .I \%man\~pages
2849 are added to the
2850 .IR man\~path ;
2851 their sequence is determined automatically.
2852 .
2853 For example, both
2854 .File_name /usr/share/man/linux/fr
2855 and
2856 .File_name /usr/share/man/fr/linux
2857 for french linux
2858 .I \%man\~pages
2859 are found.
2860 .
2861 The language and operating system names are determined from both
2862 environment variables and command line options.
2863 .
2864 .
2865 .P
2866 The locale (language) is determined like in \f[CR]GNU\f[]
2867 .BR man ,
2868 that is from highest to lowest precedence:
2869 .Topic
2870 .Opt_long locale
2871 .
2872 .Topic
2873 .Env_var $GROFFER_OPT
2874 .
2875 .Topic
2876 .Env_var $MANOPT
2877 .
2878 .Topic
2879 .Env_var $LCALL
2880 .
2881 .Topic
2882 .Env_var $LC_MESSAGES
2883 .
2884 .Topic
2885 .Env_var $LANG .
2886 .
2887 .
2888 .P
2889 The language locale is usually specified in the
2890 \%\f[CR]POSIX\~1003.1\f[] based format:
2891 .P
2892 .nh
2893 \f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\
2894 \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],
2895 .hy
2896 .P
2897 but the two-letter code in
2898 .nh
2899 .I <language>
2900 .hy
2901 is sufficient for most purposes.
2902 .
2903 .
2904 .P
2905 If no
2906 .I \%man\~pages
2907 for a complicated locale are found the country part consisting of the
2908 first two characters (without the `\f[CB]_\f[]', `\f[CB].\f[]', and
2909 `\f[CB],\f[]' parts) of the locale is searched as well.
2910 .
2911 .
2912 .P
2913 If still not found the corresponding
2914 .I \%man\~page
2915 in the default language is used instead.
2916 .
2917 As usual, this default can be specified by one of \f[CR]C\f[] or
2918 \f[CR]\%POSIX\f[].
2919 .
2920 The
2921 .I \%man\~pages
2922 in the default language are usually in English.
2923 .
2924 .
2925 .P
2926 Several operating systems can be given by appending their names,
2927 separated by a comma.
2928 .
2929 This is then specified by the environment variable
2930 .Env_var $SYSTEM
2931 or by the command line option
2932 .Opt_long systems .
2933 The precedence is similar to the locale case above from highest to
2934 lowest precedence:
2935 .
2936 Topic
2937 .Opt_long systems
2938 .
2939 .Topic
2940 .Env_var $GROFFER_OPT
2941 .
2942 .Topic
2943 .Env_var $MANOPT
2944 .
2945 .Topic
2946 .Env_var $SYSTEM .
2947 .
2948 .
2949 .P
2950 When searching for
2951 .I \%man\~pages
2952 this
2953 .I man\~path
2954 with the additional language and system specific directories is used.
2955 .
2956 .
2957 .P
2958 The search can further be restricted by limiting it to certain
2959 sections.
2960 .
2961 A single section can be specified within each
2962 .I \%filespec
2963 argument, several sections as a colon-separated list in command line
2964 option
2965 .Opt_long sections
2966 or environment variable
2967 .Env_var $MANSECT .
2968 .
2969 When no section was specified a set of standard sections is searched
2970 until a suitable
2971 .I \%man\~page
2972 was found.
2973 .
2974 .
2975 .P
2976 Finally, the search can be restricted to a so-called
2977 .IR extension .
2978 This is a postfix that acts like a subsection.
2979 .
2980 It can be specified by
2981 .Opt_long extension
2982 or environment variable
2983 .Env_var $EXTENSION .
2984 .
2985 .
2986 .P
2987 For further details on
2988 .I \%man\~page
2989 searching, see
2990 .BR \%man (1).
2991 .
2992 .
2993 .\" --------------------------------------------------------------------
2994 .SH DECOMPRESSION
2995 .\" --------------------------------------------------------------------
2996 .
2997 The program has a decompression facility.
2998 .
2999 If standard input or a file that was retrieved from the command line
3000 parameters is compressed with a format that is supported by either
3001 .BR \%gzip (1)
3002 or
3003 .BR \%bzip2 (1)
3004 it is decompressed on-the-fly.
3005 .
3006 This includes the \f[CR]GNU\f[]
3007 .BR \%.gz ,
3008 .BR \%.bz2 ,
3009 and the traditional
3010 .B \%.Z
3011 compression.
3012 .
3013 The program displays the concatenation of all decompressed input in
3014 the sequence that was specified on the command line.
3015 .
3016 .
3017 .\" --------------------------------------------------------------------
3018 .SH "ENVIRONMENT"
3019 .\" --------------------------------------------------------------------
3020 .
3021 The
3022 .B \%groffer
3023 program supports many system variables, most of them by courtesy of
3024 other programs.
3025 .
3026 All environment variables of
3027 .BR \%groff (@MAN1EXT@)
3028 and \f[CR]GNU\f[]
3029 .BR \%man (1)
3030 and some standard system variables are honored.
3031 .
3032 .
3033 .\" --------------------------------------------------------------------
3034 .SS "Native groffer Variables"
3035 .\" --------------------------------------------------------------------
3036 .
3037 .TP
3038 .Env_var $GROFFER_OPT
3039 Store options for a run of
3040 .BR \%groffer .
3041 .
3042 The options specified in this variable are overridden by the options
3043 given on the command line.
3044 .
3045 The content of this variable is run through the shell builtin `eval';
3046 so arguments containing white-space or special shell characters should
3047 be quoted.
3048 .
3049 Do not forget to export this variable, otherwise it does not exist
3050 during the run of
3051 .BR groffer .
3052 .
3053 .
3054 .\" --------------------------------------------------------------------
3055 .SS "System Variables"
3056 .\" --------------------------------------------------------------------
3057 .
3058 The
3059 .B \%groffer
3060 program is a shell script that is run through
3061 .File_name /bin/sh ,
3062 which can be internally linked to programs like
3063 .BR \%bash (1).
3064 The corresponding system environment is automatically effective.
3065 .
3066 The following variables have a special meaning for
3067 .BR \%groffer .
3068 .
3069 .
3070 .TP
3071 .Env_var $DISPLAY
3072 If this variable is set this indicates that the \%\f[CR]X\~Window\f[]
3073 system is running.
3074 .
3075 Testing this variable decides on whether graphical or text output is
3076 generated.
3077 .
3078 This variable should not be changed by the user carelessly, but it can
3079 be used to start the graphical
3080 .B \%groffer
3081 on a remote \%\f[CR]X\~Window\f[] terminal.
3082 .
3083 For example, depending on your system,
3084 .B \%groffer
3085 can be started on the second monitor by the command
3086 .Shell_cmd DISPLAY=:0.1\~groffer\~ what.ever &
3087 .
3088 .
3089 .TP
3090 .Env_var $LC_ALL
3091 .TP+
3092 .Env_var $LC_MESSAGES
3093 .TP+
3094 .Env_var $LANG
3095 If one of these variables is set (in the above sequence), its content
3096 is interpreted as the locale, the language to be used, especially when
3097 retrieving
3098 \IR \%man\~pages .
3099 .
3100 A locale name is typically of the form
3101 .nh
3102 .IR language [\c
3103 .B _\c
3104 .IR territory [\c
3105 .B .\c
3106 .IR codeset [\c
3107 .B @\c
3108 .IR modifier ]]],
3109 .hy
3110 where
3111 .I \%language
3112 is an ISO 639 language code,
3113 .I \%territory
3114 is an ISO 3166 country code, and
3115 .I \%codeset
3116 is a character set or encoding identifier like ISO-8859-1 or UTF-8;
3117 see
3118 .BR \%setlocale (3).
3119 .
3120 The locale values \f[CR]C\f[] and \%\f[CR]POSIX\f[]
3121 stand for the default, i.e. the
3122 .I \%man\~page
3123 directories without a language prefix.
3124 .
3125 This is the same behavior as when all 3\~variables are unset.
3126 .
3127 .
3128 .TP
3129 .Env_var $PAGER
3130 This variable can be used to set the pager for the tty output.
3131 .
3132 For example, to disable the use of a pager completely set this
3133 variable to the
3134 .BR \%cat (1)
3135 program
3136 .Shell_cmd PAGER=cat\~groffer\~ anything
3137 .
3138 .
3139 .TP
3140 .Env_var $PATH
3141 All programs within the
3142 .B \%groffer
3143 shell script are called without a fixed path.
3144 .
3145 Thus this environment variable determines the set of programs used
3146 within the run of
3147 .BR \%groffer .
3148 .
3149 .
3150 .\" --------------------------------------------------------------------
3151 .SS "Groff Variables"
3152 .\" --------------------------------------------------------------------
3153 .
3154 The
3155 .B \%groffer
3156 program internally calls
3157 .BR \%groff ,
3158 so all environment variables documented in
3159 .BR \%groff (@MAN1EXT@)
3160 are internally used within
3161 .B \%groffer
3162 as well.
3163 .
3164 The following variable has a direct meaning for the
3165 .B \%groffer
3166 program.
3167 .
3168 .TP
3169 .Env_var $GROFF_TMPDIR
3170 If the value of this variable is an existing, writable directory,
3171 .B \%groffer
3172 uses it for storing its temporary files, just as
3173 .B groff
3174 does.
3175 .
3176 .
3177 .\" --------------------------------------------------------------------
3178 .SS "Man Variables"
3179 .\" --------------------------------------------------------------------
3180 .
3181 Parts of the functionality of the
3182 .B man
3183 program were implemented in
3184 .BR \%groffer ;
3185 support for all environment variables documented in
3186 .BR \%man (1)
3187 was added to
3188 .BR \%groffer ,
3189 but the meaning was slightly modified due to the different approach in
3190 .BR \%groffer ;
3191 but the user interface is the same.
3192 .
3193 The
3194 .B man
3195 environment variables can be overwritten by options provided with
3196 .Env_var $MANOPT ,
3197 which in turn is overwritten by the command line.
3198 .
3199 .
3200 .TP
3201 .Env_var $EXTENSION
3202 Restrict the search for
3203 .I \%man\~pages
3204 to files having this extension.
3205 .
3206 This is overridden by option
3207 .Opt_long extension ;
3208 see there for details.
3209 .
3210 .
3211 .TP
3212 .Env_var $MANOPT
3213 This variable contains options as a preset for
3214 .BR \%man (1).
3215 As not all of these are relevant for
3216 .B \%groffer
3217 only the essential parts of its value are extracted.
3218 .
3219 The options specified in this variable overwrite the values of the
3220 other environment variables that are specific to
3221 .IR man .
3222 .
3223 All options specified in this variable are overridden by the options
3224 given on the command line.
3225 .
3226 .
3227 .TP
3228 .Env_var $MANPATH
3229 If set, this variable contains the directories in which the
3230 .I \%man\~page
3231 trees are stored.
3232 .
3233 This is overridden by option
3234 .Opt_long manpath .
3235 .
3236 .
3237 .TP
3238 .Env_var $MANSECT
3239 If this is a colon separated list of section names, the search for
3240 .I \%man\~pages
3241 is restricted to those manual sections in that order.
3242 .
3243 This is overridden by option
3244 .Opt_long sections .
3245 .
3246 .
3247 .TP
3248 .Env_var $SYSTEM
3249 If this is set to a comma separated list of names these are interpreted
3250 as
3251 .I \%man\~page
3252 trees for different operating systems.
3253 .
3254 This variable can be overwritten by option
3255 .Opt_long systems ;
3256 see there for details.
3257 .
3258 .
3259 .P
3260 The environment variable
3261 .Env_var $MANROFFSEQ
3262 is ignored by
3263 .B \%groffer
3264 because the necessary preprocessors are determined automatically.
3265 .
3266 .
3267 .\" --------------------------------------------------------------------
3268 .SH "CONFIGURATION FILES"
3269 .\" --------------------------------------------------------------------
3270 .
3271 The
3272 .B \%groffer
3273 program can be preconfigured by two configuration files.
3274 .
3275 .
3276 .TP
3277 .File_name /etc/groff/groffer.conf
3278 System-wide configuration file for
3279 .BR \%groffer .
3280 .
3281 .
3282 .TP
3283 .File_name $HOME/.groff/groffer.conf
3284 User-specific configuration file for
3285 .BR \%groffer ,
3286 where
3287 .Env_var $HOME
3288 denotes the user's home directory.
3289 .
3290 This file is called after the system-wide configuration file to enable
3291 overriding by the user.
3292 .
3293 .
3294 .P
3295 The precedence of option delivery is given in the following.
3296 .
3297 The configuration file in
3298 .File_name /etc
3299 has the lowest precedence; it is overwritten by the configuration file
3300 in the home directory; both configuration files are overwritten by the
3301 environment variable
3302 .Env_var $GROFFER_OPT ;
3303 everything is overwritten by the command line.
3304 .
3305 .
3306 .P
3307 In the configuration files, arbitrary spaces are allowed at the
3308 beginning of each line, they are just ignored.
3309 .
3310 Apart from that, the lines of the configuration lines either start
3311 with a minus character, all other lines are interpreted as shell
3312 commands.
3313 .
3314 .
3315 .P
3316 The lines with the beginning minus are interpreted as
3317 .B groffer
3318 options.
3319 .
3320 This easily allows to set general
3321 .B \%groffer
3322 options that should be used with any call of
3323 .BR \%groffer .
3324 .
3325 Each line can represent a single short option, a short option cluster,
3326 or a long option with two minus signs, eventually with an argument.
3327 .
3328 The argument can be appended either after a space character or an
3329 equal sign
3330 .RB ` = '.
3331 The argument can be surrounded by quotes, but this is not necessary.
3332 .
3333 The options from these lines are collected and prepended to the
3334 existing value of
3335 .Env_var $GROFFER_OPT
3336 at the end of each configuration file.
3337 .
3338 .
3339 .P
3340 After the transformation of the minus lines, the configuration files
3341 have been transferred into a shell script that is called within
3342 .B \%groffer
3343 using the `\c
3344 .CB \.\~\c
3345 .IR \%filename '
3346 shell syntax.
3347 .
3348 .
3349 .P
3350 It makes sense to use these configuration files for the following
3351 tasks:
3352 .
3353 .Topic
3354 Preset command line options, such as choosing a
3355 .I \%mode
3356 or a viewer.
3357 .
3358 These are written into lines starting with a single or double minus
3359 sign, followed by the option name.
3360 .
3361 .Topic
3362 Preset environment variables recognized by
3363 .BR \%groffer ;
3364 but do not forget to export them.
3365 .
3366 .Topic
3367 You can also write a shell function for calling, for example a viewer
3368 program for some
3369 .IR \%mode .
3370 Such a function can be fed into a corresponding
3371 .Opt_long \f[I]mode\f[]\-viewer
3372 option.
3373 .
3374 .Topic
3375 Enter
3376 .Opt_long shell
3377 to specify a shell for the run of
3378 .File_name groffer2.sh .
3379 Some shells run much faster than the standard shell.
3380 .
3381 .
3382 .P
3383 As an example, consider the following configuration file in
3384 .File_name ~/.groff/groffer.conf ,
3385 say.
3386 .
3387 .P
3388 .ft CR
3389 .nh
3390 .nf
3391 # groffer configuration file
3392 #
3393 # groffer options that are used in each call of groffer
3394 \-\-shell=ksh
3395 \-\-foreground=DarkBlue
3396 \-\-resolution=100
3397 \-\-x\-viewer='gxditview \-geometry 900x1200'
3398 #
3399 # some shell commands
3400 if test "$DISPLAY" = ""; then
3401   export DISPLAY='localhost:0.0'
3402 fi
3403 date >>~/mygroffer.log
3404 .fi
3405 .hy
3406 .ft
3407 .
3408 .
3409 .P
3410 The lines starting with
3411 .B #
3412 are command lines.
3413 .
3414 This configuration sets four
3415 .B \%groffer
3416 options (the lines starting with `\-') and runs two shell commands (the
3417 rest of the script).
3418 .
3419 This has the following effects:
3420 .
3421 .
3422 .Topic
3423 Use
3424 .B ksh
3425 as the shell to run the
3426 .B \%groffer
3427 script; if it works it should be faster than the usual
3428 .BR sh .
3429 .
3430 .
3431 .Topic
3432 Use a text color of
3433 .B \%DarkBlue
3434 in all viewers that support this, such as
3435 .BR \%gxditview .
3436 .
3437 .
3438 .Topic
3439 Use a resolution of
3440 .B 100\~dpi
3441 in all viewers that support this, such as
3442 .BR \%gxditview .
3443 .
3444 By this, the default device in
3445 .I x mode
3446 is set to
3447 .BR X100 .
3448 .
3449 .
3450 .Topic
3451 Force
3452 .BR \%gxditview (@MAN1EXT@)
3453 as the
3454 .I \%x-mode
3455 viewer using the geometry option for setting the width to
3456 .B 900\~dpi
3457 and the height to
3458 .BR 1200\~dpi .
3459 This geometry is suitable for a resolution of
3460 .BR 100\~dpi .
3461 .
3462 .
3463 .Topic
3464 If the environment variable
3465 .Env_var $DISPLAY
3466 is empty set it to
3467 .IR localhost:0.0 .
3468 .
3469 That allows to start
3470 .B \%groffer
3471 in the standard \%\f[CR]X\~Window\f[] display, even when the program
3472 is called from a text console.
3473 .
3474 .
3475 .Topic
3476 Just for fun, the date of each
3477 .B \%groffer
3478 start is written to the file
3479 .File_name mygroffer.log
3480 in the home directory.
3481 .
3482 .
3483 .\" --------------------------------------------------------------------
3484 .SH "EXAMPLES"
3485 .\" --------------------------------------------------------------------
3486 .
3487 The usage of
3488 .B \%groffer
3489 is very easy.
3490 .
3491 Usually, it is just called with a file name or
3492 .IR \%man\~page .
3493 .
3494 The following examples, however, show that
3495 .B \%groffer
3496 has much more fancy capabilities.
3497 .
3498 .
3499 .TP
3500 .Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz"
3501 Decompress, format and display the compressed file
3502 .File_name meintro.ms.gz
3503 in the directory
3504 .File_name /usr/local/share/doc/groff ,
3505 using the standard viewer
3506 .B \%gxditview
3507 as graphical viewer when in \%\f[CR]X\~Window\f[], or the
3508 .BR \%less (1)
3509 pager program when not in \%\f[CR]X\~Window\f[].
3510 .
3511 .
3512 .TP
3513 .Shell_cmd "groffer\~groff"
3514 If the file
3515 .File_name \%./groff
3516 exists use it as input.
3517 .
3518 Otherwise interpret the argument as a search for the
3519 .I \%man\~page
3520 named
3521 .B \%groff
3522 in the smallest possible
3523 .IR \%man\~section ,
3524 being section 1 in this case.
3525 .
3526 .
3527 .TP
3528 .Shell_cmd "groffer\~man:groff"
3529 search for the
3530 .I \%man\~page
3531 of
3532 .B \%groff
3533 even when the file
3534 .File_name ./groff
3535 exists.
3536 .
3537 .
3538 .TP
3539 .Shell_cmd "groffer\~groff.7"
3540 .TP+
3541 .Shell_cmd "groffer\~7\~groff"
3542 search the
3543 .I \%man\~page
3544 of
3545 .B \%groff
3546 in
3547 .I \%man\~section
3548 .BR 7 .
3549 This section search works only for a digit or a single character from
3550 a small set.
3551 .
3552 .
3553 .TP
3554 .Shell_cmd "groffer\~fb.modes"
3555 If the file
3556 .File_name ./fb.modes
3557 does not exist interpret this as a search for the
3558 .I \%man\~page
3559 of
3560 .BR fb.modes .
3561 As the extension
3562 .I \%modes
3563 is not a single character in classical section style the argument is
3564 not split to a search for
3565 .BR fb .
3566 .
3567 .
3568 .TP
3569 .Shell_cmd "groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff"
3570 .
3571 The arguments that are not existing files are looked-up as the
3572 following
3573 .IR \%man\~pages :
3574 .B \%groff
3575 (automatic search, should be found in \fIman\fP\~section\~1),
3576 .B \%troff
3577 (in section\~1),
3578 and
3579 .B \%roff
3580 (in the section with the lowest number, being\~7 in this case).
3581 .
3582 The quotes around
3583 .nh
3584 .I \[cq]troff(1)\[cq]
3585 .hy
3586 are necessary because the paranthesis are special shell characters;
3587 escaping them with a backslash character
3588 .I \[rs](
3589 and
3590 .I \[rs])
3591 would be possible, too.
3592 .
3593 The formatted files are concatenated and displayed in one piece.
3594 .
3595 .
3596 .TP
3597 .Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=galeon\~ls"
3598 .
3599 Retrieve the German
3600 .I \%man\~page
3601 (language
3602 .IR de )
3603 for the
3604 .B ls
3605 program, decompress it, format it to
3606 .I \%html
3607 format
3608 .nh
3609 .RI ( \%www\~mode )
3610 .hy
3611 and view the result in the web browser
3612 .BR \%galeon .
3613 The option
3614 .Opt_long man
3615 guarantees that the
3616 .I \%man\~page
3617 is retrieved, even when a local file
3618 .File_name \%ls
3619 exists in the actual directory.
3620 .
3621 .
3622 .TP
3623 .Shell_cmd "groffer\~--source\~'man:roff(7)'"
3624 .
3625 Get the
3626 .I \%man\~page
3627 called
3628 .I \%roff
3629 in \fIman\fP\~section 7, decompress it, and print its unformatted
3630 content, its source code.
3631 .
3632 .
3633 .TP
3634 .Shell_cmd "cat\~file.gz\~|\~groffer\~-Z\~-mfoo"
3635 .
3636 Decompress the standard input, send this to
3637 .I \%groff intermediate output mode
3638 without post-processing
3639 .RB ( groff
3640 option
3641 .Opt_short Z ),
3642 using macro package by
3643 .I \%foo
3644 .RB ( groff
3645 option
3646 .Opt_short m ) .
3647 .
3648 .
3649 .TP
3650 .Shell_cmd "echo\~'\[rs]f[CB]WOW!'\~|"
3651 .TP+
3652 .Shell_cmd+ "groffer --x --bg red --fg yellow --geometry 200x100 -"
3653 .
3654 Display the word \f[CB]WOW!\f[] in a small window in constant-width
3655 bold font, using color yellow on red background.
3656 .
3657 .
3658 .\" --------------------------------------------------------------------
3659 .SH "COMPATIBILITY"
3660 .\" --------------------------------------------------------------------
3661 .
3662 The
3663 .B \%groffer
3664 program consists of two shell scripts.
3665 .
3666 .
3667 .P
3668 The starting script is the file
3669 .File_name \%groffer
3670 that is installed in a
3671 .File_name bin
3672 directory.
3673 .
3674 It is generated from the source file
3675 .File_name \%groffer.sh .
3676 .
3677 It is just a short starting script without any functions such that it
3678 can run on very poor shells.
3679 .
3680 .
3681 .P
3682 The main part of the
3683 .B \%groffer
3684 program is the file
3685 .File_name groffer2.sh
3686 that is installed in the
3687 .I groff
3688 library directory.
3689 .
3690 This script can be run under a different shell by using the
3691 .B \%groffer
3692 option
3693 .Opt_long shell .
3694 .
3695 .
3696 .P
3697 Both scripts are compatible with both
3698 \f[CR]GNU\f[] and \%\f[CR]POSIX\f[].
3699 .
3700 \%\f[CR]POSIX\f[] compatibility refers to
3701 \%\f[CR]IEEE\~P1003.2/D11.2\f[] of September 1991, a very early
3702 version of the \%\f[CR]POSIX\f[] standard that is still freely
3703 available in the internet at
3704 .URL http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all \
3705 "\%POSIX\~P1003.2\~draft\~11.2" .
3706 .
3707 .
3708 .P
3709 Only a restricted set of shell language elements and shell builtins is
3710 used to achieve even compatibility with some Bourne shells that are
3711 not fully \%\f[CR]POSIX\f[] compatible.
3712 .
3713 The
3714 .B \%groffer
3715 shell scripts were tested on many shells, including the following
3716 Bourne shells:
3717 .BR \%ash (1),
3718 .BR \%bash (1),
3719 .BR \%dash (1),
3720 .BR \%ksh (1),
3721 .BR \%pdksh (1),
3722 .BR \%posh (1),
3723 and
3724 .BR \%zsh (1).
3725 So it should work on most actual free and commercial operating
3726 systems.
3727 .
3728 .
3729 .P
3730 The shell for the run of
3731 .File_name groffer2.sh
3732 can be chosen by the option
3733 .Opt_long shell
3734 on the command line or the environment variable
3735 .Env_var $GROFF_OPT .
3736 If you want to add it to one of the
3737 .B \%groffer
3738 configuration files you must write a line starting with
3739 .Opt_long shell .
3740 .
3741 .
3742 .P
3743 The
3744 .B \%groffer
3745 program provides its own parser for command line arguments that is
3746 compatible to both \%\f[CR]POSIX\f[]
3747 .BR \%getopts (1)
3748 and \%\f[CR]GNU\f[]
3749 .BR \%getopt (1).
3750 It can handle option arguments and file names containing white space
3751 and a large set of special characters.
3752 .
3753 The following standard types of options are supported.
3754 .
3755 .
3756 .Topic
3757 The option consisiting of a single minus
3758 .Opt_short
3759 refers to standard input.
3760 .
3761 .
3762 .Topic
3763 A single minus followed by characters refers to a single character
3764 option or a combination thereof; for example, the
3765 .B \%groffer
3766 short option combination
3767 .Opt_short Qmfoo
3768 is equivalent to
3769 .Opt_short Q\~\-m\~foo .
3770 .
3771 .
3772 .Topic
3773 Long options are options with names longer than one character; they
3774 are always preceded by a double minus.
3775 .
3776 An option argument can either go to the next command line argument or
3777 be appended with an equal sign to the argument; for example,
3778 .Opt_alt -- long=arg
3779 is equivalent to
3780 .Opt_alt -- long\~arg .
3781 .
3782 .
3783 .Topic
3784 An argument of
3785 .Opt_--
3786 ends option parsing; all further command line arguments are
3787 interpreted as
3788 .I \%filespec
3789 parameters, i.e. file names or constructs for searching
3790 .IR \%man\~pages ).
3791 .
3792 .
3793 .Topic
3794 All command line arguments that are neither options nor option
3795 arguments are interpreted as
3796 .I \%filespec
3797 parameters and stored until option parsing has finished.
3798 .
3799 For example, the command line
3800 .Shell_cmd "groffer file1 -a -o arg file2"
3801 is equivalent to
3802 .Shell_cmd "groffer -a -o arg -- file1 file2"
3803 .
3804 .
3805 .P
3806 The free mixing of options and
3807 .I \%filespec
3808 parameters follows the GNU principle.
3809 .
3810 That does not fulfill the strange option behavior of \%\f[CR]POSIX\f[]
3811 that ends option processing as soon as the first non-option argument
3812 has been reached.
3813 .
3814 The end of option processing can be forced by the option
3815 .RB ` \-\- '
3816 anyway.
3817 .
3818 .
3819 .\" --------------------------------------------------------------------
3820 .SH "BUGS"
3821 .\" --------------------------------------------------------------------
3822 .
3823 Report bugs to the
3824 .MTO bug-groff@gnu.org "bug-groff mailing list" .
3825 .
3826 Include a complete, self-contained example that will allow the bug to
3827 be reproduced, and say which version of
3828 .B \%groffer
3829 you are using.
3830 .
3831 .
3832 .P
3833 You can also use the
3834 .MTO groff@gnu.org "groff mailing list" ,
3835 but you must first subscribe to this list.
3836 .
3837 You can do that by visiting the
3838 .URL http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff \
3839 "groff mailing list web page" .
3840 .
3841 .
3842 .P
3843 See
3844 .BR \%groff (@MAN1EXT@)
3845 for information on availability.
3846 .
3847 .
3848 .\" --------------------------------------------------------------------
3849 .SH "SEE ALSO"
3850 .\" --------------------------------------------------------------------
3851 .
3852 .P
3853 .BR \%groff (@MAN1EXT@),
3854 .BR \%@g@troff (@MAN1EXT@)
3855 .RS
3856 Details on the options and environment variables available in
3857 .BR \%groff ;
3858 all of them can be used with
3859 .BR \%groffer .
3860 .RE
3861 .
3862 .
3863 .TP
3864 .BR \%groff (@MAN7EXT@)
3865 Documentation of the
3866 .I \%groff
3867 language.
3868 .
3869 .
3870 .TP
3871 .BR \%grog (@MAN1EXT@)
3872 Internally,
3873 .B \%groffer
3874 tries to guess the
3875 .B \%groff
3876 command line options from the input using this program.
3877 .
3878 .
3879 .TP
3880 .BR groff_out (@MAN5EXT@)
3881 Documentation on the
3882 .I \%groff intermediate output
3883 .nh
3884 .RI ( ditroff
3885 output).
3886 .hy
3887 .
3888 .
3889 .TP
3890 .BR groff_tmac (@MAN5EXT@)
3891 Documentation on the
3892 .I \%groff
3893 macro files.
3894 .
3895 .
3896 .TP
3897 .BR \%man (1)
3898 The standard program to display
3899 .IR \%man\~pages .
3900 .
3901 The information there is only useful if it is the
3902 .I \%man\~page
3903 for GNU
3904 .BR man .
3905 Then it documents the options and environment variables that are
3906 supported by
3907 .BR \%groffer .
3908 .
3909 .
3910 .P
3911 .BR \%ash (1),
3912 .BR \%bash (1),
3913 .BR \%dash (1),
3914 .BR \%ksh (1),
3915 .BR \%pdksh (1),
3916 .BR \%posh (1),
3917 .BR \%sh (1),
3918 .BR \%zsh (1)
3919 .RS
3920 Bourne shells that were tested with
3921 .BR \%groffer .
3922 .RE
3923 .
3924 .
3925 .P
3926 .BR \%gxditview (@MAN1EXT@),
3927 .BR \%xditview (1x)
3928 .RS
3929 Viewers for
3930 .BR \%groffer 's
3931 .IR \%x\~mode .
3932 .RE
3933 .
3934 .
3935 .P
3936 .BR \%kghostview (1),
3937 .BR \%ggv (1),
3938 .BR \%gv (1),
3939 .BR \%ghostview (1),
3940 .BR \%gs (1)
3941 .RS
3942 Viewers for
3943 .BR \%groffer 's
3944 .IR \%ps\~mode .
3945 .RE
3946 .
3947 .
3948 .P
3949 .BR \%kghostview (1),
3950 .BR \%ggv (1),
3951 .BR \%xpdf (1),
3952 .BR \%acroread (1),
3953 .BR \%kpdf (1)
3954 .RS
3955 Viewers for
3956 .BR \%groffer 's
3957 .IR \%pdf\~mode .
3958 .RE
3959 .
3960 .
3961 .P
3962 .BR \%kdvi (1),
3963 .BR \%xdvi (1),
3964 .BR \%dvilx (1)
3965 .RS
3966 Viewers for
3967 .BR \%groffer 's
3968 .IR \%dvi\~mode .
3969 .RE
3970 .
3971 .
3972 .P
3973 .BR \%konqueror (1),
3974 .BR \%mozilla (1),
3975 .BR \%lynx (1)
3976 .RS
3977 Web-browsers for
3978 .BR \%groffer 's
3979 .I \%html
3980 or
3981 .IR \%www\~mode .
3982 .RE
3983 .
3984 .
3985 .TP
3986 .BR \%less (1)
3987 Standard pager program for the
3988 .I \%tty\~mode .
3989 .
3990 .
3991 .P
3992 .BR \%gzip (1),
3993 .BR \%bzip2 (1)
3994 .RS
3995 The decompression programs supported by
3996 .BR \%groffer .
3997 .RE
3998 .
3999 .
4000 .\" --------------------------------------------------------------------
4001 .SH "AUTHOR"
4002 .\" --------------------------------------------------------------------
4003 .author
4004 .
4005 .
4006 .\" --------------------------------------------------------------------
4007 .SH "COPYING"
4008 .\" --------------------------------------------------------------------
4009 .copyleft
4010 .
4011 .
4012 .\" --------------------------------------------------------------------
4013 .\" Emacs settings
4014 .\" --------------------------------------------------------------------
4015 .
4016 .\" Local Variables:
4017 .\" mode: nroff
4018 .\" End: