Metadata-Version: 2.2
Name: roff
Version: 0.7.0
Summary: python-based cli to convert markdown to the roff (man-pages) format
Home-page: https://github.com/utility-toolbox/roff
Author: PlayerG9
License: MIT
Project-URL: Organisation Github, https://github.com/utility-toolbox
Project-URL: Homepage, https://github.com/utility-toolbox/roff/
Project-URL: Bug Tracker, https://github.com/utility-toolbox/roff/issues
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py
Provides-Extra: front-matter
Requires-Dist: pyyaml; extra == "front-matter"
Provides-Extra: images
Requires-Dist: pillow; extra == "images"
Provides-Extra: images-svg
Requires-Dist: pillow; extra == "images-svg"
Requires-Dist: cairosvg; extra == "images-svg"
Provides-Extra: watch
Requires-Dist: pypager; extra == "watch"
Provides-Extra: all
Requires-Dist: pyyaml; extra == "all"
Requires-Dist: pillow; extra == "all"
Requires-Dist: pillow; extra == "all"
Requires-Dist: cairosvg; extra == "all"
Requires-Dist: pypager; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

![roff-manpage head](https://github.com/utility-toolbox/roff/blob/main/README.assets/roff-manpage-head.png?raw=true)

<!-- TOC -->
* [roff](#roff)
  * [Installation](#installation)
  * [Usage/Execution](#usageexecution)
  * [File Format](#file-format)
  * [Example](#example)
<!-- TOC -->

## Installation

[![PyPI - Version](https://img.shields.io/pypi/v/roff)
](https://pypi.org/project/roff/)

```shell
pip install roff
pip install roff[front-matter]  # support for front-matter to configure 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](https://github.com/utility-toolbox/roff/blob/main/docs/roff.1.md) 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`

```shell
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
# 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.

```shell
$ 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.

```markdown
$`command subcommand [--arg value] file...`
```

![example: inline-command](README.assets/example-inline-command.png)

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

## Configuration

## Example

The following image shows the manpage of roff itself.

<small>(The manpage-content is slightly outdated but still shows what roff can do)</small>

![example: manpage](https://github.com/utility-toolbox/roff/blob/main/README.assets/roff-manpage.png?raw=true)
