mirror of
https://github.com/rust-lang/cargo.git
synced 2025-09-28 11:20:36 +00:00
92 lines
3.5 KiB
Plaintext
92 lines
3.5 KiB
Plaintext
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
|
||
|