groffer

groffer [options...] [file...]

-a, --apropos
    Interpret arguments as topics for apropos, searching man page descriptions.

-d, --device=name
    Set the output device to name (e.g., ps, dvi, pdf, html, utf8, ascii). This determines the final rendered format.

-D, --disable-detection
    Disable automatic detection of groff options for input files.

-e, --example
    Display example output for the given arguments, demonstrating rendering.

-f, --font=name
    Set the base font to name for the output document.

-F, --font-path=dir
    Add dir to the font search path for groff.

-g, --groff-option=string
    Pass string directly as an option to the underlying groff command.

-h, --help
    Display a help message and exit.

-I, --include-path=dir
    Add dir to the groff include search path for `.so` requests.

-k, --keyword
    Treat arguments as keywords to search for within man page content.

-K, --language=lang
    Set the language for man page lookup, e.g., en, de.

-L, --list-devices
    List all available output devices and exit.

-m, --macro=name
    Use the specified macro package name (e.g., man, mdoc) for processing.

-M, --macro-path=dir
    Add dir to the macro search path for groff.

-n, --number
    Number the output pages.

-o, --output-file=file
    Redirect output to file instead of displaying it in a pager.

-O, --pager-option=string
    Pass string directly as an option to the pager program (e.g., less).

-p, --paper-size=size
    Set the paper size to size (e.g., a4, letter).

-P, --pager=pager
    Use pager instead of the default less or system-configured pager.

-r, --request=name=value
    Set a groff request name to value.

-R, --raw
    Do not process input with groff; display raw content without formatting.

-s, --section=section
    Search for man pages only in the specified section (e.g., 1, 8).

-S, --stand-alone
    Do not use groff or a pager; output raw processed content directly to stdout.

-t, --tab-width=width
    Set the tab width for processing input to width characters.

-T, --terminal=name
    Use name as the terminal type (for groff -T).

-u, --update
    Update man page caches (similar to mandb).

-U, --usage
    Display a brief usage message and exit.

-v, --version
    Display version information and exit.

-w, --whatis
    Interpret arguments as topics for whatis, displaying one-line descriptions.

-W, --warning=category
    Enable warnings for a specific category (e.g., all, missing).

-z, --compress-output
    Compress the output if writing to a file (requires gzip or similar).

--debug
    Display detailed debug information about processing.

--license
    Display license information and exit.

--pager-debug
    Display debug information related to the pager command.

--strict
    Abort processing on the first error encountered.

groffer is a versatile command-line utility for viewing groff files, man pages, and plain text documents on Unix-like systems. It acts as a sophisticated pager that automatically detects the type of input file and applies appropriate groff processing before displaying the formatted output. It can handle compressed files and supports various output devices, rendering documents into formats like PostScript, PDF, DVI, HTML, or plain text.
The primary use case is to provide a rich viewing experience for documents that would traditionally be processed by groff, including system manual pages, offering features like syntax highlighting and convenient navigation through an external pager like less. It intelligently determines the correct groff macros and options required for proper rendering, simplifying the viewing process for complex documentation.

groffer relies heavily on the underlying groff system and the configured pager (usually less). Issues with these dependencies can affect its functionality. Automatic detection can sometimes fail for unusual or malformed groff files. The man page features (sections, language, keywords) depend on a properly configured man-db or similar system. Rendering to graphical devices like PDF requires a groff device driver and potentially external tools (e.g., ghostscript for PostScript).

groffer intelligently attempts to determine the best way to process a file by examining its content and common file extensions. This includes identifying groff macro packages (like man or mdoc), character encodings, and compression types. This feature greatly simplifies viewing complex documents as users don't need to specify groff options manually.

By default, groffer pipes its processed output to a pager, typically less. This integration allows for interactive viewing, searching, and navigation within the document, providing a much richer experience than simple cat to stdout. The pager can be customized using the GROFFER_PAGER environment variable or the -P option.

groffer can be configured via several environment variables, such as GROFFER_PAGER (to specify a pager), GROFFER_COMMAND_PATH (for additional command search paths), GROFFER_GROFF_COMMAND (to override the groff command), and others. These provide granular control over its behavior.

groffer was developed as a more advanced and user-friendly front-end for viewing groff documents, especially man pages, compared to directly piping groff output to a pager. It aims to simplify the process by automating the detection of file types and groff options, providing a seamless viewing experience. Its design emphasizes convenience and flexibility, allowing users to customize viewing parameters and integrate with various output devices and pagers. The command has been maintained as part of the groff project, evolving to support new features and address user needs for document viewing.

groff(1), man(1), less(1), apropos(1), whatis(1), info(1)