mdoc

A library for defining, parsing, generating, and pretty-printing documents in the mdoc(7) language.

Motivation

This project aims to automate generating man-pages from your existing option, environment, and configuration parsers. Compared to other libraries that do this, the goals of this project are to generate man-pages that are:

• Detailed: the generated man-pages should have as much information as we can glean from parser definitions. And it should be convenient to supply additional content to be placed within, instead of, or around what has been generated. And it should be possible to specify that extra content as simple text, Mdoc AST fragments, or as Mdoc values parsed from a file.

• Conventional: the generated man-pages should follow all mdoc(7) conventions and rules. Items should be presented in property-sorted definition lists with smart widths. Generation for options and environment variables vs configuration should occur in sections 1 and 5, respectively.

In short, we allow you to maintain the high level of detail and quality that one gets from writing a man-page by hand, while avoiding the hassle of updating multiple places when your options, environment, or configuration parsers change.

Usage

This project includes the executable mdoc-dump(1). This README is a Literate Haskell file that generates a man-page from its optparse-applicative and envparse parsers:

import Prelude

import Data.Function ((&))
import Env.Mdoc qualified as Env
import Mdoc.Gen
import Mdoc.Gen.Man1
import Mdoc.Dump.Env (envParser)
import Mdoc.Dump.Options (optionsInfo, optionsParser)
import Options.Applicative.Mdoc qualified as Opt

mdocDump1 :: Man1
mdocDump1 =
  baseMan1 "mdoc-dump" optionsInfo
    & Opt.addToMan1 optionsParser
    & Env.addToMan1 envParser
    & addCrossRef "mdoc" 7

main :: IO ()
main = putMdoc =<< genMan1 mdocDump1

Pretty-printed `mdoc(7)` syntax

Viewed using `man`

Converted to HTML using `mandoc`

LICENSE

This project is licensed AGPLv3. See COPYING.