mirror of
https://github.com/c-cube/linol.git
synced 2025-12-06 03:05:31 -05:00
73 lines
3.3 KiB
Text
73 lines
3.3 KiB
Text
{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.}}
|