package cmdliner

  1. Overview
  2. Docs

Module Cmdliner.ManpageSource

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

type section_name = string

The type for section names (titles). See standard section names.

type block = [
  1. | `S of section_name
    (*

    Start a new section with given name.

    *)
  2. | `P of string
    (*

    Paragraph with given text.

    *)
  3. | `Pre of string
    (*

    Preformatted paragraph with given text.

    *)
  4. | `I of string * string
    (*

    Indented paragraph with given label and text.

    *)
  5. | `Noblank
    (*

    Suppress blank line introduced between two blocks.

    *)
  6. | `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.

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 = [
  1. | `Main
    (*

    Refer to the man page of the program itself.

    *)
  2. | `Cmd of string
    (*

    Refer to the command cmd of the tool, which must exist.

    *)
  3. | `Tool of string
    (*

    Tool refer to the given command line tool.

    *)
  4. | `Page of string * int
    (*

    Refer to the manpage name(sec).

    *)
]

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 : 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.

Output

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

type format = [
  1. | `Auto
    (*

    Format like `Pager or `Plain whenever the TERM environment variable is dumb or unset.

    *)
  2. | `Pager
    (*

    Tries to use a pager or falls back to `Plain.

    *)
  3. | `Plain
    (*

    Format to plain text.

    *)
  4. | `Groff
    (*

    Format to groff commands.

    *)
]

The type for man page output specification.

val print : ?env:(string -> string option) -> ?errs:Format.formatter -> ?subst:(string -> string option) -> format -> 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.