lexgrog

lexgrog [OPTION...] [FILE...]

When no FILE is specified, lexgrog reads from standard input.

-a, --all
    Report both warnings and errors. This is the default behavior when no other output options are specified.

-e, --errors
    Only report errors, suppressing warnings. Useful when you only care about critical issues.

-w, --warnings
    Only report warnings, suppressing errors. Useful for stylistic or less critical issues.

-q, --quiet, --no-warnings, --no-errors
    Suppress all informational output, only reporting fatal errors. Ideal for scripting where only success or failure matters.

-c, --check-only
    Perform syntax checks without outputting the parsed content of the manual page. Returns an exit status indicating success or failure, making it ideal for automated validation.

-m, --mandoc
    Parse the input as a mandoc(1)-style manual page rather than groff. Useful for man pages written in the mandoc format.

-V, --version
    Display version information of lexgrog and exit.

-h, --help
    Display a brief help message with command-line options and exit.

lexgrog is a utility for parsing and checking the syntax of manual pages written in the groff (or troff) markup language. It acts as a linter for man pages, identifying common errors such as missing required macros (e.g., .TH), incorrect section numbering, or other structural and formatting issues that could prevent a man page from being correctly displayed by the man command.

It processes the input file (or standard input) and reports warnings or errors, helping authors and packagers ensure their documentation is well-formed and adheres to standard conventions. This tool is particularly valuable for developers who write man pages for their software, aiding in the creation of robust and readable documentation. It focuses purely on the syntax and structure of the roff source, rather than semantic content.

lexgrog primarily checks the roff source syntax and structure; it does not validate the semantic correctness or factual accuracy of the manual page content. While it can detect many common formatting issues, it might not catch errors that only become apparent during the actual rendering process by groff or man.

Its main focus is on groff-style man pages, although it provides limited support for mandoc format. It's a linting tool, not a full man page renderer, so it won't show you how the page looks.

lexgrog returns an exit status of 0 if no errors or warnings are found, and a non-zero status if any issues are detected (e.g., 1 for warnings, 2 for errors). This makes it highly suitable for use in automated build systems, pre-commit hooks, and CI/CD pipelines to validate documentation automatically.

If no input FILE is specified on the command line, lexgrog conveniently reads its input from standard input (stdin). This feature allows it to be seamlessly integrated into shell pipelines, for instance, by piping the output of a text editor or a generation script directly into lexgrog for validation (e.g., cat my_man_page.1 | lexgrog).

lexgrog is an integral part of the man-db package, which is a widely adopted implementation of the man utility and its associated tools on many Linux distributions. Its development stemmed from the increasing need for robust validation of manual page sources, especially as the ecosystem of software and accompanying documentation expanded.

Its evolution is closely tied to the progress of man-db, providing a specialized tool for authors and packagers to ensure high-quality, syntactically correct manual pages before distribution. This contributes significantly to maintaining consistency and readability across the vast collection of Linux documentation.

man(1), groff(1), mandoc(1), man-pages(7), troff(1)