Cmdliner.Manpage
Man pages.
Man page generation is automatically handled by Cmdliner
, see the details. The Manpage.block
type is used to define a man page's content. It's a good idea to follow the standard manual page structure.
References.
man-pages(7)
, Conventions for writing Linux man pages.The type for section names (titles). See standard section names.
type block = [
| `S of section_name
Start a new section with given name.
*)| `P of string
Paragraph with given text.
*)| `Pre of string
Preformatted paragraph with given text.
*)| `I of string * string
Indented paragraph with given label and text.
*)| `Noblank
Suppress blank line introduced between two blocks.
*)| `Blocks of block list
Splice given blocks.
*) ]
The type for a block of man page text.
Except in `Pre
, whitespace and newlines are not significant and are all collapsed to a single space. All block strings support the documentation markup language.
escape s
escapes s
so that it doesn't get interpreted by the documentation markup language.
The type for man page titles. Describes the man page title
, section
, center_footer
, left_footer
, center_header
.
type xref = [
| `Main
Refer to the man page of the program itself.
*)| `Cmd of string
Refer to the command cmd
of the tool, which must exist.
| `Tool of string
Tool refer to the given command line tool.
*)| `Page of string * int
Refer to the manpage name(sec)
.
]
The type for man page cross-references.
The following are standard man page section names, roughly ordered in the order they conventionally appear. See also man man-pages
for more elaborations about what sections should contain.
val s_name : section_name
The NAME
section. This section is automatically created by Cmdliner
for your command.
val s_synopsis : section_name
The SYNOPSIS
section. By default this section is automatically created by Cmdliner
for your command, unless it is the first section of your term's man page, in which case it will replace it with yours.
val s_description : section_name
The DESCRIPTION
section. This should be a description of what the tool does and provide a little bit of command line usage and documentation guidance.
val s_commands : section_name
The COMMANDS
section. By default subcommands get listed here.
val s_arguments : section_name
The ARGUMENTS
section. By default positional arguments get listed here.
val s_options : section_name
The OPTIONS
section. By default optional arguments get listed here.
val s_common_options : section_name
The COMMON OPTIONS
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.
val s_exit_status : section_name
The EXIT STATUS
section. By default term status exit codes get listed here.
val s_environment : section_name
The ENVIRONMENT
section. By default environment variables get listed here.
val s_environment_intro : block
s_environment_intro
is the introduction content used by cmdliner when it creates the s_environment
section.
val s_files : section_name
The FILES
section.
val s_bugs : section_name
The BUGS
section.
val s_examples : section_name
The EXAMPLES
section.
val s_authors : section_name
The AUTHORS
section.
val s_see_also : section_name
The SEE ALSO
section.
val s_none : section_name
s_none
is a special section named "cmdliner-none"
that can be used whenever you do not want something to be listed.
The print
function can be useful if the client wants to define other man pages (e.g. to implement a help command).
type format = [
| `Auto
Format like `Pager
or `Plain
whenever the TERM
environment variable is dumb
or unset.
| `Pager
| `Plain
Format to plain text.
*)| `Groff
Format to groff commands.
*) ]
The type for man page output specification.
val print :
?env:(string -> string option) ->
?errs:Stdlib.Format.formatter ->
?subst:(string -> string option) ->
format ->
Stdlib.Format.formatter ->
t ->
unit
print ~env ~errs ~subst fmt ppf page
prints page
on ppf
in the format fmt
.
env
is used to lookup environment for driving paging when the format is `Pager
. Defaults to Sys.getenv_opt
.subst
can be used to perform variable substitution (defaults to the identity).errs
is used to print formatting errors, it defaults to Format.err_formatter
.