mirror of
https://github.com/c-cube/linol.git
synced 2025-12-06 11:15:46 -05:00
2 lines
5.3 KiB
HTML
2 lines
5.3 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>tool_man (cmdliner.tool_man)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.2"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">cmdliner</a> » tool_man</nav><header class="odoc-preamble"><h1 id="tool_man"><a href="#tool_man" class="anchor"></a>Tool man pages</h1></header><nav class="odoc-toc"><ul><li><a href="#manual">Manual</a></li><li><a href="#doclang">Documentation markup language</a></li></ul></nav><div class="odoc-content"><h2 id="manual"><a href="#manual" class="anchor"></a>Manual</h2><p>Man page sections for a command are printed in the order specified by manual as given to <a href="Cmdliner/Cmd/index.html#val-info"><code>Cmdliner.Cmd.info</code></a>. Unless specified explicitly in the command's manual the following sections are automatically created and populated for you:</p><ul><li><a href="Cmdliner/Manpage/index.html#val-s_name" title="Cmdliner.Manpage.s_name"><code>NAME</code></a> section.</li><li><a href="Cmdliner/Manpage/index.html#val-s_synopsis" title="Cmdliner.Manpage.s_synopsis"><code>SYNOPSIS</code></a> section.</li></ul><p>The various <code>doc</code> documentation strings specified by the command's term arguments get inserted at the end of the documentation section they respectively mention in their <code>docs</code> argument:</p><ol><li>For commands, see <a href="Cmdliner/Cmd/index.html#val-info"><code>Cmdliner.Cmd.info</code></a>.</li><li>For positional arguments, see <a href="Cmdliner/Arg/index.html#type-info"><code>Cmdliner.Arg.info</code></a>. Those are listed iff both the <code>docv</code> and <code>doc</code> string is specified by <a href="Cmdliner/Arg/index.html#val-info"><code>Cmdliner.Arg.info</code></a>.</li><li>For optional arguments, see <a href="Cmdliner/Arg/index.html#val-info"><code>Cmdliner.Arg.info</code></a>.</li><li>For exit statuses, see <a href="Cmdliner/Cmd/Exit/index.html#val-info"><code>Cmdliner.Cmd.Exit.info</code></a>.</li><li>For environment variables, see <a href="Cmdliner/Arg/index.html#val-env_var"><code>Cmdliner.Arg.env_var</code></a> and <a href="Cmdliner/Cmd/Env/index.html#val-info"><code>Cmdliner.Cmd.Env.info</code></a>.</li></ol><p>If a <code>docs</code> section name is mentioned and does not exist in the command's manual, an empty section is created for it, after which the <code>doc</code> strings are inserted, possibly prefixed by boilerplate text (e.g. for <a href="Cmdliner/Manpage/index.html#val-s_environment"><code>Cmdliner.Manpage.s_environment</code></a> and <a href="Cmdliner/Manpage/index.html#val-s_exit_status"><code>Cmdliner.Manpage.s_exit_status</code></a>).</p><p>If the created section is:</p><ul><li><a href="Cmdliner/Manpage/index.html#standard_sections" title="standard_sections">standard</a>, it is inserted at the right place in the order specified <a href="Cmdliner/Manpage/index.html#standard_sections" title="standard_sections">here</a>, but after a possible non-standard section explicitly specified by the command's manual since the latter get the order number of the last previously specified standard section or the order of <a href="Cmdliner/Manpage/index.html#val-s_synopsis"><code>Cmdliner.Manpage.s_synopsis</code></a> if there is no such section.</li><li>non-standard, it is inserted before the <a href="Cmdliner/Manpage/index.html#val-s_commands"><code>Cmdliner.Manpage.s_commands</code></a> 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.</li></ul><p>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.</p><h2 id="doclang"><a href="#doclang" class="anchor"></a>Documentation markup language</h2><p>Manpage <a href="Cmdliner/Manpage/index.html#type-block" title="Cmdliner.Manpage.block">blocks</a> and doc strings support the following markup language.</p><ul><li>Markup directives <code>$(i,text)</code> and <code>$(b,text)</code>, where <code>text</code> is raw text respectively rendered in italics and bold.</li><li>Outside markup directives, context dependent variables of the form <code>$(var)</code> are substituted by marked up data. For example in a term's man page <code>$(tname)</code> is substituted by the term name in bold.</li><li>Characters $, (, ) and \ can respectively be escaped by \$, \(, \) and \\ (in OCaml strings this will be <code>"\\$"</code>, <code>"\\("</code>, <code>"\\)"</code>, <code>"\\\\"</code>). 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.</li><li>Referring to unknown markup directives or variables will generate errors on standard error during documentation generation.</li></ul></div></body></html>
|