Skip to content

Commit

Permalink
Add mdman for generating man pages.
Browse files Browse the repository at this point in the history
  • Loading branch information
ehuss committed Aug 1, 2020
1 parent 2d5c238 commit 8b878f3
Show file tree
Hide file tree
Showing 41 changed files with 3,735 additions and 0 deletions.
449 changes: 449 additions & 0 deletions crates/mdman/Cargo.lock

Large diffs are not rendered by default.

18 changes: 18 additions & 0 deletions crates/mdman/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
[package]
name = "mdman"
version = "0.1.0"
authors = ["Eric Huss"]
edition = "2018"
license = "MIT OR Apache-2.0"
description = "Creates a man page page from markdown."

[dependencies]
anyhow = "1.0.31"
handlebars = { version = "3.2.1", features = ["dir_source"] }
pulldown-cmark = { version = "0.7.2", default-features = false }
same-file = "1.0.6"
serde_json = "1.0.56"
url = "2.1.1"

[dev-dependencies]
pretty_assertions = "0.6.1"
7 changes: 7 additions & 0 deletions crates/mdman/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# mdman

mdman is a small utility for creating man pages from markdown text files.

## Usage

See the [man page](doc/out/mdman.md) generated by this tool.
7 changes: 7 additions & 0 deletions crates/mdman/build-man.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
#!/bin/bash

set -e

