blob: 83fa7de9034247d629bced8f927462cd0aaf9e73 (
plain)
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
|
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:
o Every block of command-line options must be wrapped between
{{#options}} and {{/options}} tags. This tells the processor where
the options start and end.
o 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.
o 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.
o Variables can be set with {{*set name="value"}}. These variables can
then be referenced with {{name}} expressions.
o 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}}.
o Other helpers include:
o {{lower value}} Converts the given value to lowercase.
OPTIONS
-t type
Specifies the output type. The following output types are supported:
o man — A troff-style man page. Outputs with a numbered extension
(like .1) matching the man page section.
o md — A markdown file, after all handlebars processing has been
finished. Outputs with the .md extension.
o txt — A text file, rendered for situations where a man page
viewer isn't available. Outputs with the .txt extension.
-o outdir
Specifies the directory where to save the output.
--url base_url
Specifies a base URL to use for relative URLs within the document.
Any relative URL will be joined with this URL.
--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.
sources...
The source input filename, may be specified multiple times.
EXAMPLES
1. Convert the given documents to man pages:
mdman -t man -o doc doc/mdman.md
|
