# 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(7)`, Conventions for writing Linux man pages.

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

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

    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.

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

## 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 optional arguments get listed here.

    val s_common_options : string

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

    val s_none : string

`s_none` is a special section named `"cmdliner-none"` that can be used whenever you do not want something to be listed.

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

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