Hackage :: [Package]

mdoc: Parser and pretty-printer for the mdoc(7) language

[ agpl, library, program, text ] [ Propose Tags ] [ Report a vulnerability ]

This library parses, represents, pretty-prints, or generates man-page content using the mdoc(7) language.

To parse a man-page and work with its data in a structured way,

To pretty-print parsed (or constructed) man-page data,

  • Use prettyMdoc and putMdoc from the Mdoc module

To generate a man-page from a supported parser library, check the appropriate integration module,

An example and screenshots can be seen at the project homepage.

[Skip to Readme]

Modules

[Last Documentation]

  • Autodocodec
    • Schema
      • Autodocodec.Schema.Mdoc
  • Env
    • Env.Mdoc
  • Mdoc
    • Data
      • Mdoc.Data.Argument
      • Mdoc.Data.Config
      • Mdoc.Data.Described
      • Mdoc.Data.EnvVar
      • Mdoc.Data.Flag
      • Mdoc.Data.List
      • Mdoc.Data.Named
      • Mdoc.Data.Option
      • Mdoc.Data.Optionality
      • Mdoc.Data.Page
      • Mdoc.Data.Positional
      • Mdoc.Data.Synopsis
    • Mdoc.Detect
    • Dump
      • Mdoc.Dump.Diff
      • Mdoc.Dump.Env
      • Mdoc.Dump.Main
      • Mdoc.Dump.Options
    • Examples
      • Mdoc.Examples.Grep
      • Mdoc.Examples.OptEnvConf
      • Mdoc.Examples.Person
    • Mdoc.Input
    • Mdoc.Optics
    • Mdoc.Parse
      • Mdoc.Parse.MacroArg
      • Mdoc.Parse.MacroName
      • Mdoc.Parse.Mdoc
      • Mdoc.Parse.MdocLine
      • Mdoc.Parse.TableLine
      • Mdoc.Parse.TroffMacro
    • Mdoc.Prelude
    • Mdoc.Pretty
    • Mdoc.Syntax
      • Mdoc.Syntax.MacroArg
      • Mdoc.Syntax.MacroName
      • Mdoc.Syntax.Mdoc
      • Mdoc.Syntax.MdocLine
      • Mdoc.Syntax.TableLine
      • Mdoc.Syntax.TroffMacro
    • Mdoc.Template
    • Mdoc.UpdateMdocdate
  • OptEnvConf
    • OptEnvConf.Mdoc
  • Options
    • Applicative
      • Options.Applicative.Mdoc

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3, 0.1.1.0, 0.1.1.1, 0.1.1.2, 0.1.1.3, 0.1.1.4, 0.2.0.0
Change log CHANGELOG.md
Dependencies aeson (>=2.2.3.0), autodocodec (>=0.4.2.2 && <0.6), autodocodec-schema (>=0.2.0.1 && <0.2.0.2), base (>=4.19.2.0 && <5), bytestring (>=0.12.1.0), containers (>=0.6.8), Diff (>=0.5), envparse (>=0.6.0), extra (>=1.7.16), file-embed (>=0.0.16.0), filepath (>=1.4.301.0), generic-optics (>=2.2.1.0), mdoc, megaparsec (>=9.6.1), mtl (>=2.3.1), opt-env-conf (>=0.8.0.0), optics (>=0.4.2.1), optparse-applicative (>=0.18.1.0), prettyprinter (>=1.7.2), prettyprinter-ansi-terminal (>=1.1.3), stache (>=2.3.4), text (>=2.1.1), time (>=1.12.2), zlib (>=0.7.1.0) [details]
License AGPL-3.0-only
Author
Maintainer Pat Brisbin
Uploaded by PatrickBrisbin at 2026-10-01T20:48:17Z
Category Text
Home page https://codeberg.org/pbrisbin/mdoc#readme
Bug tracker https://codeberg.org/pbrisbin/mdoc/issues
Source repo head: git clone https://codeberg.org/pbrisbin/mdoc
Distributions
Executables mdoc-dump
Downloads 27 total (27 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2026-10-01 [all 2 reports]

Readme for mdoc-0.2.0.0

[back to package description]

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:

module Main
  ( main
  ) where

import Prelude

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

mdocDump1 :: Named
mdocDump1 =
  mempty
    & (<> Opt.getPage optionsParser)
    & (<> Env.getPage envParser)
    & setEpilogue
      ( Mdoc
        [ MacroLine Sh ["SEE ALSO"]
        , MacroLine Xr ["mdoc", "7"]
        ]
      )
    & name "mdoc-dump" optionsInfo

main :: IO ()
main = do
  mdoc <- renderTemplateThrow man1 mdocDump1
  putMdoc =<< updateMdocdate mdoc
Pretty-printed `mdoc(7)` syntax

Viewed using `man`

Converted to HTML using `mandoc`

LICENSE

This project is licensed AGPLv3. See COPYING.