1GROFFER(1)                  General Commands Manual                 GROFFER(1)
2
3
4

NAME

6       groffer - display groff files and man pages on X and tty
7

SYNOPSIS

9       groffer [mode-option ...] [groff-option ...] [man-option ...] [X-option
10               ...] [--] [filespec ...]
11
12       groffer -h
13       groffer --help
14
15       groffer -v
16       groffer --version
17

DESCRIPTION

19       The groffer program is the easiest way to use groff(1).  It can display
20       arbitrary  documents  written  in  the groff language, see groff(7), or
21       other roff languages, see roff(7), that are compatible to the  original
22       troff  language.   It finds and runs all necessary groff preprocessors,
23       such as chem.
24
25       The groffer program also includes many of the features for finding  and
26       displaying  the Unix manual pages (man pages), such that it can be used
27       as a replacement for a man(1) program.  Moreover, compressed files that
28       can be handled by gzip(1) or bzip2(1) are decompressed on-the-fly.
29
30       The  normal usage is quite simple by supplying a file name or name of a
31       man page without further options.  But the  option  handling  has  many
32       possibilities  for creating special behaviors.  This can be done either
33       in  configuration  files,   with   the   shell   environment   variable
34       GROFFER_OPT, or on the command line.
35
36       The output can be generated and viewed in several different ways avail‐
37       able for groff.  This includes the X Window System-based groff  program
38       gxditview(1),  each  PostScript,  PDF,  or  DVI  display program, a web
39       browser by generating HTML or XHTML in www mode, or several text  modes
40       in text terminals.
41
42       Most  of the options that must be named when running groff directly are
43       determined automatically for groffer, due to the internal usage of  the
44       grog(1)  program.  But all parts can also be controlled manually by ar‐
45       guments.
46
47       Several file names can be  specified  on  the  command-line  arguments.
48       They are transformed into a single document in the normal way of groff.
49
50       Option  handling  is  done in GNU style.  Options and file names can be
51       mixed freely.  The option “--” closes the option handling, all  follow‐
52       ing  arguments are treated as file names.  Long options can be abbrevi‐
53       ated in several ways.
54

OPTION OVERVIEW

56       breaking options
57
58               [-h | --help] [-v | --version]
59
60       groffer mode options
61
62               [--auto] [--default] [--default-modes mode1,mode2,...] [--dvi]
63               [--groff] [--html] [--latin1] [--mode display_mode] [--pdf]
64               [--pdf2] [--ps] [--source] [--text] [--to-stdout] [--tty]
65               [--utf8] [--viewer prog] [--www] [--xhtml] [--x | --X]
66
67       options related to groff
68
69               [-T | --device device] [-Z | --intermediate-output | --ditroff]
70
71              All further groff short options are accepted.
72
73       options for man pages
74
75               [--apropos] [--apropos-data] [--apropos-devel]
76               [--apropos-progs] [--man] [--no-man] [--no-special] [--whatis]
77
78       long options taken over from GNU man
79
80               [--all] [--ascii] [--ditroff] [--extension suffix]
81               [--locale language] [--local-file] [--location | --where]
82               [--manpath dir1:dir2:...] [--no-location] [--pager program]
83               [--sections sec1:sec2:...] [--systems sys1,sys2,...]
84               [--troff-device device]
85
86              Further long options of GNU man are accepted as well.
87
88       options mapped to X Window System Toolkit Intrinsics options
89
90               [--bd | --bordercolor pixels] [--bg | --background color]
91               [--bw | --borderwidth pixels] [--display X-display]
92               [--fg | --foreground color] [--fn | --ft | --font font_name]
93               [--geometry size_pos] [--resolution value] [--rv]
94               [--title string] [--xrm X-resource]
95
96       options for development
97
98               [--debug] [--debug-filenames] [--debug-grog] [--debug-keep]
99               [--debug-params] [--debug-tmpdir] [--do-nothing] [--print text]
100               [-V]
101
102       filespec arguments
103
104              The filespec parameters are all arguments that  are  neither  an
105              option nor an option argument.  They usually mean a file name or
106              a man page searching scheme.
107
108              In the following, the term section_extension is used.  It  means
109              a  word  that  consists of a man section that is optionally fol‐
110              lowed by an extension.  The name of a man section  is  a  single
111              character  from [1–9on], the extension is some word.  The exten‐
112              sion is mostly lacking.
113
114              No filespec parameters means standard input.
115
116              -         stands for standard input (can occur several times).
117
118              filename  the path name of an existing file.
119
120              man:name(section_extension)
121              man:name.section_extension
122              name(section_extension)
123              name.section_extension
124              section_extension name
125                        search the man page name in the section with  optional
126                        extension section_extension.
127
128              man:name  man page in the lowest man section that has name.
129
130              name      if  name  is  not  an  existing  file  search  for the
131                        man page name in the lowest man section.
132

OPTION DETAILS

