The Predoc language is a Markdown flavour for writing manpages.
Using Predoc, you can quickly and easily add documentation to your project. Your users can then consult this documentation in the comfort of their own terminal using standard tools like man.
Try Predoc in your web browser now with live preview.
The reference implementation for Predoc is written in the Janet programming language. Janet is a Lisp that comes with a powerful PEG (parser expression grammar) engine as part of the runtime.
The reference implementation includes a single-binary command-line utility that you can use to convert Predoc into mdoc. Pre-built binaries are available for FreeBSD, Linux and macOS from the repository on GitHub.
Markdown is a lightweight markup language that optimises for ease-of-reading and ease-of-writing. As explained on the Markdown project website:
Readability is emphasised above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
Predoc shares this philosophy. Its syntax is comprised of punctuation characters. As much as possible, the punctuation characters are chosen to look like what they mean. Headings look like headings, emphasis looks like emphasis, lists look like lists and so on.
Markdown assumes that it will be converted to HTML. Predoc assumes that it will be converted to mdoc. In the same way that Markdown is not a replacement for HTML, predoc is not a replacement for mdoc. John Gruber, the creator of Markdown, makes a distinction between HTML as a publishing format and Markdown as a writing format. Predoc makes this same distinction: mdoc is a publishing format and predoc is a writing format.
Predoc’s syntax is a reduced and modified set of Markdown’s
syntax.The Predoc syntax is more fully described in the predoc(7)
manpage.
To give you an idea, here are a couple of syntactic elements that make writing manpages in Predoc such a nice experience:
A command is denoted by ** on either side of text.
Load the **jump** program.Commands are intended to be used for internal or interactive commands
associated with the subject of the manpage. For strong text, use
__ instead.
When rendered to mdoc, a command usually produces an internal command
using the Ic macro. The exception to this is when a name is
provided to the rendering function. In this case, a command produces the
name of the manpage using the Nm macro.
An option is denoted by ** on either side of text. The
option name must begin with -. Long options begin with
--.
If flying is enabled, use **-f** or **--fly**.Options are intended to be used for what mdoc calls command-line
flags or command-line options. For strong text, use __
instead.
When rendered to mdoc, an option produces a command option using the
Op macro.
A tagged list is denoted by a - at the start of the
first line, a : at the end of the first line and then a
body beginning on the second line.
- **Dojo**:
A place for sparring.
- **Street**:
A place for concentration.A tagged list is a list of tag/body pairs. Tagged lists are used idiomatically in manpages for argument lists but can be used for other content.
When rendered to mdoc, a tagged list produces a tagged list using the
Bl macro with the arguments -tag and
-width Ds. If the list is ‘tight’ (i.e., there are no blank
lines between elements), the arguments also include
-compact.
Predoc is open source and licensed under the MIT Licence. More information is available from the repository on GitHub.