src/tools/cargo/crates/mdman/doc/out/mdman.txt

   1 MDMAN(1)
   2
   3 NAME
   4        mdman - Converts markdown to a man page
   5
   6 SYNOPSIS
   7        mdman [options] -t type -o outdir sources...
   8
   9 DESCRIPTION
  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 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
  57 OPTIONS
  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
  87 EXAMPLES
  88        1. Convert the given documents to man pages:
  89
  90               mdman -t man -o doc doc/mdman.md
  91