134       The groffer program can usually be run with very few options.  But  for
135       special purposes, it supports many options.  These can be classified in
136       5 option classes.
137
138       All short options of groffer are compatible with the short  options  of
139       groff(1).   All  long  options  of groffer are compatible with the long
140       options of man(1).
141
142       Arguments for long option names can be  abbreviated  in  several  ways.
143       First, the argument is checked whether it can be prolonged as is.  Fur‐
144       thermore, each minus sign - is considered as a starting point for a new
145       abbreviation.  This leads to a set of multiple abbreviations for a sin‐
146       gle argument.  For example, --de-n-f can be used as an abbreviation for
147       --debug-not-func, but --de-n works as well.  If the abbreviation of the
148       argument leads to several resulting options an error is raised.
149
150       These abbreviations  are  only  allowed  in  the  environment  variable
151       GROFFER_OPT, but not in the configuration files.  In configuration, all
152       long options must be exact.
153
154   groffer breaking Options
155       As soon as one of these options is found on the command line it is exe‐
156       cuted,  printed  to  standard output, and the running groffer is termi‐
157       nated thereafter.  All other arguments are ignored.
158
159       -h | --help
160              Print help information with a short explanation  of  options  to
161              standard output.
162
163       -v | --version
164              Print version information to standard output.
165
166   groffer Mode Options
167       The  display  mode  and  the  viewer  programs  are determined by these
168       options.  If none of these mode and viewer options is specified groffer
169       tries to find a suitable display mode automatically.  The default modes
170       are mode pdf, mode ps, mode html, mode xhtml, mode x, and mode  dvi  in
171       the  X  Window  System  with different viewers and mode tty with device
172       utf8 under less on a terminal; other modes are tested if  the  programs
173       for the main default mode do not exist.
174
175       In  the  X  Window  System,  many programs create their own window when
176       called.  groffer can run these viewers as an independent program in the
177       background.   As  this  does  not work in text mode on a terminal (tty)
178       there must be a way to know which viewers  are  X  Window  System-based
179       graphical  programs.  The groffer script has a small amount of informa‐
180       tion on some viewer names.  If a viewer argument  of  the  command-line
181       chooses  an element that is recognized as an X Window System-based pro‐
182       gram in this list, it is treated as a viewer that can run in the  back‐
183       ground.  Unrecognized viewers are not run in the background.
184
185       For  each  mode, you are free to choose whatever viewer you want.  That
186       need not be some graphical viewer suitable for this mode.  There  is  a
187       chance  to  view the output source; for example, the combination of the
188       options --mode=ps and --viewer=less shows the content of the PostScript
189       output, the source code, with the pager less.
190
191       --auto Equivalent to --mode=auto.
192
193       --default
194              Reset  all  configuration from previously processed command-line
195              options to the default values.  This is useful to wipe  out  all
196              former options of the configuration, in GROFFER_OPT, and restart
197              option processing using only the rest of the command line.
198
199       --default-modes mode1,mode2,...
200              Set the sequence of modes for auto mode to the  comma  separated
201              list  given  in  the argument.  See --mode for details on modes.
202              Display in the default manner; actually, this means to  try  the
203              modes x, ps, and tty in this sequence.
204
205       --dvi  Equivalent  to  --mode=dvi.   Known DVI viewers for the X Window
206              System include xdvi(1) and dvilx(1).
207
208       --groff
209              Equivalent to --mode=groff.
210
211       --html Equivalent to --mode=html.
212
213       --mode value
214              Set the display mode.  The following mode values are recognized:
215
216              auto   Select the automatic determination of the  display  mode.
217                     The  sequence of modes that are tried can be set with the
218                     --default-modes  option.   Useful   for   restoring   the
219                     default mode when a different mode was specified before.
220
221              dvi    Display  formatted  input  in  a  DVI viewer program.  By
222                     default,  the  formatted  input  is  displayed  with  the
223                     xdvi(1) program.
224
225              groff  After  the  file determination, switch groffer to process
226                     the input like groff(1)  would  do.   This  disables  the
227                     groffer viewing features.
228
229              html   Translate  the  input  into  HTML  format and display the
230                     result in a web browser program.  By default,  the  exis‐
231                     tence  of  a sequence of standard web browsers is tested,
232                     starting with konqueror(1) and mozilla(1).  The text HTML
233                     viewer  is  lynx(1).   By  default,  the  existence  of a
234                     sequence of standard web  browsers  is  tested,  starting
235                     with  konqueror(1)  and mozilla(1).  The text HTML viewer
236                     is lynx(1).
237
238              pdf    Transform roff input files into a PDF file by  using  the
239                     groff  (1) device -Tpdf.  This is the default PDF genera‐
240                     tor.  The generated PDF file is displayed  with  suitable
241                     viewer programs, such as okular(1).
242
243              pdf2   This  is  the  traditional pdf mode.  Sometimes this mode
244                     produces more correct output than the default  PDF  mode.
245                     By  default,  the  input  is formatted by groff using the
246                     PostScript device, then it is transformed  into  the  PDF
247                     file  format  using  gs(1),  or ps2pdf(1).  If that's not
248                     possible, the  PostScript  mode  (ps)  is  used  instead.
249                     Finally it is displayed using different viewer programs.
250
251              ps     Display  formatted  input in a PostScript viewer program.
252                     By default, the formatted input is displayed  in  one  of
253                     many viewer programs.
254
255              text   Format in a groff text mode and write the result to stan‐
256                     dard output without a pager or viewer program.  The  text
257                     device, latin1 by default, can be chosen with option -T.
258
259              tty    Format in a groff text mode and write the result to stan‐
260                     dard output using a text pager program, even when in  the
261                     X Window System.
262
263              www    Equivalent to --mode=html.
264
265              x      Display  the formatted input in a native roff viewer.  By
266                     default,  the  formatted  input  is  displayed  with  the
267                     gxditview(1)  program  being  distributed  together  with
268                     groff.   But  the  legacy  X  Window  System  application
269                     xditview(1)  can also be chosen with the option --viewer.
270                     The default resolution is 75dpi, but 100dpi are also pos‐
271                     sible.   The  default  groff device for the resolution of
272                     75dpi is X75-12, for 100dpi it is X100.  The  correspond‐
273                     ing  groff  intermediate  output for the actual device is
274                     generated and the result is displayed.  For a  resolution
275                     of  100dpi, the default width of the geometry of the dis‐
276                     play program is chosen to 850dpi.
277
278              X      Equivalent to --mode=x.
279
280              xhtml  Translate the input into XHTML format, which  is  an  XML
281                     version  of  HTML.   Then  display  the  result  in a web
282                     browser program, mostly the known HTML viewers.
283
284              The following modes do not use  the  groffer  viewing  features.
285              They are only interesting for advanced applications.
286
287              groff  Generate device output with plain groff without using the
288                     special viewing features of groffer.  If  no  device  was
289                     specified by option -T the groff default ps is assumed.
290
291              source Output  the  roff  source code of the input files without
292                     further processing.
293
294       --pdf  Equivalent to --mode=pdf.
295       --pdf2 Equivalent to --mode=pdf2.
296
297       --ps   Equivalent to  --mode=ps.   Common  PostScript  viewers  include
298              okular(1),  evince(1),  gv(1),  ghostview(1), and gs(1), In each
299              case, arguments can be provided additionally.
300
301       --source
302              Equivalent to --mode=source.
303
304       --text Equivalent to --mode=text.
305
306       --to-stdout
307              The file for the chosen mode is generated  and  its  content  is
308              printed to standard output.  It will not be displayed in graphi‐
309              cal mode.
310
311       --tty  Equivalent to --mode=tty.  The standard pager is less(1).   This
312              option  is  equivalent  to  man option --pager=prog.  The option
313              argument can be a file name or  a  program  to  be  searched  in
314              $PATH; arguments can be provided additionally.
315
316       --viewer prog
317              Choose  a viewer program for actual device or mode.  This can be
318              a file name or a program to be searched in $PATH; arguments  can
319              be provided additionally.
320
321       --www  Equivalent to --mode=html.
322
323       --X | --x
324              Equivalent   to   --mode=x.    Suitable   viewer   programs  are
325              gxditview(1) which is the default and xditview(1).
326
327       --     Signals the end of option processing;  all  remaining  arguments
328              are interpreted as filespec parameters.
329
330       Besides these, groffer accepts all short options that are valid for the
331       groff(1) program.  All non-groffer options are sent unmodified via grog
332       to  groff.  So postprocessors, macro packages, compatibility with clas‐
333       sical troff, and much more can be manually specified.
334
335   Options related to groff
336       All short options of groffer are compatible with the short  options  of
337       groff(1).   The  following  of  groff options have either an additional
338       special meaning within groffer or make sense for normal usage.
339
340       Because of the special outputting  behavior  of  the  groff  option  -Z
341       groffer  was designed to be switched into groff mode; the groffer view‐
342       ing features are disabled there.  The other groff options do not switch
343       the mode, but allow to customize the formatting process.
344
345       --a    This   generates   an  ASCII  approximation  of  output  in  the
346              text modes.  That could be important when  the  text  pager  has
347              problems with control sequences in tty mode.
348
349       --m file
350              Add  file as a groff macro file.  This is useful in case it can‐
351              not be recognized automatically.
352
353       --P opt_or_arg
354              Send the argument opt_or_arg as an option or option argument  to
355              the actual groff postprocessor.
356
357       --T devname | --device devname
358              This  option  determines groff's output device.  The most impor‐
359              tant devices are the text output devices for  referring  to  the
360              different character sets, such as ascii, utf8, latin1, utf8, and
361              others.   Each  of  these  arguments  switches  groffer  into  a
362              text  mode  using this device, to mode tty if the actual mode is
363              not a text mode.  The following devname arguments are mapped  to
364              the  corresponding  groffer  --mode=devname  option:  dvi, html,
365              xhtml, and ps.  All X* arguments are mapped  to  mode  x.   Each
366              other devname argument switches to mode groff using this device.
367
368       --X    is  equivalent  to groff -X.  It displays the groff intermediate
369              output with gxditview.  As the quality is  relatively  bad  this
370              option is deprecated; use --X instead because the x mode uses an
371              X* device for a better display.
372
373       -Z | --intermediate-output | --ditroff
374              Switch into groff mode and  format  the  input  with  the  groff
375              intermediate  output  without  postprocessing; see groff_out(5).
376              This is equivalent to option --ditroff of man, which can be used
377              as well.
378
379       All  other  groff  options  are supported by groffer, but they are just
380       transparently transferred  to  groff  without  any  intervention.   The
381       options  that  are  not explicitly handled by groffer are transparently
382       passed to groff.  Therefore these transparent  options  are  not  docu‐
383       mented  here,  but in groff(1).  Due to the automatism in groffer, none
384       of these groff options should be needed, except for advanced usage.
385
386   Options for man pages
387       --apropos
388              Start the apropos(1) command or facility of man(1) for searching
389              the  filespec  arguments within all man page descriptions.  Each
390              filespec argument is taken for search as it is; section specific
391              parts  are  not  handled, such that 7 groff searches for the two
392              arguments 7 and groff, with a large  result;  for  the  filespec
393              groff.7  nothing  will be found.  The language locale is handled
394              only when the called programs do support this; the  GNU  apropos
395              and man -k do not.  The display differs from the apropos program
396              by the following concepts:
397
398              * Construct a groff frame similar to a man page to the output of
399                apropos,
400
401              * each filespec argument is searched on its own.
402
403              * The restriction by --sections is handled as well,
404
405              * wildcard  characters are allowed and handled without a further
406                option.
407
408       --apropos-data
409              Show only the apropos descriptions for data documents, these are
410              the  man(7)  sections  4, 5, and 7.  Direct section declarations
411              are ignored, wildcards are accepted.
412
413       --apropos-devel
414              Show only the apropos descriptions  for  development  documents,
415              these  are the man(7) sections 2, 3, and 9.  Direct section dec‐
416              larations are ignored, wildcards are accepted.
417
418       --apropos-progs
419              Show only the apropos descriptions for  documents  on  programs,
420              these  are the man(7) sections 1, 6, and 8.  Direct section dec‐
421              larations are ignored, wildcards are accepted.
422
423       --whatis
424              For each filespec argument search  all  man  pages  and  display
425              their  description  — or say that it is not a man page.  This is
426              written from anew, so it differs from man's whatis output by the
427              following concepts
428
429              * each retrieved file name is added,
430
431              * local files are handled as well,
432
433              * the language and system locale is supported,
434
435              * the  display  is  framed by a groff output format similar to a
436                man page,
437
438              * wildcard characters are allowed without a further option.
439
440       The following options were added to groffer for  choosing  whether  the
441       file  name  arguments  are interpreted as names for local files or as a
442       search pattern for man pages.  The default  is  looking  up  for  local
443       files.
444
445       --man  Check the non-option command-line arguments (filespecs) first on
446              being man pages, then whether they represent an  existing  file.
447              By default, a filespec is first tested whether it is an existing
448              file.
449
450       --no-man | --local-file
451              Do not check for man pages.  --local-file is  the  corresponding
452              man option.
453
454       --no-special
455              Disable former calls of --all, --apropos*, and --whatis.
456
457   Long options taken over from GNU man
458       The  long options of groffer were synchronized with the long options of
459       GNU man.  All long options of GNU man are recognized, but  not  all  of
460       these  options  are  important to groffer, so most of them are just ig‐
461       nored.  These ignored man options are --catman, --troff, and --update.
462
463       In the following, the man options  that  have  a  special  meaning  for
464       groffer are documented.
465
466       If your system has GNU man installed the full set of long and short op‐
467       tions of the GNU man program can be passed via the environment variable
468       MANOPT; see man(1).
469
470       --all  In  searching man pages, retrieve all suitable documents instead
471              of only one.
472
473       -7 | --ascii
474              In text modes, display ASCII translation of  special  characters
475              for   critical   environment.    This  is  equivalent  to  groff
476              -mtty_char; see groff_tmac(5).
477
478       --ditroff
479              Produce  groff  intermediate  output.   This  is  equivalent  to
480              groffer -Z.
481
482       --extension suffix
483              Restrict man page search to file names that have suffix appended
484              to their  section  element.   For  example,  in  the  file  name
485              /usr/share/man/man3/terminfo.3ncurses.gz  the man page extension
486              is ncurses.
487
488       --locale language
489              Set the language for man pages.  This has the same  effect,  but
490              overwrites $LANG.
491
492       --location
493              Print the location of the retrieved files to standard error.
494
495       --no-location
496              Do  not  display  the location of retrieved files; this resets a
497              former call to --location.  This was added by groffer.
498
499       --manpath 'dir1:dir2:...'
500              Use the specified search path for retrieving man  pages  instead
501              of  the  program  defaults.  If the argument is set to the empty
502              string "" the search for man page is disabled.
503
504       --pager
505              Set the pager program in tty mode; default is less.  This can be
506              set with --viewer.
507
508       --sections sec1:sec2:...
509              Restrict searching for man pages to the given sections, a colon-
510              separated list.
511
512       --systems sys1,sys2,...
513              Search for man pages for the given operating systems; the  argu‐
514              ment systems is a comma-separated list.
515
516       --where
517              Equivalent to --location.
518
519   X Window System Toolkit Intrinsics Options
520       The following long options were adapted from the corresponding X Window
521       System Toolkit Intrinsics options.  groffer will pass them to the actu‐
522       al viewer program if it is an X Window System program.  Otherwise these
523       options are ignored.
524
525       Unfortunately these options use the old style of  a  single  minus  for
526       long  options.  For groffer that was changed to the standard with using
527       a double minus for long options, for example, groffer uses  the  option
528       --font for the X Window System Toolkit Intrinsics option -font.
529
530       See X(7) and the manual X Toolkit Intrinsics  C Language Interface for
531       more details on these options and their arguments.
532
533       --background color
534              Set the background color of the viewer window.
535
536       --bd pixels
537              This is equivalent to --bordercolor.
538
539       --bg color
540              This is equivalent to --background.
541
542       --bw pixels
543              This is equivalent to --borderwidth.
544
545       --bordercolor pixels
546              Specifies the color of the border surrounding the viewer window.
547
548       --borderwidth pixels
549              Specifies the width in pixels  of  the  border  surrounding  the
550              viewer window.
551
552       --display X-display
553              Set  the  X  Window  System  display on which the viewer program
554              shall be started.  See section “Display Names” in X(7)  for  the
555              syntax of the argument.
556
557       --foreground color
558              Set the foreground color of the viewer window.
559
560       --fg color
561              This is equivalent to --foreground.
562
563       --fn font_name
564              This is equivalent to --font.
565
566       --font font_name
567              Set  the  font  used by the viewer window.  The argument is an X
568              Window System font name.
569
570       --ft font_name
571              This is equivalent to --font.
572
573       --geometry size_pos
574              Set the geometry of the display window, that means its size  and
575              its starting position.  See section “Geometry Specifications” in
576              X(7) for the syntax of the argument.
577
578       --resolution value
579              Set X Window System resolution in dpi (dots per  inch)  in  some
580              viewer  programs.  The only supported dpi values are 75 and 100.
581              Actually, the default resolution for groffer is  set  to  75dpi.
582              The resolution also sets the default device in mode x.
583
584       --rv   Reverse foreground and background color of the viewer window.
585
586       --title 'some text'
587              Set the title for the viewer window.
588
589       --xrm 'resource'
590              Set the X Window System server resource to the given value.
591
592   Options for Development
593       --debug
594              Enable  all debugging options --debug-type.  The temporary files
595              are kept and not deleted, the grog output is printed,  the  name
596              of  the temporary directory is printed, the displayed file names
597              are printed, and the parameters are printed.
598
599       --debug-filenames
600              Print the names of the files and man pages that are displayed by
601              groffer.
602
603       --debug-grog
604              Print the output of all grog commands.
605
606       --debug-keep
607              Enable two debugging informations.  Print the name of the tempo‐
608              rary directory and keep the temporary files, do not delete  them
609              during the run of groffer.
610
611       --debug-params
612              Print  the parameters, as obtained from the configuration files,
613              from GROFFER_OPT, and the command-line arguments.
614
615       --debug-tmpdir
616              Print the name of the temporary directory.
617
618       --do-nothing
619              This is like --version, but without the  output;  no  viewer  is
620              started.  This makes only sense in development.
621
622       --print=text
623              Just print the argument to standard error.  This is good for pa‐
624              rameter check.
625
626       -V     This is an advanced option for debugging only.  Instead of  dis‐
627              playing  the formatted input, a lot of groffer specific informa‐
628              tion is printed to standard output:
629
630              * the output file name in the temporary directory,
631
632              * the display mode of the actual groffer run,
633
634              * the display program for viewing the output with its arguments,
635
636              * the active parameters from the config files, the arguments  in
637                GROFFER_OPT, and the arguments of the command line,
638
639              * the pipeline that would be run by the groff program, but with‐
640                out executing it.
641
642       Other  useful  debugging  options  are  the   groff   option   -Z   and
643       --mode=groff.
644
645   Filespec Arguments
646       A filespec parameter is an argument that is not an option or option ar‐
647       gument.  In groffer, filespec parameters are a file name or a  template
648       for  searching  man  pages.  These input sources are collected and com‐
649       posed into a single output file such as groff does.
650
651       The strange POSIX behavior to regard all  arguments  behind  the  first
652       non-option argument as filespec arguments is ignored.  The GNU behavior
653       to recognize options even when mixed with filespec  arguments  is  used
654       throughout.   But,  as usual, the double minus argument -- ends the op‐
655       tion handling and interprets all following arguments as filespec  argu‐
656       ments; so the POSIX behavior can be easily adopted.
657
658       The  options  --apropos* have a special handling of filespec arguments.
659       Each argument is taken as a search scheme of its own.   Also  a  regexp
660       (regular expression) can be used in the filespec.  For example, groffer
661       --apropos '^gro.f$' searches groff in the man page name, while  groffer
662       --apropos  groff searches groff somewhere in the name or description of
663       the man pages.
664
665       All other parts of groffer, such as the normal display  or  the  output
666       with  --whatis  have  a different scheme for filespecs.  No regular ex‐
667       pressions are used for the arguments.  The filespec arguments are  han‐
668       dled by the following scheme.
669
670       It  is  necessary  to know that on each system the man pages are sorted
671       according to their content into several sections.   The  classical  man
672       sections  have  a  single-character name, either a digit from 1 to 9 or
673       one of the characters n or o.
674
675       This can optionally be followed by a string, the  so-called  extension.
676       The  extension  allows  the  storage of several man pages with the same
677       name in the same section.  But the extension is only rarely used;  usu‐
678       ally  it is omitted.  Then the extensions are searched automatically by
679       alphabet.
680
681       In the following, we use the name section_extension  for  a  word  that
682       consists of a single character section name or a section character that
683       is followed by an extension.  Each filespec parameter can have  one  of
684       the following forms in decreasing sequence.
685
686       * No  filespec  parameters means that groffer waits for standard input.
687         The minus option - always stands for standard  input;  it  can  occur
688         several  times.   If  you want to look up a man page called - use the
689         argument man:-.
690
691       * Next a filespec is tested whether it is the path name of an  existing
692         file.   Otherwise  it  is  assumed  to  be  a searching pattern for a
693         man page.
694
695       * man:name(section_extension),              man:name.section_extension,
696         name(section_extension),   or   name.section_extension   search   the
697         man  page  name  in   man   section   and   possibly   extension   of
698         section_extension.
699
700       * Now  man:name  searches for a man page in the lowest man section that
701         has a document called name.
702
703       * section_extension name is a pattern of 2  arguments  that  originates
704         from  a  strange  argument  parsing  of the man program.  Again, this
705         searches the man page name with section_extension, a combination of a
706         section character optionally followed by an extension.
707
708       * We are left with the argument name which is not an existing file.  So
709         this searches for the man page called name in the lowest man  section
710         that has a document for this name.
711
712       Several  file  name arguments can be supplied.  They are mixed by groff
713       into a single document.  Note that the set of option arguments must fit
714       to  all of these file arguments.  So they should have at least the same
715       style of the groff language.
716

