roff 0.6.0

Description:

roff 0.6.0

roff
python-based cli to convert markdown to the roff (man-pages) format



roff

Installation
Usage/Execution
File Format
Example




Installation


pip install roff
pip install roff[images] # support for images
pip install roff[images-svg] # support for svg-images
pip install roff[watch] # support for rendering and auto-reloading a manpage while writing


[!TIP]
After the installation you should be able to see roff's manpage with man roff
or the file format information with man roff.5.

Usage/Execution
For the common usage you can create a template markdown file with the roff template subcommand and then convert it to the roff-file-format with roff convert
roff --help
roff template command.1.md
roff convert command.1.md
man ./command.1

Additionally, if roff[watch] was installed, you can run roff watch to see the rendered file that automatically re-renders if the file-content changes.
# shell 1
$ roff watch command.1.md
# shell 2
$ nano command.1.md
$ vim command.1.md

Additionally, if your project uses python argparse.ArgumentParser then you can start quicker by using the roff from-parser command instead of roff template.
This works almost like the template command. But fills most of the fields.
$ roff from-parser --root src/ --output prog.1.md myprog.__main__:parser

File Format
roff uses markdown as the file format. It supports all commonmark markdown features (h1 is reserved for the head).
Additionally, roff brings 1 own markdown-feature, the inline-command!
By prepending your inline-code with a $ sign it gets recognised as an inline-command and rendered in a more special way.
$`command subcommand [--arg value] file...`



[!TIP]
Use roff template command.1.md to get a pre-filled markdown file as a starting point.

Example
The following image shows the manpage of roff itself.
(The manpage-content is slightly outdated but still shows what roff can do)