fork/cargo

git clone https://git.julia.blue/fork/cargo

borsAuto merge of #12067 - cuishuang:master, r=weihangloba45764a2

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