Predoc

Predoc is a Markdown flavour specifically designed for writing man pages.

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 Janet programming language. It includes a command-line utility, predoc, which converts a Predoc document into a man page written in mdoc.

You can try out Predoc in your browser on the project homepage.

Example

Predoc allows you to take this:

---
Title: PREDOC(1)
Authors: Michael Camilleri <[email protected]>
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:

• FreeBSD 14 (x86-64 and aarch64)
• 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 Janet installed on your system. Then you can run:

$ git clone https://github.com/pyrmont/predoc
$ cd predoc
$ git tag --sort=creatordate
$ git checkout <version>
$ janet -e '(import ./bundle) (bundle/build (table :info (-> (slurp "info.jdn") parse)))'

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 predoc /usr/local/bin/
$ sudo cp predoc.1 /usr/local/share/man/man1/
$ sudo cp predoc.7 /usr/local/share/man/man7/

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

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

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.