Up  Next

Module Cmdliner.Manpage

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


type block = [ `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.

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.
type title = string * int * string * string * string
The type for man page titles. Describes the man page title, section, center_footer, left_footer, center_header.
type t = title * block list
The type for a man page. A title and the page text as a list of blocks.
type xref = [ `Cmd of string | `Main | `Page of string * int | `Tool of string ]
The type for man page cross-references.

Standard section names and content

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.
val s_authors : string
The AUTHORS section.
val s_see_also : string
The SEE ALSO section.

Output

The Cmdliner.Manpage.print function can be useful if the client wants to define other man pages (e.g. to implement a help command).

type format = [ `Auto | `Groff | `Pager | `Plain ]
The type for man page output specification. 
val print : ?errs:Format.formatter ->
       ?subst:(string -> string option) ->
       format -> 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.