python-based cli to convert markdown to the roff (man-pages) format
Project description
roff
python-based cli to convert markdown to the roff (man-pages) format
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 withman 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)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.