{0:tool_man Tool man pages}

See also the {{!page-cli.help}section} about man pages in the command
line interface manual.

{1:manual Man page generation}

Man page sections for a command are printed in the order specified by
the [man] value given to {!Cmdliner.Cmd.val-info}. Unless
specified explicitly in the [man] value the following sections
are automatically created and populated for you:

{ul
{- {{!Cmdliner.Manpage.s_name}[NAME]} section.}
{- {{!Cmdliner.Manpage.s_synopsis}[SYNOPSIS]} section.}}

The various [doc] documentation strings specified by the command's
term arguments get inserted at the end of the documentation section
they respectively mention in their [docs] argument:

{ol
{- For commands, see {!Cmdliner.Cmd.val-info}.}
{- For positional arguments, see {!Cmdliner.Arg.type-info}. Those are listed iff
   both the [docv] and [doc] string is specified by {!Cmdliner.Arg.val-info}.}
{- For optional arguments, see {!Cmdliner.Arg.val-info}.}
{- For exit statuses, see {!Cmdliner.Cmd.Exit.val-info}.}
{- For environment variables, see {!Cmdliner.Cmd.Env.val-info}.}}

If a [docs] section name is mentioned and does not exist in the command's
[man] value, an empty section is created for it, after which the [doc] strings
are inserted, possibly prefixed by boilerplate text (e.g. for
{!Cmdliner.Manpage.s_environment} and {!Cmdliner.Manpage.s_exit_status}).

If the created section is:
{ul
{- {{!Cmdliner.Manpage.standard_sections}standard}, it
    is inserted at the right place in the order specified
    {{!Cmdliner.Manpage.standard_sections}here}, but after a
    possible non-standard
    section explicitly specified by the command's [man] value since the latter
    get the order number of the last previously specified standard section
    or the order of {!Cmdliner.Manpage.s_synopsis} if there is no such section.}
{-  non-standard, it is inserted before the {!Cmdliner.Manpage.s_commands}
    section or the first subsequent existing standard section if it
    doesn't exist. Taking advantage of this behaviour is discouraged,
    you should declare manually your non standard section in the command's
    manual page.}}

Finally note that the header of empty sections are dropped from the
output.  This allows you to share section placements among many
commands and render them only if something actually gets inserted in
it.

{1:doclang Documentation markup language}

Manpage {{!Cmdliner.Manpage.block}blocks} and the doc strings of the
various [info] values support the following markup language.

{ul
{- Markup directives [$(i,text)] and [$(b,text)], where [text] is raw
   text respectively rendered in italics and bold.}
{- Outside markup directives, context dependent variables of the form
   [$(var)] are substituted by marked up data. For example in a command
   man page [$(cmd)] is substituted by the command's invocation in
   bold.}
{- Characters '$', '(', ')' and '\' can respectively be escaped by \$, \(, \)
   and \\ . In OCaml strings this will be ["\\$"], ["\\("], ["\\)"],
   ["\\\\"]. Escaping '$' and '\' is mandatory everywhere. Escaping ')' is
   mandatory only in markup directives. Escaping '(' is only here for
   your symmetric pleasure. Any other sequence of characters starting
   with a '\' is an illegal character sequence.}
{- Referring to unknown markup directives or variables will generate
   errors on standard error during documentation generation.}}