mirror of
https://git.proxmox.com/git/cargo
synced 2025-08-18 03:27:16 +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
|
|
|