Documenting Command-Line Interfaces

When documenting command-line interfaces, it is important to follow a widely recognized convention to allow readers to easily distinguish between the various parts of the command line that they need to put together.

In This Article

• Structure
• Common Rules
• Mutually Exclusive Elements
• Optional Elements
• Repeatable Elements
• Arguments
• Hidden User Input

Structure

• When you document a command-line command, stick to the following structure. Not all sections are mandatory.

• If appropriate, you may include additional sections. For example, the *nix find command has additional sections, such as Expressions, Standards Conformance, and Environment Variables.

  • (Mandatory) Name
  • (Mandatory) Synopsis
  • Notes
  • (Mandatory) Description
  • (Mandatory) Options
  • Files
  • History
  • Non-bugs
  • Bugs
  • Examples
  • Exit Status
  • See Also
  • History

Common Rules

• Use a monospace font for the parts of a command line. Use normal text for the descriptions and other sections.
• Learn More: Guidelines for Formatting Command-Line Examples and References to Commands in Text

In Markdown, use the HTML <code> tag to mark a command line where you need to emphasize different parts of it by using bold or italic. As opposed to <pre>, <code> accepts <strong> and <em>.

Mutually Exclusive Elements

• Use a vertical bar (|) to separate alternative, mutually exclusive elements.

• Apply vertical bars together with:

  • Braces ({}) to bound the choice and identify it as required. For example, {best-effort | controlled-load | guaranteed-delay}.
  • Brackets ([]) to bound the choice and identify it as optional. For example, [ip-address | hostname].

Optional Elements

Use square brackets ([]) to present optional elements. For example, ip route-cache [cbus].

Repeatable Elements

Use an ellipsis (…) after a syntax element to indicate that the element can be repeated. For example, protocol address [protocol2 address2 [... [protocol9 address9]]].

Arguments

• Use italic to mark arguments to commands such as file paths. For example, hostname domain.

• In contexts that do not allow italic, such as ASCII output, use angle brackets (<>) for arguments. For example, <hostname> <domain>.

  In Markdown, you have to escape angle brackets by using the < and > HTML entities.

Hidden User Input

In examples, use angle brackets to indicate a character string that the user enters but that does not appear on the screen, such as a password.

login: root
Password: <root-password>