Skip to content

Commit 8b878f3

Browse files
ehussehuss
committed
Add mdman for generating man pages.
1 parent 2d5c238 commit 8b878f3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+3735
-0
lines changed

‎crates/mdman/Cargo.lock

Lines changed: 449 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crates/mdman/Cargo.toml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[package]
2+
name = "mdman"
3+
version = "0.1.0"
4+
authors = ["Eric Huss"]
5+
edition = "2018"
6+
license = "MIT OR Apache-2.0"
7+
description = "Creates a man page page from markdown."
8+
9+
[dependencies]
10+
anyhow = "1.0.31"
11+
handlebars = { version = "3.2.1", features = ["dir_source"] }
12+
pulldown-cmark = { version = "0.7.2", default-features = false }
13+
same-file = "1.0.6"
14+
serde_json = "1.0.56"
15+
url = "2.1.1"
16+
17+
[dev-dependencies]
18+
pretty_assertions = "0.6.1"

‎crates/mdman/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# mdman
2+
3+
mdman is a small utility for creating man pages from markdown text files.
4+
5+
## Usage
6+
7+
See the [man page](doc/out/mdman.md) generated by this tool.

‎crates/mdman/build-man.sh

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
cargo run -- -t md -o doc/out doc/*.md
6+
cargo run -- -t txt -o doc/out doc/*.md
7+
cargo run -- -t man -o doc/out doc/*.md

‎crates/mdman/doc/mdman.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# mdman(1)
2+
3+
## NAME
4+
5+
mdman - Converts markdown to a man page
6+
7+
## SYNOPSIS
8+
9+
`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._
10+
11+
## DESCRIPTION
12+
13+
Converts a markdown file to a man page.
14+
15+
The source file is first processed as a
16+
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
17+
markdown into the target format. This supports different output formats,
18+
such as troff or plain text.
19+
20+
Every man page should start with a level-1 header with the man name and
21+
section, such as `# mdman(1)`.
22+
23+
The handlebars template has several special tags to assist with generating the
24+
man page:
25+
26+
{{{{raw}}}}
27+
- Every block of command-line options must be wrapped between `{{#options}}`
28+
and `{{/options}}` tags. This tells the processor where the options start
29+
and end.
30+
- Each option must be expressed with a `{{#option}}` block. The parameters to
31+
the the block are a sequence of strings indicating the option. For example,
32+
```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
33+
has two different forms. The text within the string is processed as markdown.
34+
It is recommended to use formatting similar to this example.
35+
36+
The content of the `{{#option}}` block should contain a detailed description
37+
of the option.
38+
39+
Use the `{{/option}}` tag to end the option block.
40+
- References to other man pages should use the `{{man name section}}`
41+
expression. For example, `{{man "mdman" 1}}` will generate a reference to
42+
the `mdman(1)` man page. For non-troff output, the `--man` option will tell
43+
`mdman` how to create links to the man page. If there is no matching `--man`
44+
option, then it links to a file named _name_`.md` in the same directory.
45+
- Variables can be set with `{{*set name="value"}}`. These variables can
46+
then be referenced with `{{name}}` expressions.
47+
- Partial templates should be placed in a directory named `includes`
48+
next to the source file. Templates can be included with an expression like
49+
`{{> template-name}}`.
50+
- Other helpers include:
51+
- `{{lower value}}` Converts the given value to lowercase.
52+
{{{{/raw}}}}
53+
54+
## OPTIONS
55+
56+
{{#options}}
57+
58+
{{#option "`-t` _type_"}}
59+
Specifies the output type. The following output types are supported:
60+
- `man` — A troff-style man page. Outputs with a numbered extension (like
61+
`.1`) matching the man page section.
62+
- `md` — A markdown file, after all handlebars processing has been finished.
63+
Outputs with the `.md` extension.
64+
- `txt` — A text file, rendered for situations where a man page viewer isn't
65+
available. Outputs with the `.txt` extension.
66+
{{/option}}
67+
68+
{{#option "`-o` _outdir_"}}
69+
Specifies the directory where to save the output.
70+
{{/option}}
71+
72+
{{#option "`--url` _base_url_"}}
73+
Specifies a base URL to use for relative URLs within the document. Any
74+
relative URL will be joined with this URL.
75+
{{/option}}
76+
77+
{{#option "`--man` _name_`:`_section_`=`_url_"}}
78+
Specifies a URL to use for the given man page. When the `\{{man name
79+
section}}` expression is used, the given URL will be inserted as a link. This
80+
may be specified multiple times. If a man page reference does not have a
81+
matching `--man` entry, then a relative link to a file named _name_`.md` will
82+
be used.
83+
{{/option}}
84+
85+
{{#option "_sources..._"}}
86+
The source input filename, may be specified multiple times.
87+
{{/option}}
88+
89+
{{/options}}
90+
91+
## EXAMPLES
92+
93+
1. Convert the given documents to man pages:
94+
95+
mdman -t man -o doc doc/mdman.md

‎crates/mdman/doc/out/mdman.1

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
'\" t
2+
.TH "MDMAN" "1"
3+
.nh
4+
.ad l
5+
.ss \n[.ss] 0
6+
.SH "NAME"
7+
mdman \- Converts markdown to a man page
8+
.SH "SYNOPSIS"
9+
\fBmdman\fR [\fIoptions\fR] \fB\-t\fR \fItype\fR \fB\-o\fR \fIoutdir\fR \fIsources...\fR
10+
.SH "DESCRIPTION"
11+
Converts a markdown file to a man page.
12+
.sp
13+
The source file is first processed as a
14+
\fIhandlebars\fR <https://handlebarsjs.com/> template. Then, it is processed as
15+
markdown into the target format. This supports different output formats,
16+
such as troff or plain text.
17+
.sp
18+
Every man page should start with a level\-1 header with the man name and
19+
section, such as \fB# mdman(1)\fR\&.
20+
.sp
21+
The handlebars template has several special tags to assist with generating the
22+
man page:
23+
.sp
24+
.RS 4
25+
\h'-04'\(bu\h'+02'Every block of command\-line options must be wrapped between \fB{{#options}}\fR
26+
and \fB{{/options}}\fR tags. This tells the processor where the options start
27+
and end.
28+
.RE
29+
.sp
30+
.RS 4
31+
\h'-04'\(bu\h'+02'Each option must be expressed with a \fB{{#option}}\fR block. The parameters to
32+
the the block are a sequence of strings indicating the option. For example,
33+
\fB{{#option "`\-p` _spec_..." "`\-\-package` _spec_..."}}\fR is an option that
34+
has two different forms. The text within the string is processed as markdown.
35+
It is recommended to use formatting similar to this example.
36+
.sp
37+
The content of the \fB{{#option}}\fR block should contain a detailed description
38+
of the option.
39+
.sp
40+
Use the \fB{{/option}}\fR tag to end the option block.
41+
.RE
42+
.sp
43+
.RS 4
44+
\h'-04'\(bu\h'+02'References to other man pages should use the \fB{{man name section}}\fR
45+
expression. For example, \fB{{man "mdman" 1}}\fR will generate a reference to
46+
the \fBmdman(1)\fR man page. For non\-troff output, the \fB\-\-man\fR option will tell
47+
\fBmdman\fR how to create links to the man page. If there is no matching \fB\-\-man\fR
48+
option, then it links to a file named \fIname\fR\fB\&.md\fR in the same directory.
49+
.RE
50+
.sp
51+
.RS 4
52+
\h'-04'\(bu\h'+02'Variables can be set with \fB{{*set name="value"}}\fR\&. These variables can
53+
then be referenced with \fB{{name}}\fR expressions.
54+
.RE
55+
.sp
56+
.RS 4
57+
\h'-04'\(bu\h'+02'Partial templates should be placed in a directory named \fBincludes\fR
58+
next to the source file. Templates can be included with an expression like
59+
\fB{{> template\-name}}\fR\&.
60+
.RE
61+
.sp
62+
.RS 4
63+
\h'-04'\(bu\h'+02'Other helpers include:
64+
.sp
65+
.RS 4
66+
\h'-04'\(bu\h'+02'\fB{{lower value}}\fR Converts the given value to lowercase.
67+
.RE
68+
.RE
69+
.SH "OPTIONS"
70+
.sp
71+
\fB\-t\fR \fItype\fR
72+
.RS 4
73+
Specifies the output type. The following output types are supported:
74+
.sp
75+
.RS 4
76+
\h'-04'\(bu\h'+02'\fBman\fR \[em]\ A troff\-style man page. Outputs with a numbered extension (like
77+
\fB\&.1\fR) matching the man page section.
78+
.RE
79+
.sp
80+
.RS 4
81+
\h'-04'\(bu\h'+02'\fBmd\fR \[em]\ A markdown file, after all handlebars processing has been finished.
82+
Outputs with the \fB\&.md\fR extension.
83+
.RE
84+
.sp
85+
.RS 4
86+
\h'-04'\(bu\h'+02'\fBtxt\fR \[em]\ A text file, rendered for situations where a man page viewer isn't
87+
available. Outputs with the \fB\&.txt\fR extension.
88+
.RE
89+
.RE
90+
.sp
91+
\fB\-o\fR \fIoutdir\fR
92+
.RS 4
93+
Specifies the directory where to save the output.
94+
.RE
95+
.sp
96+
\fB\-\-url\fR \fIbase_url\fR
97+
.RS 4
98+
Specifies a base URL to use for relative URLs within the document. Any
99+
relative URL will be joined with this URL.
100+
.RE
101+
.sp
102+
\fB\-\-man\fR \fIname\fR\fB:\fR\fIsection\fR\fB=\fR\fIurl\fR
103+
.RS 4
104+
Specifies a URL to use for the given man page. When the \fB{{man name section}}\fR expression is used, the given URL will be inserted as a link. This
105+
may be specified multiple times. If a man page reference does not have a
106+
matching \fB\-\-man\fR entry, then a relative link to a file named \fIname\fR\fB\&.md\fR will
107+
be used.
108+
.RE
109+
.sp
110+
\fIsources...\fR
111+
.RS 4
112+
The source input filename, may be specified multiple times.
113+
.RE
114+
.SH "EXAMPLES"
115+
.sp
116+
.RS 4
117+
\h'-04' 1.\h'+01'Convert the given documents to man pages:
118+
.sp
119+
.RS 4
120+
.nf
121+
mdman \-t man \-o doc doc/mdman.md
122+
.fi
123+
.RE
124+
.RE

‎crates/mdman/doc/out/mdman.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# mdman(1)
2+
3+
## NAME
4+
5+
mdman - Converts markdown to a man page
6+
7+
## SYNOPSIS
8+
9+
`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._
10+
11+
## DESCRIPTION
12+
13+
Converts a markdown file to a man page.
14+
15+
The source file is first processed as a
16+
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
17+
markdown into the target format. This supports different output formats,
18+
such as troff or plain text.
19+
20+
Every man page should start with a level-1 header with the man name and
21+
section, such as `# mdman(1)`.
22+
23+
The handlebars template has several special tags to assist with generating the
24+
man page:
25+
26+
- Every block of command-line options must be wrapped between `{{#options}}`
27+
and `{{/options}}` tags. This tells the processor where the options start
28+
and end.
29+
- Each option must be expressed with a `{{#option}}` block. The parameters to
30+
the the block are a sequence of strings indicating the option. For example,
31+
```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
32+
has two different forms. The text within the string is processed as markdown.
33+
It is recommended to use formatting similar to this example.
34+
35+
The content of the `{{#option}}` block should contain a detailed description
36+
of the option.
37+
38+
Use the `{{/option}}` tag to end the option block.
39+
- References to other man pages should use the `{{man name section}}`
40+
expression. For example, `{{man "mdman" 1}}` will generate a reference to
41+
the `mdman(1)` man page. For non-troff output, the `--man` option will tell
42+
`mdman` how to create links to the man page. If there is no matching `--man`
43+
option, then it links to a file named _name_`.md` in the same directory.
44+
- Variables can be set with `{{*set name="value"}}`. These variables can
45+
then be referenced with `{{name}}` expressions.
46+
- Partial templates should be placed in a directory named `includes`
47+
next to the source file. Templates can be included with an expression like
48+
`{{> template-name}}`.
49+
- Other helpers include:
50+
- `{{lower value}}` Converts the given value to lowercase.
51+
52+
53+
## OPTIONS
54+
55+
<dl>
56+
57+
<dt><code>-t</code> <em>type</em></dt>
58+
<dd>Specifies the output type. The following output types are supported:</p>
59+
<ul>
60+
<li><code>man</code> — A troff-style man page. Outputs with a numbered extension (like
61+
<code>.1</code>) matching the man page section.</li>
62+
<li><code>md</code> — A markdown file, after all handlebars processing has been finished.
63+
Outputs with the <code>.md</code> extension.</li>
64+
<li><code>txt</code> — A text file, rendered for situations where a man page viewer isn't
65+
available. Outputs with the <code>.txt</code> extension.</li>
66+
</ul></dd>
67+
68+
69+
<dt><code>-o</code> <em>outdir</em></dt>
70+
<dd>Specifies the directory where to save the output.</dd>
71+
72+
73+
<dt><code>--url</code> <em>base_url</em></dt>
74+
<dd>Specifies a base URL to use for relative URLs within the document. Any
75+
relative URL will be joined with this URL.</dd>
76+
77+
78+
<dt><code>--man</code> <em>name</em><code>:</code><em>section</em><code>=</code><em>url</em></dt>
79+
<dd>Specifies a URL to use for the given man page. When the <code>{{man name section}}</code> expression is used, the given URL will be inserted as a link. This
80+
may be specified multiple times. If a man page reference does not have a
81+
matching <code>--man</code> entry, then a relative link to a file named <em>name</em><code>.md</code> will
82+
be used.</dd>
83+
84+
85+
<dt><em>sources...</em></dt>
86+
<dd>The source input filename, may be specified multiple times.</dd>
87+
88+
89+
</dl>
90+
91+
## EXAMPLES
92+
93+
1. Convert the given documents to man pages:
94+
95+
mdman -t man -o doc doc/mdman.md

0 commit comments

Comments
 (0)