simon/linol
1
0
Fork 0
mirror of https://github.com/c-cube/linol.git synced 2025-12-07 03:35:41 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
linol/cmdliner/Cmdliner/Manpage/index.html
c-cube 247371f990 deploy: fb49472f34
2025-11-26 00:50:10 +00:00

9 lines
17 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Manpage (cmdliner.Cmdliner.Manpage)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><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">Index</a> &#x00BB; <a href="../../index.html">cmdliner</a> &#x00BB; <a href="../index.html">Cmdliner</a> &#x00BB; Manpage</nav><header class="odoc-preamble"><h1>Module <code><span>Cmdliner.Manpage</span></code></h1><p>Man pages.</p><p>Man page generation is automatically handled by <code>Cmdliner</code>, see the <a href="../../tool_man.html#manual" title="manual">details</a>. The <a href="#type-block"><code>Manpage.block</code></a> type is used to define a man page's content. It's a good idea to follow the <a href="#standard_sections" title="standard_sections">standard</a> manual page structure.</p><p><b>References.</b></p><ul><li><code>man-pages(7)</code>, <a href="http://man7.org/linux/man-pages/man7/man-pages.7.html"><em>Conventions for writing Linux man pages</em></a>.</li></ul></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#man">Man pages</a></li><li><a href="#standard_sections">Standard section names and content</a></li><li><a href="#output">Output</a></li></ul></nav></div><div class="odoc-content"><h2 id="man"><a href="#man" class="anchor"></a>Man pages</h2><div class="odoc-spec"><div class="spec type anchored" id="type-section_name"><a href="#type-section_name" class="anchor"></a><code><span><span class="keyword">type</span> section_name</span><span> = string</span></code></div><div class="spec-doc"><p>The type for section names (titles). See <a href="#standard_sections" title="standard_sections">standard section names</a>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-block"><a href="#type-block" class="anchor"></a><code><span><span class="keyword">type</span> block</span><span> = </span><span>[ </span></code><ol><li id="type-block.S" class="def variant constructor anchored"><a href="#type-block.S" class="anchor"></a><code><span>| </span><span>`S <span class="keyword">of</span> <a href="#type-section_name">section_name</a></span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Start a new section with given name.</p><span class="comment-delim">*)</span></div></li><li id="type-block.P" class="def variant constructor anchored"><a href="#type-block.P" class="anchor"></a><code><span>| </span><span>`P <span class="keyword">of</span> string</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Paragraph with given text.</p><span class="comment-delim">*)</span></div></li><li id="type-block.Pre" class="def variant constructor anchored"><a href="#type-block.Pre" class="anchor"></a><code><span>| </span><span>`Pre <span class="keyword">of</span> string</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Preformatted paragraph with given text.</p><span class="comment-delim">*)</span></div></li><li id="type-block.I" class="def variant constructor anchored"><a href="#type-block.I" class="anchor"></a><code><span>| </span><span>`I <span class="keyword">of</span> string * string</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Indented paragraph with given label and text.</p><span class="comment-delim">*)</span></div></li><li id="type-block.Noblank" class="def variant constructor anchored"><a href="#type-block.Noblank" class="anchor"></a><code><span>| </span><span>`Noblank</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Suppress blank line introduced between two blocks.</p><span class="comment-delim">*)</span></div></li><li id="type-block.Blocks" class="def variant constructor anchored"><a href="#type-block.Blocks" class="anchor"></a><code><span>| </span><span>`Blocks <span class="keyword">of</span> <span><a href="#type-block">block</a> list</span></span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Splice given blocks.</p><span class="comment-delim">*)</span></div></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>The type for a block of man page text.</p><p>Except in <code>`Pre</code>, whitespace and newlines are not significant and are all collapsed to a single space. All block strings support the <a href="../../tool_man.html#doclang" title="doclang">documentation markup language</a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-escape"><a href="#val-escape" class="anchor"></a><code><span><span class="keyword">val</span> escape : <span>string <span class="arrow">&#45;&gt;</span></span> string</span></code></div><div class="spec-doc"><p><code>escape s</code> escapes <code>s</code> so that it doesn't get interpreted by the <a href="../../tool_man.html#doclang" title="doclang">documentation markup language</a>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-title"><a href="#type-title" class="anchor"></a><code><span><span class="keyword">type</span> title</span><span> = string * int * string * string * string</span></code></div><div class="spec-doc"><p>The type for man page titles. Describes the man page <code>title</code>, <code>section</code>, <code>center_footer</code>, <code>left_footer</code>, <code>center_header</code>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span><span> = <a href="#type-title">title</a> * <span><a href="#type-block">block</a> list</span></span></code></div><div class="spec-doc"><p>The type for a man page. A title and the page text as a list of blocks.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-xref"><a href="#type-xref" class="anchor"></a><code><span><span class="keyword">type</span> xref</span><span> = </span><span>[ </span></code><ol><li id="type-xref.Main" class="def variant constructor anchored"><a href="#type-xref.Main" class="anchor"></a><code><span>| </span><span>`Main</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Refer to the man page of the program itself.</p><span class="comment-delim">*)</span></div></li><li id="type-xref.Cmd" class="def variant constructor anchored"><a href="#type-xref.Cmd" class="anchor"></a><code><span>| </span><span>`Cmd <span class="keyword">of</span> string</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Refer to the command <code>cmd</code> of the tool, which must exist.</p><span class="comment-delim">*)</span></div></li><li id="type-xref.Tool" class="def variant constructor anchored"><a href="#type-xref.Tool" class="anchor"></a><code><span>| </span><span>`Tool <span class="keyword">of</span> string</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Tool refer to the given command line tool.</p><span class="comment-delim">*)</span></div></li><li id="type-xref.Page" class="def variant constructor anchored"><a href="#type-xref.Page" class="anchor"></a><code><span>| </span><span>`Page <span class="keyword">of</span> string * int</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Refer to the manpage <code>name(sec)</code>.</p><span class="comment-delim">*)</span></div></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>The type for man page cross-references.</p></div></div><h2 id="standard_sections"><a href="#standard_sections" class="anchor"></a>Standard section names and content</h2><p>The following are standard man page section names, roughly ordered in the order they conventionally appear. See also <a href="http://man7.org/linux/man-pages/man7/man-pages.7.html"><code>man man-pages</code></a> for more elaborations about what sections should contain.</p><div class="odoc-spec"><div class="spec value anchored" id="val-s_name"><a href="#val-s_name" class="anchor"></a><code><span><span class="keyword">val</span> s_name : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>NAME</code> section. This section is automatically created by <code>Cmdliner</code> for your command.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_synopsis"><a href="#val-s_synopsis" class="anchor"></a><code><span><span class="keyword">val</span> s_synopsis : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>SYNOPSIS</code> section. By default this section is automatically created by <code>Cmdliner</code> for your command, unless it is the first section of your term's man page, in which case it will replace it with yours.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_description"><a href="#val-s_description" class="anchor"></a><code><span><span class="keyword">val</span> s_description : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>DESCRIPTION</code> section. This should be a description of what the tool does and provide a little bit of command line usage and documentation guidance.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_commands"><a href="#val-s_commands" class="anchor"></a><code><span><span class="keyword">val</span> s_commands : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>COMMANDS</code> section. By default subcommands get listed here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_arguments"><a href="#val-s_arguments" class="anchor"></a><code><span><span class="keyword">val</span> s_arguments : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>ARGUMENTS</code> section. By default positional arguments get listed here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_options"><a href="#val-s_options" class="anchor"></a><code><span><span class="keyword">val</span> s_options : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>OPTIONS</code> section. By default optional arguments get listed here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_common_options"><a href="#val-s_common_options" class="anchor"></a><code><span><span class="keyword">val</span> s_common_options : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>COMMON OPTIONS</code> section. By default help and version options get listed here. For programs with multiple commands, optional arguments common to all commands can be added here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_exit_status"><a href="#val-s_exit_status" class="anchor"></a><code><span><span class="keyword">val</span> s_exit_status : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>EXIT STATUS</code> section. By default term status exit codes get listed here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_environment"><a href="#val-s_environment" class="anchor"></a><code><span><span class="keyword">val</span> s_environment : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>ENVIRONMENT</code> section. By default environment variables get listed here.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_environment_intro"><a href="#val-s_environment_intro" class="anchor"></a><code><span><span class="keyword">val</span> s_environment_intro : <a href="#type-block">block</a></span></code></div><div class="spec-doc"><p><code>s_environment_intro</code> is the introduction content used by cmdliner when it creates the <a href="#val-s_environment"><code>s_environment</code></a> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_files"><a href="#val-s_files" class="anchor"></a><code><span><span class="keyword">val</span> s_files : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>FILES</code> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_bugs"><a href="#val-s_bugs" class="anchor"></a><code><span><span class="keyword">val</span> s_bugs : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>BUGS</code> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_examples"><a href="#val-s_examples" class="anchor"></a><code><span><span class="keyword">val</span> s_examples : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>EXAMPLES</code> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_authors"><a href="#val-s_authors" class="anchor"></a><code><span><span class="keyword">val</span> s_authors : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>AUTHORS</code> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_see_also"><a href="#val-s_see_also" class="anchor"></a><code><span><span class="keyword">val</span> s_see_also : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p>The <code>SEE ALSO</code> section.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-s_none"><a href="#val-s_none" class="anchor"></a><code><span><span class="keyword">val</span> s_none : <a href="#type-section_name">section_name</a></span></code></div><div class="spec-doc"><p><code>s_none</code> is a special section named <code>&quot;cmdliner-none&quot;</code> that can be used whenever you do not want something to be listed.</p></div></div><h2 id="output"><a href="#output" class="anchor"></a>Output</h2><p>The <a href="#val-print"><code>print</code></a> function can be useful if the client wants to define other man pages (e.g. to implement a help command).</p><div class="odoc-spec"><div class="spec type anchored" id="type-format"><a href="#type-format" class="anchor"></a><code><span><span class="keyword">type</span> format</span><span> = </span><span>[ </span></code><ol><li id="type-format.Auto" class="def variant constructor anchored"><a href="#type-format.Auto" class="anchor"></a><code><span>| </span><span>`Auto</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Format like <code>`Pager</code> or <code>`Plain</code> whenever the <code>TERM</code> environment variable is <code>dumb</code> or unset.</p><span class="comment-delim">*)</span></div></li><li id="type-format.Pager" class="def variant constructor anchored"><a href="#type-format.Pager" class="anchor"></a><code><span>| </span><span>`Pager</span></code><div class="def-doc"><span class="comment-delim">(*</span><p><a href="../../cli.html#help" title="help">Tries</a> to use a pager or falls back to <code>`Plain</code>.</p><span class="comment-delim">*)</span></div></li><li id="type-format.Plain" class="def variant constructor anchored"><a href="#type-format.Plain" class="anchor"></a><code><span>| </span><span>`Plain</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Format to plain text.</p><span class="comment-delim">*)</span></div></li><li id="type-format.Groff" class="def variant constructor anchored"><a href="#type-format.Groff" class="anchor"></a><code><span>| </span><span>`Groff</span></code><div class="def-doc"><span class="comment-delim">(*</span><p>Format to groff commands.</p><span class="comment-delim">*)</span></div></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>The type for man page output specification.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-print"><a href="#val-print" class="anchor"></a><code><span><span class="keyword">val</span> print :
<span><span class="optlabel">?env</span>:<span>(<span>string <span class="arrow">&#45;&gt;</span></span> <span>string option</span>)</span> <span class="arrow">&#45;&gt;</span></span>
<span><span class="optlabel">?errs</span>:<a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">&#45;&gt;</span></span>
<span><span class="optlabel">?subst</span>:<span>(<span>string <span class="arrow">&#45;&gt;</span></span> <span>string option</span>)</span> <span class="arrow">&#45;&gt;</span></span>
<span><a href="#type-format">format</a> <span class="arrow">&#45;&gt;</span></span>
<span><a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">&#45;&gt;</span></span>
<span><a href="#type-t">t</a> <span class="arrow">&#45;&gt;</span></span>
unit</span></code></div><div class="spec-doc"><p><code>print ~env ~errs ~subst fmt ppf page</code> prints <code>page</code> on <code>ppf</code> in the format <code>fmt</code>.</p><ul><li><code>env</code> is used to lookup environment for driving paging when the format is <code>`Pager</code>. Defaults to <code>Sys.getenv_opt</code>.</li><li><code>subst</code> can be used to perform variable substitution (defaults to the identity).</li><li><code>errs</code> is used to print formatting errors, it defaults to <code>Format.err_formatter</code>.</li></ul></div></div></div></body></html>
Reference in a new issue View git blame Copy permalink