package reason

  1. Overview
  2. Docs
Reason: Syntax & Toolchain for OCaml

Install 

dune-project
 Dependency

reasonml.github.io Readme Changelog Edit opam file Versions (17)

Authors

  1. J
    Jordan Walke <jordojw@gmail.com>

Maintainers

  1. J
    Jordan Walke <jordojw@gmail.com>
  2. A
    Antonio Nuno Monteiro <anmonteiro@gmail.com>

Sources

reason-3.14.0.tbz
sha256=1d09ba24a0594745ab6b38b4d5f81ead8565b73cb69ad46af1c2c26f8d324f00
sha512=542d63c99ab976d011ca39953c022bdd2120177d5905df7ee6ff9623ec4d52c09a323ff7aec95fba5e71611c3850a88172e1c2be94ce68d966b5680ddd436494

doc/reason.cmdliner/Vendored_cmdliner/Manpage/index.html

Module Vendored_cmdliner.ManpageSource

Man page specification.

Man page generation is automatically handled by Cmdliner, consult 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

Sourcetype block = [
  1. | `S of string
  2. | `P of string
  3. | `Pre of string
  4. | `I of string * string
  5. | `Noblank
  6. | `Blocks of block list
]

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.

Sourceval escape : string -> string

escape s escapes s so that it doesn't get interpreted by the documentation markup language.

Sourcetype title = string * int * string * string * string

The type for man page titles. Describes the man page title, section, center_footer, left_footer, center_header.

Sourcetype t = title * block list

The type for a man page. A title and the page text as a list of blocks.

Sourcetype xref = [
  1. | `Main
  2. | `Cmd of string
  3. | `Tool of string
  4. | `Page of string * int
]

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.

Sourceval s_name : string

The NAME section. This section is automatically created by Cmdliner for your.

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

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

Sourceval s_commands : string

The COMMANDS section. By default subcommands get listed here.

Sourceval s_arguments : string

The ARGUMENTS section. By default positional arguments get listed here.

Sourceval s_options : string

The OPTIONS section. By default optional arguments get listed here.

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

Sourceval s_exit_status : string

The EXIT STATUS section. By default term status exit codes get listed here.

Sourceval s_environment : string

The ENVIRONMENT section. By default environment variables get listed here.

Sourceval s_environment_intro : block

s_environment_intro is the introduction content used by cmdliner when it creates the s_environment section.

Sourceval s_files : string

The FILES section.

Sourceval s_bugs : string

The BUGS section.

Sourceval s_examples : string

The EXAMPLES section.

Sourceval s_authors : string

The AUTHORS section.

Sourceval s_see_also : string

The SEE ALSO section.

Sourceval 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 print function can be useful if the client wants to define other man pages (e.g. to implement a help command).

Sourcetype format = [
  1. | `Auto
  2. | `Pager
  3. | `Plain
  4. | `Groff
]

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