OUTPUT MODES

718       By default, the groffer program collects all input into a single  file,
719       formats it with the groff program for a certain device, and then choos‐
720       es a suitable viewer program.  The device and viewer process in groffer
721       is  called a mode.  The mode and viewer of a running groffer program is
722       selected automatically, but the user can also choose it  with  options.
723       The  modes are selected by option the arguments of --mode=anymode.  Ad‐
724       ditionally, each of this argument can be specified as an option of  its
725       own, such as anymode.  Most of these modes have a viewer program, which
726       can be chosen by the option --viewer.
727
728       Several different modes are offered: graphical modes for the  X  Window
729       System,  text  modes, and some direct groff modes for debugging and de‐
730       velopment.
731
732       By default, groffer first  tries  whether  x  mode  is  possible,  then
733       ps  mode,  and  finally  tty  mode.   This  mode  testing  sequence for
734       auto mode can be changed by specifying a comma separated list of  modes
735       with the option --default-modes.
736
737       The  searching for man pages and the decompression of the input are ac‐
738       tive in every mode.
739
740   Graphical Display Modes
741       The graphical display modes work mostly in the X Window System environ‐
742       ment  (or similar implementations within other windowing environments).
743       The environment variable DISPLAY and the option --display are used  for
744       specifying the X Window System display to be used.  If this environment
745       variable is empty, groffer assumes that the X Window System is not run‐
746       ning  and changes to a text mode.  You can change this automatic behav‐
747       ior by the option --default-modes.
748
749       Known viewers for the graphical display modes and their standard X Win‐
750       dow System viewer programs are
751
752       * in a PDF viewer (pdf mode)
753
754       * in a web browser (html, (xhtml, or www mode)
755
756       * in a PostScript viewer (ps mode)
757
758       * X  Window System roff viewers such as gxditview(1) or xditview(1) (in
759         x mode)
760
761       * in a DVI viewer program (dvi mode)
762
763       The pdf mode has a major advantage — it is the only  graphical  display
764       mode  that  allows  searching for text within the viewer; this can be a
765       really important feature.  Unfortunately, it takes some time to  trans‐
766       form  the  input into the PDF format, so it was not chosen as the major
767       mode.
768
769       These graphical viewers can be customized by options of  the  X  Window
770       System  Toolkit Intrinsics.  But the groffer options use a leading dou‐
771       ble minus instead of the single minus used by the X Window System Tool‐
772       kit Intrinsics.
773
774   Text modes
775       There are two modes for text output, mode text for plain output without
776       a pager and mode tty for a text output on a text  terminal  using  some
777       pager program.
778
779       If  the  variable  DISPLAY is not set or empty, groffer assumes that it
780       should use tty mode.
781
782       In the actual implementation, the groff output device latin1 is  chosen
783       for  text  modes.   This  can  be  changed  by  specifying option -T or
784       --device.
785
786       The pager to be used can be specified by one of the options --pager and
787       --viewer,  or by the environment variable PAGER.  If all of this is not
788       used the less(1) program with the option -r  for  correctly  displaying
789       control sequences is used as the default pager.
790
791   Special Modes for Debugging and Development
792       These modes use the groffer file determination and decompression.  This
793       is combined into a single input file that is fed  directly  into  groff
794       with  different strategy without the groffer viewing facilities.  These
795       modes are regarded as advanced, they are useful for debugging  and  de‐
796       velopment purposes.
797
798       The source mode with option --source just displays the decompressed in‐
799       put.
800
801       Option --to-stdout does not display in a graphical mode.  It just  gen‐
802       erates  the  file  for  the  chosen mode and then prints its content to
803       standard output.
804
805       The groff mode passes the input to groff using only some  suitable  op‐
806       tions provided to groffer.  This enables the user to save the generated
807       output into a file or pipe it into another program.
808
809       In groff mode, the option -Z disables post-processing,  thus  producing
810       the  groff  intermediate output.  In this mode, the input is formatted,
811       but not postprocessed; see groff_out(5) for details.
812
813       All groff short options are supported by groffer.
814

MAN PAGE SEARCHING

816       The default behavior of groffer is to first test whether a file parame‐
817       ter  represents a local file; if it is not an existing file name, it is
818       assumed to represent the name of a man page.  The following options can
819       be  used  to  determine whether the arguments should be handled as file
820       name or man page arguments.
821
822       --man  forces to interpret all file parameters as filespecs for search‐
823              ing man pages.
824
825       --no-man
826       --local-file
827              disable the man searching; so only local files are displayed.
828
829       If  neither a local file nor a man page was retrieved for some file pa‐
830       rameter a warning is issued on standard error, but processing  is  con‐
831       tinued.
832
833   Search Algorithm
834       Let us now assume that a man page should be searched.  The groffer pro‐
835       gram provides a search facility for man pages.  All long  options,  all
836       environment  variables, and most of the functionality of the GNU man(1)
837       program were implemented.  The search algorithm shall  determine  which
838       file is displayed for a given man page.  The process can be modified by
839       options and environment variables.
840
841       The only man action that is omitted in  groffer  are  the  preformatted
842       man  pages,  also  called cat pages.  With the excellent performance of
843       the actual computers, the preformatted man pages aren't  necessary  any
844       longer.  Additionally, groffer is a roff program; it wants to read roff
845       source files and format them itself.
846
847       The algorithm for retrieving the file for a man page needs first a  set
848       of  directories.   This  set starts with the so-called man path that is
849       modified later on by adding names of  operating  system  and  language.
850       This  arising set is used for adding the section directories which con‐
851       tain the man page files.
852
853       The man path is a list of directories that are separated by colon.   It
854       is generated by the following methods.
855
856       * The environment variable MANPATH can be set.
857
858       * It can be read from the arguments of the environment variable MANOPT.
859
860       * The man path can be manually specified by using the option --manpath.
861         An empty argument disables the man page searching.
862
863       * When no man path was set the manpath(1) program is tried to determine
864         one.
865
866       * If  this does not work a reasonable default path from $PATH is deter‐
867         mined.
868
869       We now have a starting set of directories.  The  first  way  to  change
870       this  set  is  by adding names of operating systems.  This assumes that
871       man pages for several operating systems are installed.  This is not al‐
872       ways  true.   The  names of such operating systems can be provided by 3
873       methods.
874
875       * The environment variable SYSTEM has the lowest precedence.
876
877       * This can be overridden by an option in MANOPT.
878
879       * This again is overridden by the command-line option --systems.
880
881       Several names of operating systems can  be  given  by  appending  their
882       names, separated by a comma.
883
884       The  man  path is changed by appending each system name as subdirectory
885       at the end of each directory of the set.  No directory of the man  path
886       set  is  kept.  But if no system name is specified the man path is left
887       unchanged.
888
889       After this, the actual set of directories can be  changed  by  language
890       information.  This assumes that there exist man pages in different lan‐
891       guages.  The wanted language can be chosen by several methods.
892
893       * Environment variable LANG.
894
895       * This is overridden by LC_MESSAGES.
896
897       * This is overridden by LC_ALL.
898
899       * This can be overridden by providing an option in MANOPT.
900
901       * All these environment variables are overridden  by  the  command-line
902         option --locale.
903
904       The  default language can be specified by specifying one of the pseudo-
905       language parameters C or POSIX.  This is like deleting a formerly given
906       language information.  The man pages in the default language are usual‐
907       ly in English.
908
909       Of course, the language name is determined by man.  In GNU man,  it  is
910       specified in the POSIX 1003.1 based format:
911
912       <language>[_<territory>[.<character-set>[,<version>]]],
913
914       but  the two-letter code in <language> is sufficient for most purposes.
915       If for a complicated  language  formulation  no  man  pages  are  found
916       groffer searches the country part consisting of these first two charac‐
917       ters as well.
918
919       The actual directory set is copied thrice.  The language  name  is  ap‐
920       pended as subdirectory to each directory in the first copy of the actu‐
921       al directory set (this is only done when a language information is giv‐
922       en).   Then  the 2-letter abbreviation of the language name is appended
923       as subdirectories to the second copy of the directory set (this is only
924       done  when the given language name has more than 2 letters).  The third
925       copy of the directory set is kept unchanged (if no language information
926       is given this is the kept directory set).  These maximally 3 copies are
927       appended to get the new directory set.
928
929       We now have a complete set of directories to work  with.   In  each  of
930       these  directories,  the man files are separated in sections.  The name
931       of a section is represented by a single character, a  digit  between  1
932       and 9, or the character o or n, in this order.
933
934       For each available section, a subdirectory man<section> exists contain‐
935       ing all man files for this section, where <section> is a single charac‐
936       ter  as described before.  Each man file in a section directory has the
937       form man<section>/<name>.<section>[<extension>][.<compression>],  where
938       <extension>  and <compression> are optional.  <name> is the name of the
939       man page that is also specified as filespec  argument  on  the  command
940       line.
941
942       The  extension is an addition to the section.  This postfix acts like a
943       subsection.  An extension occurs only in the file name, not in name  of
944       the section subdirectory.  It can be specified on the command line.
945
946       On  the  other  hand, the compression is just an information on how the
947       file is compressed.  This is not important for the user, such  that  it
948       cannot be specified on the command line.
949
950       There are 4 methods to specify a section on the command line:
951
952       * Environment variable MANSECT
953
954       * Command line option --sections
955
956       * Appendix to the name argument in the form <name>.<section>
957
958       * Preargument before the name argument in the form <section> <name>
959
960       It is also possible to specify several sections by appending the single
961       characters separated by colons.  One can imagine that this means to re‐
962       strict  the  man  page search to only some sections.  The multiple sec‐
963       tions are only possible for MANSECT and --sections.
964
965       If no section is specified all sections are searched one after the oth‐
966       er  in  the given order, starting with section 1, until a suitable file
967       is found.
968
969       There are 4 methods to specify an extension on the command  line.   But
970       it is not necessary to provide the whole extension name, some abbrevia‐
971       tion is good enough in most cases.
972
973       * Environment variable EXTENSION
974
975       * Command line option --extension
976
977       * Appendix to the <name>.<section> argument in  the  form  <name>.<sec‐
978         tion><extension>
979
980       * Preargument before the name argument in the form <section><extension>
981         <name>
982
983       For further details on man page searching, see man(1).
984
985   Examples of man files
986       /usr/share/man/man1/groff.1
987              This is an uncompressed file for the  man  page  groff  in  sec‐
988              tion 1.  It can be called by
989              sh# groffer groff
990              No  section  is  specified  here,  so  all  sections  should  be
991              searched, but as section 1 is searched first this file  will  be
992              found  first.  The file name is composed of the following compo‐
993              nents.  /usr/share/man/ must be part of the man path; the subdi‐
994              rectory  man1/  and  the part .1 stand for the section; groff is
995              the name of the man page.
996
997       /usr/local/share/man/man7/groff.7.gz
998              The  file  name  is  composed  of  the   following   components.
999              /usr/local/share/man must be part of the man path; the subdirec‐
1000              tory man7/ and the part .7 stand for the section; groff  is  the
1001              name  of  the man page; the final part .gz stands for a compres‐
1002              sion with gzip(1).  As the section is not the first one it  must
1003              be  specified as well.  This can be done by one of the following
1004              commands.
1005              sh# groffer groff.7
1006              sh# groffer 7 groff
1007              sh# groffer --sections=7 groff
1008
1009       /usr/local/man/man1/ctags.1emacs21.bz2
1010              Here /usr/local/man must be in man path; the subdirectory  man1/
1011              and  the  file name part .1 stand for section 1; the name of the
1012              man page is ctags; the section has an extension emacs21; and the
1013              file  is  compressed  as  .bz2  with  bzip2(1).  The file can be
1014              viewed with one of the following commands
1015              sh# groffer ctags.1e
1016              sh# groffer 1e ctags
1017              sh# groffer --extension=e --sections=1 ctags
1018              where e works as an abbreviation for the extension emacs21.
1019
1020       /usr/man/linux/de/man7/man.7.Z
1021              The directory /usr/man is now part of the man path;  then  there
1022              is  a  subdirectory  for  an  operating system name linux/; next
1023              comes a subdirectory de/ for the German  language;  the  section
1024              names  man7  and  .7  are  known  so far; man is the name of the
1025              man page; and .Z signifies the compression that can  be  handled
1026              by  gzip(1).  We want now show how to provide several values for
1027              some options.  That is possible for sections and operating  sys‐
1028              tem  names.   So  we use as sections 5 and 7 and as system names
1029              linux and aix.  The command is then
1030
1031              sh# groffer --locale=de --sections=5:7 --systems=linux,aix man
1032              sh# LANG=de MANSECT=5:7 SYSTEM=linux,aix groffer man
1033

DECOMPRESSION

1035       The program has a decompression facility.  If standard input or a  file
1036       that  was retrieved from the command line parameters is compressed with
1037       a format that is supported by either gzip(1) or bzip2(1) it  is  decom‐
1038       pressed  on-the-fly.   This  includes the GNU .gz, .bz2, and the tradi‐
1039       tional .Z compression.  The program displays the concatenation  of  all
1040       decompressed  input  in  the sequence that was specified on the command
1041       line.
1042

ENVIRONMENT

1044       The groffer program supports many system variables,  most  of  them  by
1045       courtesy  of other programs.  All environment variables of groff(1) and
1046       GNU man(1) and some standard system variables are honored.
1047
1048   Native groffer Variables
1049       GROFFER_OPT
1050              Store options for a run of groffer.  The  options  specified  in
1051              this variable are overridden by the options given on the command
1052              line.  The content of this variable is  run  through  the  shell
1053              builtin  “eval”,  so  arguments containing whitespace or special
1054              shell characters should be quoted.  Do not forget to export this
1055              variable, otherwise it does not exist during the run of groffer.
1056
1057   System Variables
1058       The following variables have a special meaning for groffer.
1059
1060       DISPLAY
1061              If set, this variable indicates that the X Window System is run‐
1062              ning.  Testing this variable decides  on  whether  graphical  or
1063              text  output  is generated.  This variable should not be changed
1064              by the user carelessly, but it can be used to start the  graphi‐
1065              cal  groffer on a remote X Window System terminal.  For example,
1066              depending on your system, groffer can be started on  the  second
1067              monitor by the command
1068
1069              sh# DISPLAY=:0.1 groffer what.ever &
1070
1071       LC_ALL
1072       LC_MESSAGES
1073       LANG   If  one  of  these variables is set (in the above sequence), its
1074              content is interpreted as the locale, the language to  be  used,
1075              especially  when  retrieving  man pages.  A locale name is typi‐
1076              cally  of  the  form  language[_territory[.codeset[@modifier]]],
1077              where  language is an ISO 639 language code, territory is an ISO
1078              3166 country code, and codeset is a character  set  or  encoding
1079              identifier  like ISO-8859-1 or UTF-8; see setlocale(3).  The lo‐
1080              cale values C and POSIX stand for the default, i.e. the man page
1081              directories  without a language prefix.  This is the same behav‐
1082              ior as when all 3 variables are unset.
1083
1084       PAGER  This variable can be used to set the pager for the  tty  output.
1085              For  example,  to disable the use of a pager completely set this
1086              variable to the cat(1) program
1087
1088              sh# PAGER=cat groffer anything
1089
1090
1091       PATH   All programs within the groffer  script  are  called  without  a
1092              fixed  path.   Thus this environment variable determines the set
1093              of programs used within the run of groffer.
1094
1095   Groff Variables
1096       The groffer program internally calls groff, so  all  environment  vari‐
1097       ables  documented  in  groff(1)  are  internally used within groffer as
1098       well.  The following variable has a direct meaning for the groffer pro‐
1099       gram.
1100
1101       GROFF_TMPDIR
1102              If  the  value  of this variable is an existing, writable direc‐
1103              tory, groffer uses it for storing its temporary files,  just  as
1104              groff  does.   See the groff(1) man page for more details on the
1105              location of temporary files.
1106
1107   Man Variables
1108       Parts of the functionality of  the  man  program  were  implemented  in
1109       groffer; support for all environment variables documented in man(1) was
1110       added to groffer, but the meaning was slightly modified due to the dif‐
1111       ferent  approach  in  groffer; but the user interface is the same.  The
1112       man environment variables can be overwritten by options  provided  with
1113       MANOPT, which in turn is overwritten by the command line.
1114
1115       EXTENSION
1116              Restrict  the  search  for man pages to files having this exten‐
1117              sion.  This is overridden by option --extension; see  there  for
1118              details.
1119
1120       MANOPT This  variable  contains options as a preset for man(1).  As not
1121              all of these are relevant for groffer only the  essential  parts
1122              of its value are extracted.  The options specified in this vari‐
1123              able overwrite the values of  the  other  environment  variables
1124              that  are  specific to man.  All options specified in this vari‐
1125              able are overridden by the options given on the command line.
1126
1127       MANPATH
1128              If set, this variable contains  the  directories  in  which  the
1129              man  page  trees  are  stored.   This  is  overridden  by option
1130              --manpath.
1131
1132       MANSECT
1133              If this is a colon separated list of section names,  the  search
1134              for  man  pages  is  restricted to those manual sections in that
1135              order.  This is overridden by option --sections.
1136
1137       SYSTEM If this is set to a comma separated  list  of  names  these  are
1138              interpreted  as  man page trees for different operating systems.
1139              This variable can be overwritten by option --systems; see  there
1140              for details.
1141
1142       The  environment  variable MANROFFSEQ is ignored by groffer because the
1143       necessary preprocessors are determined automatically.
1144

CONFIGURATION FILES

1146       The groffer program can be preconfigured by two configuration files.
1147
1148       /etc/groff/groffer.conf
1149              System-wide configuration file for groffer.
1150
1151       $HOME/.groff/groffer.conf
1152              User-specific  configuration  file  for  groffer,  where   $HOME
1153              denotes  the  user's  home directory.  This file is called after
1154              the system-wide configuration file to enable overriding  by  the
1155              user.
1156
1157       Both  files  are  handled  for the configuration, but the configuration
1158       file in /etc comes first; it is overwritten by the  configuration  file
1159       in  the home directory; both configuration files are overwritten by the
1160       environment variable GROFFER_OPT; everything is overwritten by the com‐
1161       mand line arguments.
1162
1163       The  configuration  files  contain  options  that  should  be called as
1164       default for every groffer run.  These options are written in lines such
1165       that  each  contains  either  a long option, a short option, or a short
1166       option cluster; each with or without an argument.  So  each  line  with
1167       configuration  information  starts  with  a minus character “-”; a line
1168       with a long option starts with two minus characters “--”, a line with a
1169       short option or short option cluster starts with a single minus “-”.
1170
1171       The  option  names  in  the configuration files may not be abbreviated,
1172       they must be exact.
1173
1174       The argument for a long option can be separated from  the  option  name
1175       either by an equal sign “=” or by whitespace, i.e. one or several space
1176       or tab characters.  An argument for a  short  option  or  short  option
1177       cluster  can  be  directly  appended to the option name or separated by
1178       whitespace.  The end of an argument is the end of the line.  It is  not
1179       allowed  to use a shell environment variable in an option name or argu‐
1180       ment.
1181
1182       It is not necessary to use quotes in an option or argument, except  for
1183       empty arguments.  An empty argument can be provided by appending a pair
1184       of quotes to the separating equal sign  or  whitespace;  with  a  short
1185       option, the separator can be omitted as well.  For a long option with a
1186       separating equal sign “=”, the pair of quotes can be omitted, thus end‐
1187       ing  the  line with the separating equal sign.  All other quote charac‐
1188       ters are cancelled internally.
1189
1190       In the configuration files, arbitrary  whitespace  is  allowed  at  the
1191       beginning  of  each line, it is just ignored.  Each whitespace within a
1192       line is replaced by a single space character “ ” internally.
1193
1194       All lines of the configuration lines that do not  start  with  a  minus
1195       character  are ignored, such that comments starting with “#” are possi‐
1196       ble.  So there are no shell commands in the configuration files.
1197
1198       As an example, consider the following configuration file  that  can  be
1199       used either in /etc/groff/groffer.conf or ~/.groff/groffer.conf .
1200
1201       # groffer configuration file
1202       #
1203       # groffer options that are used in each call of groffer
1204       --foreground=DarkBlue
1205       --resolution=100
1206       --viewer=gxditview -geometry 900x1200
1207
1208       The  lines  starting  with  #  are just ignored, so they act as command
1209       lines.  This configuration sets four groffer options (the lines  start‐
1210       ing with “-”).  This has the following effects:
1211
1212       * Use  a  text color of DarkBlue in all viewers that support this, such
1213         as gxditview.
1214
1215       * Use a resolution of 100dpi in all viewers that support this, such  as
1216         gxditview.  By this, the default device in x mode is set to X100.
1217
1218       * Force gxditview(1) as the x-mode viewer using the geometry option for
1219         setting the width to 900px and the height to 1200px.   This  geometry
1220         is suitable for a resolution of 100dpi.
1221
1222       * Use xpdf(1) as the pdf-mode viewer with the argument -Z 150.
1223

EXAMPLES

1225       The  usage  of groffer is very easy.  Usually, it is just called with a
1226       file name or man page.  The  following  examples,  however,  show  that
1227       groffer has much more fancy capabilities.
1228
1229       sh# groffer /usr/local/share/doc/groff/meintro.ms.gz
1230
1231       Decompress, format and display the compressed file meintro.ms.gz in the
1232       directory  /usr/local/share/doc/groff,  using   the   standard   viewer
1233       gxditview  as  graphical  viewer  when  in  the X Window System, or the
1234       less(1) pager program otherwise.
1235
1236       sh# groffer groff
1237
1238       If the file ./groff exists use it as input.   Otherwise  interpret  the
1239       argument  as a search for the man page named groff in the smallest pos‐
1240       sible man section, being section 1 in this case.
1241
1242       sh# groffer man:groff
1243
1244       search for the man page of groff even when the file ./groff exists.
1245
1246       sh# groffer groff.7
1247       sh# groffer 7 groff
1248
1249       search the man page of groff in man section  7.   This  section  search
1250       works only for a digit or a single character from a small set.
1251
1252       sh# groffer fb.modes
1253
1254       If  the  file  ./fb.modes does not exist interpret this as a search for
1255       the man page of fb.modes.  As the extension modes is not a single char‐
1256       acter  in classical section style the argument is not split to a search
1257       for fb.
1258
1259       sh# groffer groff ’troff(1)’ man:roff
1260
1261       The arguments that are not existing files are looked-up as the  follow‐
1262       ing  man  pages:  groff  (automatic search, should be found in man sec‐
1263       tion 1), troff (in section 1), and roff (in the section with the lowest
1264       number, being 7 in this case).  The quotes around troff(1) are neces‐
1265       sary because the parentheses are  special  shell  characters;  escaping
1266       them  with a backslash character \( and \) would be possible, too.  The
1267       formatted files are concatenated and displayed in one piece.
1268
1269       sh# LANG=de groffer --man --viewer=galeon ls
1270
1271       Retrieve the German man page (language de) for the ls  program,  decom‐
1272       press it, format it to html or xhtml format (www mode) and view the re‐
1273       sult in the web browser galeon.  The option --man guarantees  that  the
1274       man  page  is retrieved, even when a local file ls exists in the actual
1275       directory.
1276
1277       sh# groffer --source 'man:roff(7)'
1278
1279       Get the man page called roff in man section 7, decompress it, and print
1280       its unformatted content, its source code.
1281
1282       sh# groffer --de-p --in --ap
1283
1284       This is a set of abbreviated arguments, it is determined as
1285
1286       sh# groffer --debug-params --intermediate-output --apropos
1287
1288
1289       sh# cat file.gz | groffer -Z -mfoo
1290
1291       The  file  file.gz is sent to standard input, this is decompressed, and
1292       then this is transported to the groff intermediate output mode  without
1293       post-processing  (groff  option  -Z),  using  macro  package foo (groff
1294       option -m).
1295
1296       sh# echo '\f(CBWOW!' |
1297       > groffer --x --bg red --fg yellow --geometry 200x100 -
1298
1299       Display the word WOW! in a small window in  constant-width  bold  font,
1300       using color yellow on red background.
1301

COMPATIBILITY

1303       The groffer program is written in Perl, the Perl version during writing
1304       was v5.8.8.
1305
1306       groffer provides its own parser for command-line arguments that is com‐
1307       patible  to  both  POSIX  getopts(1)  and GNU getopt(1).  It can handle
1308       option arguments and file names containing white space and a large  set
1309       of  special  characters.   The  following standard types of options are
1310       supported.
1311
1312       * The option consisting of a single minus - refers to standard input.
1313
1314       * A single minus followed by characters refers to  a  single  character
1315         option  or  a  combination  thereof;  for  example, the groffer short
1316         option combination -Qmfoo is equivalent to -Q -m foo.
1317
1318       * Long options are options with names longer than one  character;  they
1319         are always preceded by a double minus.  An option argument can either
1320         go to the next command-line argument or be  appended  with  an  equal
1321         sign  to  the  argument;  for  example,  --long=arg  is equivalent to
1322         --long arg.
1323
1324       * An argument of -- ends option parsing; all further command-line argu‐
1325         ments are interpreted as filespec parameters, i.e. file names or con‐
1326         structs for searching man pages).
1327
1328       * All command-line arguments that are neither options nor option  argu‐
1329         ments  are interpreted as filespec parameters and stored until option
1330         parsing has finished.  For example, the command line
1331
1332         sh# groffer file1 -a -o arg file2
1333
1334         is equivalent to
1335
1336         sh# groffer -a -o arg -- file1 file2
1337
1338
1339       The free mixing of options and  filespec  parameters  follows  the  GNU
1340       principle.   That does not fulfill the strange option behavior of POSIX
1341       that ends option processing as soon as the  first  non-option  argument
1342       has  been  reached.   The end of option processing can be forced by the
1343       option “--” anyway.
1344