cargo run -- -t md -o doc/out doc/*.md
cargo run -- -t txt -o doc/out doc/*.md
cargo run -- -t man -o doc/out doc/*.md
95 changes: 95 additions & 0 deletions crates/mdman/doc/mdman.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# mdman(1)

## NAME

mdman - Converts markdown to a man page

## SYNOPSIS

`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._

## DESCRIPTION

Converts a markdown file to a man page.

The source file is first processed as a
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
markdown into the target format. This supports different output formats,
such as troff or plain text.

Every man page should start with a level-1 header with the man name and
section, such as `# mdman(1)`.

The handlebars template has several special tags to assist with generating the
man page:

{{{{raw}}}}
- Every block of command-line options must be wrapped between `{{#options}}`
and `{{/options}}` tags. This tells the processor where the options start
and end.
- Each option must be expressed with a `{{#option}}` block. The parameters to
the the block are a sequence of strings indicating the option. For example,
```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
has two different forms. The text within the string is processed as markdown.
It is recommended to use formatting similar to this example.

The content of the `{{#option}}` block should contain a detailed description
of the option.

Use the `{{/option}}` tag to end the option block.
- References to other man pages should use the `{{man name section}}`
expression. For example, `{{man "mdman" 1}}` will generate a reference to
the `mdman(1)` man page. For non-troff output, the `--man` option will tell
`mdman` how to create links to the man page. If there is no matching `--man`
option, then it links to a file named _name_`.md` in the same directory.
- Variables can be set with `{{*set name="value"}}`. These variables can
then be referenced with `{{name}}` expressions.
- Partial templates should be placed in a directory named `includes`
next to the source file. Templates can be included with an expression like
`{{> template-name}}`.
- Other helpers include:
- `{{lower value}}` Converts the given value to lowercase.
{{{{/raw}}}}

## OPTIONS

{{#options}}

{{#option "`-t` _type_"}}
Specifies the output type. The following output types are supported:
- `man` — A troff-style man page. Outputs with a numbered extension (like
`.1`) matching the man page section.
- `md` — A markdown file, after all handlebars processing has been finished.
Outputs with the `.md` extension.
- `txt` — A text file, rendered for situations where a man page viewer isn't
available. Outputs with the `.txt` extension.
{{/option}}

{{#option "`-o` _outdir_"}}
Specifies the directory where to save the output.
{{/option}}

{{#option "`--url` _base_url_"}}
Specifies a base URL to use for relative URLs within the document. Any
relative URL will be joined with this URL.
{{/option}}

{{#option "`--man` _name_`:`_section_`=`_url_"}}
Specifies a URL to use for the given man page. When the `\{{man name
section}}` expression is used, the given URL will be inserted as a link. This
may be specified multiple times. If a man page reference does not have a
matching `--man` entry, then a relative link to a file named _name_`.md` will
be used.
{{/option}}

{{#option "_sources..._"}}
The source input filename, may be specified multiple times.
{{/option}}

{{/options}}

## EXAMPLES

1. Convert the given documents to man pages:

mdman -t man -o doc doc/mdman.md
124 changes: 124 additions & 0 deletions crates/mdman/doc/out/mdman.1
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
'\" t
.TH "MDMAN" "1"
.nh
.ad l
.ss \n[.ss] 0
.SH "NAME"
mdman \- Converts markdown to a man page
.SH "SYNOPSIS"
\fBmdman\fR [\fIoptions\fR] \fB\-t\fR \fItype\fR \fB\-o\fR \fIoutdir\fR \fIsources...\fR
.SH "DESCRIPTION"
Converts a markdown file to a man page.
.sp
The source file is first processed as a
\fIhandlebars\fR <https://handlebarsjs.com/> template. Then, it is processed as
markdown into the target format. This supports different output formats,
such as troff or plain text.
.sp
Every man page should start with a level\-1 header with the man name and
section, such as \fB# mdman(1)\fR\&.
.sp
The handlebars template has several special tags to assist with generating the
man page:
.sp
.RS 4
\h'-04'\(bu\h'+02'Every block of command\-line options must be wrapped between \fB{{#options}}\fR
and \fB{{/options}}\fR tags. This tells the processor where the options start
and end.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Each option must be expressed with a \fB{{#option}}\fR block. The parameters to
the the block are a sequence of strings indicating the option. For example,
\fB{{#option "`\-p` _spec_..." "`\-\-package` _spec_..."}}\fR is an option that
has two different forms. The text within the string is processed as markdown.
It is recommended to use formatting similar to this example.
.sp
The content of the \fB{{#option}}\fR block should contain a detailed description
of the option.
.sp
Use the \fB{{/option}}\fR tag to end the option block.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'References to other man pages should use the \fB{{man name section}}\fR
expression. For example, \fB{{man "mdman" 1}}\fR will generate a reference to
the \fBmdman(1)\fR man page. For non\-troff output, the \fB\-\-man\fR option will tell
\fBmdman\fR how to create links to the man page. If there is no matching \fB\-\-man\fR
option, then it links to a file named \fIname\fR\fB\&.md\fR in the same directory.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Variables can be set with \fB{{*set name="value"}}\fR\&. These variables can
then be referenced with \fB{{name}}\fR expressions.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Partial templates should be placed in a directory named \fBincludes\fR
next to the source file. Templates can be included with an expression like
\fB{{> template\-name}}\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Other helpers include:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fB{{lower value}}\fR Converts the given value to lowercase.
.RE
.RE
.SH "OPTIONS"
.sp
\fB\-t\fR \fItype\fR
.RS 4
Specifies the output type. The following output types are supported:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBman\fR \[em]\ A troff\-style man page. Outputs with a numbered extension (like
\fB\&.1\fR) matching the man page section.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBmd\fR \[em]\ A markdown file, after all handlebars processing has been finished.
Outputs with the \fB\&.md\fR extension.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBtxt\fR \[em]\ A text file, rendered for situations where a man page viewer isn't
available. Outputs with the \fB\&.txt\fR extension.
.RE
.RE
.sp
\fB\-o\fR \fIoutdir\fR
.RS 4
Specifies the directory where to save the output.
.RE
.sp
\fB\-\-url\fR \fIbase_url\fR
.RS 4
Specifies a base URL to use for relative URLs within the document. Any
relative URL will be joined with this URL.
.RE
.sp
\fB\-\-man\fR \fIname\fR\fB:\fR\fIsection\fR\fB=\fR\fIurl\fR
.RS 4
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
may be specified multiple times. If a man page reference does not have a
matching \fB\-\-man\fR entry, then a relative link to a file named \fIname\fR\fB\&.md\fR will
be used.
.RE
.sp
\fIsources...\fR
.RS 4
The source input filename, may be specified multiple times.
.RE
.SH "EXAMPLES"
.sp
.RS 4
\h'-04' 1.\h'+01'Convert the given documents to man pages:
.sp
.RS 4
.nf
mdman \-t man \-o doc doc/mdman.md
.fi
.RE
.RE
95 changes: 95 additions & 0 deletions crates/mdman/doc/out/mdman.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# mdman(1)

## NAME

mdman - Converts markdown to a man page

## SYNOPSIS

`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._

## DESCRIPTION

Converts a markdown file to a man page.

The source file is first processed as a
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
markdown into the target format. This supports different output formats,
such as troff or plain text.

Every man page should start with a level-1 header with the man name and
section, such as `# mdman(1)`.

The handlebars template has several special tags to assist with generating the
man page:

- Every block of command-line options must be wrapped between `{{#options}}`
and `{{/options}}` tags. This tells the processor where the options start
and end.
- Each option must be expressed with a `{{#option}}` block. The parameters to
the the block are a sequence of strings indicating the option. For example,
```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
has two different forms. The text within the string is processed as markdown.
It is recommended to use formatting similar to this example.

The content of the `{{#option}}` block should contain a detailed description
of the option.

Use the `{{/option}}` tag to end the option block.
- References to other man pages should use the `{{man name section}}`
expression. For example, `{{man "mdman" 1}}` will generate a reference to
the `mdman(1)` man page. For non-troff output, the `--man` option will tell
`mdman` how to create links to the man page. If there is no matching `--man`
option, then it links to a file named _name_`.md` in the same directory.
- Variables can be set with `{{*set name="value"}}`. These variables can
then be referenced with `{{name}}` expressions.
- Partial templates should be placed in a directory named `includes`
next to the source file. Templates can be included with an expression like
`{{> template-name}}`.
- Other helpers include:
- `{{lower value}}` Converts the given value to lowercase.


## OPTIONS

<dl>

<dt><code>-t</code> <em>type</em></dt>
<dd>Specifies the output type. The following output types are supported:</p>
<ul>
<li><code>man</code> — A troff-style man page. Outputs with a numbered extension (like
<code>.1</code>) matching the man page section.</li>
<li><code>md</code> — A markdown file, after all handlebars processing has been finished.
Outputs with the <code>.md</code> extension.</li>
<li><code>txt</code> — A text file, rendered for situations where a man page viewer isn't
available. Outputs with the <code>.txt</code> extension.</li>
</ul></dd>


<dt><code>-o</code> <em>outdir</em></dt>
<dd>Specifies the directory where to save the output.</dd>


<dt><code>--url</code> <em>base_url</em></dt>
<dd>Specifies a base URL to use for relative URLs within the document. Any
relative URL will be joined with this URL.</dd>


<dt><code>--man</code> <em>name</em><code>:</code><em>section</em><code>=</code><em>url</em></dt>
<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
may be specified multiple times. If a man page reference does not have a
matching <code>--man</code> entry, then a relative link to a file named <em>name</em><code>.md</code> will
be used.</dd>


<dt><em>sources...</em></dt>
<dd>The source input filename, may be specified multiple times.</dd>


</dl>

## EXAMPLES

1. Convert the given documents to man pages:

mdman -t man -o doc doc/mdman.md
Loading

0 comments on commit 8b878f3

Please sign in to comment.