NAME

style/synopsis —

DESCRIPTION

The purpose of the SYNOPSIS section is to provide a first overview of the syntax of the topic. Never attempt to explain semantics there. Since the SYNOPSIS is the first part of a manual page every user will look at, extra care to make it useful is well spent. If the syntax of the topic is very simple, it may be possible for the SYNOPSIS to exhaustively document the syntax. Doing so is desirable unless it makes the SYNOPSIS unduly long or complicated. The mdoc(7) language intentionally does not provide a complete or formal metasyntax notation like, for example, the Backus-Naur Form does. The idea is to make reading manual pages easy without formal mathematical training. Consequently, it is sometimes impossible to express all aspects of the syntax in the SYNOPSIS. In such cases, a properly written DESCRIPTION will resolve all the ambiguities that the SYNOPSIS may contain. Sometimes, even if the mdoc(7) language does provide the tools to unambiguously express all aspects of the syntax in the SYNOPSIS, it may be better to refrain from doing so if that would result in a lengthy, cumbersome SYNOPSIS. Keep in mind that brevity and simplicity are the most important assets of the SYNOPSIS and should not be disturbed by minor details; the place to fully explain all the details is the DESCRIPTION. Very often, there is more than one way to write an acceptable SYNOPSIS. Choose the way most helpful as a first overview.

Optional and alternative syntax elements

Even though mdoc(7) does not attempt to provide a complete or formal metasyntax notation, some metasyntax conventions do exist that make reading manual pages easier without causing formal clutter. The most important metasyntax convention probably is the representation of optional and alternative syntax elements. If any syntax element is optional, always indicate that by enclosing it in an Op or Oo block. Usually, where that is easily feasible, prefer Op over Oo for brevity. Where any one of two or more syntax elements can be used, put the vertical bar delimiter (‘|’) between them. Use the plain ASCII vertical bar character, put it into its own macro argument, and do not escape it in any way, neither with a zero-width space nor with a backslash. Do not use an escape sequence like \(ba or a predefined string like \*(Ba. Since the vertical bar is treated as a middle delimiter, it is not necessary to repeat the previous in-line macro after it; the previous in-line macro scope will automatically resume after the vertical bar. In most cases, sequences of alternatives are part of optional syntax elements, in which case they are enclosed in an optional block and there is little ambiguity where the sequence of alternatives begins and ends. In rarer cases, in particular for mandatory alternatives, ambiguity may arise. The mdoc(7) language does not provide a way to resolve such ambiguities. Do not borrow metasyntax from other languages, and don't invent your own metasyntax. For example, do not use curly braces or the Brq macro in this context. Instead, make sure the text in the DESCRIPTION resolves the ambiguity. In case an alternative looks particularly misleading when marked up as described above, it may sometimes be possible to informally provide visual hints where the alternative is intended to begin and end by suppressing white space with the Ns or Sm off macros; use this possibility sparingly. Placing line breaks wisely may also provide informal visual cues in a few cases.

EXAMPLES

In simple cases, alternatives can be used to express that options are mutually exclusive: In complicated cases, it's better to leave the details to the DESCRIPTION: Mandatory alternative: Alternative arguments: Alternative command modifiers: The spacing trick to reduce visual ambiguity: A typical example where trying to resolve ambiguities would be a bad idea because it would just make the SYNOPSIS less readable: