mandate 0.1.0

Convert Markdown or YAML manuals into roff manpages
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# mandate

Mandate converts Markdown or YAML-with-Markdown into roff manpages. Think of it as a small
translator that speaks both CommonMark and `man`, with just enough schema validation to keep
things civil.

## Contents

<!-- toc -->

* [Features](#features)
* [Installation](#installation)
* [Quick start](#quick-start)
* [Usage](#usage)
* [CLI flags](#cli-flags)
* [Documentation](#documentation)
* [Project status](#project-status)
* [Development](#development)
* [Contributing](#contributing)
* [License](#license)

<!-- tocstop -->


## Features

- Converts Markdown or YAML-with-Markdown into roff.
- Optional schema validation for YAML manuals.
- Works with stdin for pipeline-friendly workflows.
- Tries hard to stay boring (the highest compliment for tooling).

## Installation

Prebuilt binaries:

```sh
brew install claylo/brew/mandate
```

```sh
cargo binstall mandate
```

From a local checkout:

```sh
cargo install --path .
```

Or run without installing:

```sh
cargo run -- --help
```

## Quick start

```sh
# Markdown in, roff out
mandate -i README.md -p mandate -s 1 -t "Mandate Manual"

# YAML in, roff out
mandate -i docs/mandate.yml -p mandate -s 1 -t "Mandate Manual"

# stdin if you're feeling bold (or piping)
echo '# mytool(1) -- Example tool' | mandate -i - -p mytool -s 1 -t "Mytool Manual"
```

## Usage

```text
mandate -i <input> -p <program> -s <section> -t <title> [options]
```

Notes:

- `manual.md`/`manual.markdown` → Markdown input.
- `manual.yml`/`manual.yaml` → YAML input.
- `-` reads from stdin and auto-detects format.
- `--validate` checks YAML against the embedded schema (or `--schema` override).

## CLI flags

- `-i, --input` path to `manual.yml` or `manual.md` (use `-` for stdin)
- `-p, --program` program name
- `-s, --section` man section (default: `1`)
- `-t, --title` manpage title
- `-m, --manual-section` manual section label (optional)
- `--source` source string (optional)
- `-o, --output` output file path (default: stdout)
- `--validate` validate YAML input against the built-in schema
- `--schema` path to an alternate schema to use with `--validate`

## Documentation

- Manpage source: `docs/mandate.yml`
- Decisions: `docs/decisions/`
- Changelog: `CHANGELOG.md`
- Plan/Roadmap: `PLAN.md`

## Project status

`mandate` is pre-1.0. Expect the occasional sharp edge, but nothing a comment and a sigh
can’t smooth out.

## Development

Validation:

```sh
just check
just test
just cov
```

Build the manpage used by releases:

```sh
cargo run --bin mandate -- -i docs/mandate.yml -p mandate -s 1 -t "Mandate Manual" -o target/man/mandate.1
```

## Contributing

Open a PR with a clear intent and keep changes focused. If you touch behavior, add tests in the
same change. (Future you will say thanks, and present you can pretend this was inevitable.)

## License

Licensed under either of:

- Apache License, Version 2.0 (`LICENSE-APACHE`)
- MIT license (`LICENSE-MIT`)

at your option.