Predoc

Predoc is a Markdown flavour specifically designed for writing man pages. You can see Predoc in your browser on the project homepage.

Warning

Predoc is in a beta stage of development. There are likely to be bugs and gaps in its implementation.

This is the repository for the reference implementation of the parser and renderer written in the Wattle programming language. It provides a command-line utility, predoc, which converts a Predoc document into a man page written in mdoc.

Example

Predoc allows you to take this:

---
Title: PREDOC(1)
Authors: Michael Camilleri <mike@inqk.net>
Date: September 13, 2025
Project: Predoc
Version: DEVEL
---

NAME
====

**predoc** - converter from Predoc to mdoc

SYNOPSIS
========

**predoc** [**--format** _fmt_] [**--name** _program_] [**--no-ad**]
           [**--output** _path_] _input_

DESCRIPTION
===========

**predoc** is a command-line tool for converting documents written in
`predoc(7)` to man pages written in `mdoc(7)`.

and convert it to this:

.\"
.\" Generated by predoc at 2025-09-19T02:26:42Z
.\"
.Dd September 13, 2025
.Dt PREDOC 1
.Os Predoc DEVEL
.
.Sh NAME
.Nm predoc
.Nd converter from Predoc to mdoc
.
.Sh SYNOPSIS
.Nm
.Oo
.Fl -format
.Ar fmt
.Oc
.Oo
.Fl -name
.Ar program
.Oc
.Oo
.Fl -no-ad
.Oc
.Oo
.Fl -output
.Ar path
.Oc
.Ar input
.
.Sh DESCRIPTION
.Nm
is a command-line tool for converting documents written in
.Xr predoc 7
to man pages written in
.Xr mdoc 7 .

which in turn is rendered by man into this:

Language

Rationale

Documentation is great and man pages can be a wonderful source of information. But people are discouraged from creating or updating man pages because the syntax of mdoc and roff (the markup languages used for these documents) is intimidating.

Predoc aims to remedy this. Markdown allows a person to create HTML that 'looks like' what they wrote. Predoc wants to do the same thing for man pages: create mdoc that 'looks like' what is written in plain text.

Syntax

Like Markdown, Predoc is a lightweight markup language that optimises for ease-of-reading and ease-of-writing. It does this by specifying its syntactic constructs using punctuation characters.

More information about the Predoc language is in predoc(7). You can (hopefully) see the benefit of writing man pages in Predoc by reading the Predoc version directly.

CLI Utility

Building

Pre-Built

Pre-built binaries of predoc are available as tarballs via the Releases section on GitHub for:

• Linux (x86-64 and aarch64)
• macOS (aarch64)

$ curl -LO https://github.com/pyrmont/predoc/releases/latest/download/predoc-<version>-<platform>-<arch>.tar.gz
$ tar -xzf predoc-<version>-<platform>-<arch>.tar.gz
$ cd predoc-<version>

From Source

To build the predoc binary from source, you need Zig 0.17.0 and Wattle 0.2.0 or later installed on your system. Then you can run:

$ git clone https://github.com/pyrmont/predoc
$ cd predoc
$ git tag --sort=creatordate
$ git checkout <version>
$ wattle build exe --release fast

The executable is zig-out/bin/predoc. It includes the Wattle runtime and does not require a separate Wattle installation to run.

To run the tests, use wattle test from the root of the project.

Installing

Move the predoc binary somewhere on your path and predoc.1 and predoc.7 to the appropriate man page locations. For example:

# use sudo or doas depending on the permissions of the target directories
$ sudo cp zig-out/bin/predoc /usr/local/bin/
$ sudo cp predoc.1 /usr/local/share/man/man1/
$ sudo cp predoc.7 /usr/local/share/man/man7/

If you have Wattle installed, you can instead build and install predoc and its man pages under your WATTLE_PREFIX in one step:

$ wattle apps install https://github.com/pyrmont/predoc

The predoc binary is placed in the prefix's bin/ directory and the man pages in share/man/. Run wattle apps upgrade predoc to reinstall it from the repository and wattle apps remove predoc to remove it.

Using

To convert a Predoc document called example.1.predoc into the man page example.1 for the program example, you can write:

$ predoc example.1.predoc

If only the input filename is given, predoc will use this to derive the program name and the output filename. To specify these values explicitly, you can write:

$ predoc --name example --output example.1 example.1.predoc

As well as mdoc, predoc can convert a document to HTML. By default, the html format produces a fragment suitable for embedding in an existing page. If you pass --css, the output is instead a complete HTML page that links to a stylesheet and that stylesheet is written to the given path:

$ predoc --format html --css predoc.css example.1.predoc

This writes the page example.1.html and the stylesheet predoc.css. The stylesheet is overwritten each time, so make a copy under a different name if you want to customise it.

More information about predoc is, of course, available in predoc(1).

Browser Demo

The browser demo in pages runs predoc compiled to WebAssembly. A web worker (pages/worker.js) performs the conversions so that typing remains responsive. The program is loaded in pages/predoc/dingus.js once and reuses one instance of the runtime for every conversion. To rebuild the program, run:

$ wattle res/tools/wasm.wattle

This runs wattle build web dingus, replaces the files in pages/predoc and updates the cache reference in pages/index.html. Zig and the Wattle package are needed, as for any build. To check the result without a browser, run the Node.js smoke test:

$ node res/tools/wasm-smoke.mjs

Alternatives

There are alternatives to Predoc. Here are a few:

• lowdown is a simple Markdown translator. It is written in C and compiles to a single binary with no dependencies. It uses Markdown. It produces roff rather than mdoc but can convert to additional formats as well. The syntactic constructs it can produce in the generated man page are fewer than can be produced by Predoc. It is actively maintained.

• Pandoc is the universal document converter. It is written in Haskell and compiles to a single binary with no dependencies. It uses Markdown. It produces roff rather than mdoc but can convert to additional formats as well. The syntactic constructs it can produce in the generated man page are fewer than can be produced by Predoc. It is actively maintained.

• ronn is the opposite of roff. It is written in Ruby and runs as an executable script that requires Ruby. It uses a syntax similar to Markdown. It produces roff rather than mdoc but can also produce HTML. The syntactic constructs it can produce in the generated man page are fewer than can be produced by Predoc. It is not actively maintained. (It does objectively have the best name.)

• scdoc is a simple man page generator. It is written in C and compiles to a single binary with no dependencies. It uses a syntax similar to Markdown. It produces roff rather than mdoc. The syntactic constructs it can produce in the generated man page are fewer than can be produced by Predoc. It is actively maintained.

Versioning

Predoc uses the label DEVEL during development. When a new version is released, a tag is created for that version in the repository.

Bugs

Found a bug? I'd love to know about it. The best way is to report your bug in the Issues section on GitHub.

Licence

Predoc is licensed under the MIT Licence. See LICENSE for more details.