AUTHORS

1346       groffer was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
1347

SEE ALSO

1349       groff(1), troff(1)
1350              Details on the options and environment  variables  available  in
1351              groff; all of them can be used with groffer.
1352
1353       grog(1)
1354              This  program  tries  to  guess the necessary groff command-line
1355              options from the input and the groffer options.
1356
1357       groff(7)
1358              Documentation of the groff language.
1359
1360       groff_char(7)
1361              Documentation on the groff characters, special  characters,  and
1362              glyphs..
1363
1364       groff_tmac(5)
1365              Documentation on the groff macro files.
1366
1367       groff_out(5)
1368              Documentation on the groff intermediate output before the run of
1369              a postprocessor.  (ditroff output).  This  can  be  run  by  the
1370              groff or groffer option -Z.
1371
1372       man(1) The  standard  program  to  display  man pages.  The information
1373              there is only useful if it is the man page for GNU man.  Then it
1374              documents  the  options  and environment variables that are sup‐
1375              ported by groffer.
1376
1377       gxditview(1)
1378       xditview(1x)
1379              Viewers for groffer's x mode.
1380
1381       kpdf(1)
1382       kghostview(1)
1383       evince(1)
1384       ggv(1)
1385       gv(1)
1386       ghostview(1)
1387       gs(1)  Viewers for groffer's ps mode.
1388
1389       kpdf(1)
1390       acroread(1)
1391       evince(1)
1392       xpdf(1)
1393       gpdf(1)
1394       kghostview(1)
1395       ggv(1) Viewers for groffer's pdf mode.
1396
1397       kdvi(1), xdvi(1), dvilx(1)
1398              Viewers for groffer's dvi mode.
1399
1400       konqueror(1)
1401       epiphany(1)
1402       firefox(1)
1403       mozilla(1)
1404       netscape(1)
1405       lynx(1)
1406              Web-browsers for groffer's html, xhtml, or www mode.
1407
1408       less(1)
1409       more(1)
1410              Standard pager program for the tty mode.
1411
1412       gzip(1)
1413       bzip2(1)
1414       xz(1)  The decompression programs supported by groffer.
1415
1416
1417
1418groff 1.22.4                    3 November 2020                     GROFFER(1)
Impressum