module Manpage:sig
..end
Man page specification.
Man page generation is automatically handled by Cmdliner
,
consult the details.
The Cmdliner.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.typeblock =
[ `Blocks of block list
| `I of string * string
| `Noblank
| `P of string
| `Pre of string
| `S of string ]
The type for a block of man page text.
`S s
introduces a new section s
, see the
standard section names.`P t
is a new paragraph with text t
.`Pre t
is a new preformatted paragraph with text t
.`I (l,t)
is an indented paragraph with label
l
and text t
.`Noblank
suppresses the blank line introduced between two blocks.`Blocks bs
splices the blocks bs
.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.
val escape : string -> string
escape s
escapes s
so that it doesn't get interpreted by the
documentation markup language.
typetitle =
string * int * string * string * string
The type for man page titles. Describes the man page
title
, section
, center_footer
, left_footer
, center_header
.
typet =
title * block list
The type for a man page. A title and the page text as a list of blocks.
typexref =
[ `Cmd of string | `Main | `Page of string * int | `Tool of string ]
The type for man page cross-references.
`Main
refers to the man page of the program itself.`Cmd cmd
refers to the man page of the program's cmd
command (which must exist).`Tool bin
refers to the command line tool named bin
.`Page (name, sec)
refers to the man page name(sec)
.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 : string
The NAME
section. This section is automatically created by
Cmdliner
for your.
val s_synopsis : string
The SYNOPSIS
section. By default this section is automatically
created by Cmdliner
for you, unless it is the first section of
your term's man page, in which case it will replace it with yours.
val s_description : string
The DESCRIPTION
section. This should be a description of what
the tool does and provide a little bit of usage and
documentation guidance.
val s_commands : string
The COMMANDS
section. By default subcommands get listed here.
val s_arguments : string
The ARGUMENTS
section. By default positional arguments get
listed here.
val s_options : string
The OPTIONS
section. By default options and flag arguments get
listed here.
val s_common_options : string
The COMMON OPTIONS
section. For programs with multiple commands
a section that can be used to gather options common to all commands.
val s_exit_status : string
The EXIT STATUS
section. By default term status exit codes
get listed here.
val s_environment : string
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 Cmdliner.Manpage.s_environment
section.
val s_files : string
The FILES
section.
val s_bugs : string
The BUGS
section.
val s_examples : string
The EXAMPLES
section.
string
: The AUTHORS
section.
val s_see_also : string
The SEE ALSO
section.
The Cmdliner.Manpage.print
function can be useful if the client wants to define
other man pages (e.g. to implement a help command).
typeformat =
[ `Auto | `Groff | `Pager | `Plain ]
The type for man page output specification.
`Auto
, formats like `Pager
or `Plain
whenever the TERM
environment variable is dumb
or unset.`Pager
, tries to write to a discovered pager, if that fails
uses the `Plain
format.`Plain
, formats to plain text.`Groff
, formats to groff commands.val print : ?errs:Stdlib.Format.formatter ->
?subst:(string -> string option) ->
format ->
Stdlib.Format.formatter -> t -> unit
print ~errs ~subst fmt ppf page
prints page
on ppf
in the
format fmt
. 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
.