fork/cargo
git clone https://git.julia.blue/fork/cargo
ba45764a2
0.87.0
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