mdoc-0.2.0.0: README.lhs

# mdoc

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

[mdoc.7]: https://mandoc.bsd.lv/man/mdoc.7.html

## 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)`][mdoc-dump.1]. This
`README` is a Literate Haskell file that generates a man-page from its
`optparse-applicative` and `envparse` parsers:

[mdoc-dump.1]: ./examples/mdoc-dump.1

```haskell
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
```

<details>
<summary>Pretty-printed `mdoc(7)` syntax</summary>

![](./files/mdoc-dump-pretty.png)

</details>

<details>
<summary>Viewed using `man`</summary>

![](./files/mdoc-dump-man.png)

</details>

<details>
<summary>Converted to HTML using `mandoc`</summary>

![](./files/mdoc-dump-html.png)

</details>

## LICENSE

This project is licensed AGPLv3. See [COPYING](./COPYING).