diff options
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 279 |
1 files changed, 170 insertions, 109 deletions
@@ -27,8 +27,10 @@ The language is used to format .Bx .Ux -manuals. In this reference document, we describe its syntax, structure, -and usage. Our reference implementation is mandoc; the +manuals. +In this reference document, we describe its syntax, structure, and +usage. +Our reference implementation is mandoc; the .Sx COMPATIBILITY section describes compatibility with other troff \-mdoc implementations. .Pp @@ -37,7 +39,8 @@ An document follows simple rules: lines beginning with the control character .Sq \. -are parsed for macros. Other lines are interpreted within the scope of +are parsed for macros. +Other lines are interpreted within the scope of prior macros: .Bd -literal -offset indent \&.Sh Macro lines change control state. @@ -46,18 +49,20 @@ Other lines are interpreted within the current state. .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space -character, and, in certain circumstances, the tab character. All -manuals must have +character, and, in certain circumstances, the tab character. +All manuals must have .Ux line terminators. .Ss Comments Text following a .Sq \e\*q , whether in a macro or free-form text line, is ignored to the end of -line. A macro line with only a control character and comment escape, +line. +A macro line with only a control character and comment escape, .Sq \&.\e\*q , -is also ignored. Macro lines with only a control character and optionally -whitespace are stripped from input. +is also ignored. +Macro lines with only a control character and optionally whitespace are +stripped from input. .Ss Reserved Characters Within a macro line, the following characters are reserved: .Pp @@ -445,8 +450,8 @@ section, particularly .Sx \&Vt , and .Sx \&Ft . -All of these macros are output on their own line. If two such -dissimilar macros are pair-wise invoked (except for +All of these macros are output on their own line. +If two such dissimilar macros are pair-wise invoked (except for .Sx \&Ft before .Sx \&Fo @@ -858,14 +863,17 @@ For the scoping of individual macros, see .Ss \&%A Author name of an .Sx \&Rs -block. Multiple authors should each be accorded their own +block. +Multiple authors should each be accorded their own .Sx \%%A -line. Author names should be ordered with full or abbreviated -forename(s) first, then full surname. +line. +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. .Ss \&%B Book title of an .Sx \&Rs -block. This macro may also be used in a non-bibliographic context when +block. +This macro may also be used in a non-bibliographic context when referring to book titles. .Ss \&%C Publication city or location of an @@ -878,8 +886,8 @@ this macro is not implemented in .Ss \&%D Publication date of an .Sx \&Rs -block. This should follow the reduced or canonical form syntax -described in +block. +This should follow the reduced or canonical form syntax described in .Sx Dates . .Ss \&%I Publisher or issuer name of an @@ -904,7 +912,8 @@ block. .Ss \&%Q Institutional author (school, government, etc.) of an .Sx \&Rs -block. Multiple institutional authors should each be accorded their own +block. +Multiple institutional authors should each be accorded their own .Sx \&%Q line. .Ss \&%R @@ -914,8 +923,9 @@ block. .Ss \&%T Article title of an .Sx \&Rs -block. This macro may also be used in a non-bibliographical context -when referring to article titles. +block. +This macro may also be used in a non-bibliographical context when +referring to article titles. .Ss \&%U URI of reference document. .Ss \&%V @@ -925,7 +935,8 @@ block. .Ss \&Ac Closes an .Sx \&Ao -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Ad Address construct: usually in the context of an computational address in memory, not a physical (post) address. @@ -976,7 +987,7 @@ Examples: See also .Sx \&Aq . .Ss \&Ap -Inserts an apostrophe without any surrounding white-space. +Inserts an apostrophe without any surrounding whitespace. This is generally used as a grammatical device when referring to the verb form of a function: .Bd -literal -offset indent @@ -1040,7 +1051,8 @@ and .Ss \&Bc Closes a .Sx \&Bo -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Bd Begins a display block. Its syntax is as follows: @@ -1289,8 +1301,8 @@ The .Fl width argument is ignored. .It Fl tag -A list offset by list entry heads. List entry bodies are positioned -after the head as specified by the +A list offset by list entry heads. +List entry bodies are positioned after the head as specified by the .Fl width argument. .El @@ -1328,7 +1340,8 @@ See also .Ss \&Brc Closes a .Sx \&Bro -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Bro Begins a block enclosed by curly braces. Does not have any head arguments. @@ -1396,7 +1409,7 @@ Examples: .Pp .Em Remarks : this macro is commonly abused by using quoted literals to retain -white-space and align consecutive +whitespace and align consecutive .Sx \&Cd declarations. This practise is discouraged. @@ -1432,7 +1445,8 @@ Its syntax is as follows: .Ss \&Dc Closes a .Sx \&Do -block. Does not have any tail arguments. +block. +Does not have any tail arguments. .Ss \&Dd Document date. This is the mandatory first macro of any @@ -1475,8 +1489,8 @@ See also and .Sx \&D1 . .Ss \&Do -Begins a block enclosed by double quotes. Does not have any head -arguments. +Begins a block enclosed by double quotes. +Does not have any head arguments. .Pp Examples: .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot @@ -1484,7 +1498,9 @@ Examples: See also .Sx \&Dq . .Ss \&Dq -Encloses its arguments in double quotes. +Encloses its arguments in +.Dq typographic +double-quotes. .Pp Examples: .Bd -literal -offset indent -compact @@ -1493,8 +1509,10 @@ Examples: .Ed .Pp See also +.Ss \&Qq , +.Ss \&Sq , +and .Sx \&Do . -.Ss \&Dt Document title. This is the mandatory second macro of any .Nm @@ -1515,7 +1533,7 @@ Its arguments are as follows: .Bl -tag -width Ds -offset Ds .It Cm title The document's title (name), defaulting to -.Qq UNKNOWN +.Dq UNKNOWN if unspecified. It should be capitalised. .It Cm section @@ -1555,7 +1573,7 @@ or .Ar paper .Pq paper . It should correspond to the manual's filename suffix and defaults to -.Qq 1 +.Dq 1 if unspecified. .It Cm volume This overrides the volume inferred from @@ -1696,6 +1714,12 @@ stylistically decorating technical terms. Examples: .D1 \&.Em Warnings! .D1 \&.Em Remarks : +.Pp +See also +.Sx \&Bf , +.Sx \&Sy , +and +.Sx \&Li . .Ss \&En This macro is obsolete and not implemented. .Ss \&Eo @@ -1913,13 +1937,13 @@ is preferred for displaying code; the macro is used when referring to specific instructions. .Ss \&In An -.Qq include +.Dq include file. In the .Em SYNOPSIS section (only if invoked as the line macro), the first argument is preceded by -.Qq #include , +.Dq #include , the arguments is enclosed in angled braces. .Pp Examples: @@ -1991,8 +2015,8 @@ are interpreted within the scope of the last phrase. Calling the pseudo-macro .Sq \&Ta will open a new phrase scope (this must occur on a macro line to be -interpreted as a macro). Note that the tab phrase delimiter may only be -used within the +interpreted as a macro). +Note that the tab phrase delimiter may only be used within the .Sx \&It line itself. Subsequent this, only the @@ -2036,6 +2060,12 @@ Examples: Denotes text that should be in a literal font mode. Note that this is a presentation term and should not be used for stylistically decorating technical terms. +.Pp +See also +.Sx \&Bf , +.Sx \&Sy , +and +.Sx \&Em . .Ss \&Lk Format a hyperlink. Its syntax is as follows: @@ -2052,9 +2082,14 @@ See also Synonym for .Sx \&Pp . .Ss \&Ms +Display a mathematical symbol. +.Pp +Examples: +.D1 \&.Ms sigma +.D1 \&.Ms aleph .Ss \&Mt Format a -.Qq mailto: +.Dq mailto: hyperlink. Its syntax is as follows: .Pp @@ -2125,12 +2160,23 @@ macro rather than to mark up the name of the manual page. .Ss \&No A -.Qq noop +.Dq noop macro used to terminate prior macro contexts. .Pp Examples: .D1 \&.Sx \&Fl ab \&No cd \&Fl ef .Ss \&Ns +Suppress a space. +Following invocation, text is interpreted as free-form text until a +macro is encountered. +.Pp +Examples: +.D1 \&.Fl o \&Ns \&Ar output +.Pp +See also +.Sx \&No +and +.Sx \&Sm . .Ss \&Nx Format the NetBSD version provided as an argument, or a default value if no argument is provided. @@ -2157,7 +2203,7 @@ Multi-line version of .Sx \&Op . .Pp Examples: -.Bd -literal -offset indent +.Bd -literal -offset indent -compact \&.Oo \&.Op Fl flag Ns Ar value \&.Oc @@ -2234,7 +2280,7 @@ Close parenthesised context opened by .Sx \&Po . .Ss \&Pf Removes the space -.Pq Qq prefix +.Pq Dq prefix between its arguments. Its syntax is as follows: .Pp @@ -2259,9 +2305,29 @@ Parenthesised enclosure. See also .Sx \&Po . .Ss \&Qc +Close quoted context opened by +.Sx \&Qo . .Ss \&Ql +Format a single-quoted literal. +See also +.Sx \&Qq +and +.Sx \&Sq . .Ss \&Qo +Multi-line version of +.Sx \&Qq . .Ss \&Qq +Encloses its arguments in +.Dq typewriter +double-quotes. +Consider using +.Sx \&Dq . +.Pp +See also +.Sx \&Dq , +.Sx \&Sq , +and +.Sx \&Qo . .Ss \&Re Closes a .Sx \&Rs @@ -2309,7 +2375,23 @@ before the rendered output, else the block continues on the current line. .Ss \&Rv .Ss \&Sc +Close single-quoted context opened by +.Sx \&So . .Ss \&Sh +Begin a new section. +For a list of conventional manual sections, see +.Sx MANUAL STRUCTURE . +These sections should be used unless it's absolutely necessary that +custom sections be used. +.Pp +Section names should be unique so that they may be keyed by +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Ss , +and +.Sx \&Sx . .Ss \&Sm Switches the spacing mode for output generated from macros. Its syntax is as follows: @@ -2324,12 +2406,59 @@ no white space is inserted between macro arguments and between the output generated from adjacent macros, but free-form text lines still get normal spacing between words and sentences. .Ss \&So +Multi-line version of +.Sx \&Sq . .Ss \&Sq +Encloses its arguments in +.Dq typewriter +single-quotes. +.Pp +See also +.Sx \&Dq , +.Sx \&Qq , +and +.Sx \&So . .Ss \&Ss +Begin a new sub-section. +Unlike with +.Sx \&Sh , +there's no convention for sub-sections. +Conventional sections, as described in +.Sx MANUAL STRUCTURE , +rarely have sub-sections. +.Pp +Sub-section names should be unique so that they may be keyed by +.Sx \&Sx . +.Pp +See also +.Sx \&Pp , +.Sx \&Sh , +and +.Sx \&Sx . .Ss \&St .Ss \&Sx +Reference a section or sub-section. +The referenced section or sub-section name must be identical to the +enclosed argument, including whitespace. +.Pp +Examples: +.D1 \&.Sx MANUAL STRUCTURE .Ss \&Sy +Format enclosed arguments in symbolic +.Pq Dq boldface . +Note that this is a presentation term and should not be used for +stylistically decorating technical terms. +.Pp +See also +.Sx \&Bf , +.Sx \&Li , +and +.Sx \&Em . .Ss \&Tn +Format a tradename. +.Pp +Examples: +.D1 \&.Tn IBM . .Ss \&Ud Prints out .Dq currently under development. @@ -2571,71 +2700,3 @@ The .Nm reference was written by .An Kristaps Dzonsons Aq kristaps@bsd.lv . -.\" -.\" XXX: this really isn't the place for these caveats. -.\" . -.\" . -.\" .Sh CAVEATS -.\" There are many ambiguous parts of mdoc. -.\" . -.\" .Pp -.\" .Bl -dash -compact -.\" .It -.\" .Sq \&Fa -.\" should be -.\" .Sq \&Va -.\" as function arguments are variables. -.\" .It -.\" .Sq \&Ft -.\" should be -.\" .Sq \&Vt -.\" as function return types are still types. Furthermore, the -.\" .Sq \&Ft -.\" should be removed and -.\" .Sq \&Fo , -.\" which ostensibly follows it, should follow the same convention as -.\" .Sq \&Va . -.\" .It -.\" .Sq \&Va -.\" should formalise that only one or two arguments are acceptable: a -.\" variable name and optional, preceding type. -.\" .It -.\" .Sq \&Fd -.\" is ambiguous. It's commonly used to indicate an include file in the -.\" synopsis section. -.\" .Sq \&In -.\" should be used, instead. -.\" .It -.\" Only the -.\" .Sq \-literal -.\" argument to -.\" .Sq \&Bd -.\" makes sense. The remaining ones should be removed. -.\" .It -.\" The -.\" .Sq \&Xo -.\" and -.\" .Sq \&Xc -.\" macros should be deprecated. -.\" .It -.\" The -.\" .Sq \&Dt -.\" macro lacks clarity. It should be absolutely clear which title will -.\" render when formatting the manual page. -.\" .It -.\" A -.\" .Sq \&Lx -.\" should be provided for Linux (\(`a la -.\" .Sq \&Ox , -.\" .Sq \&Nx -.\" etc.). -.\" .It -.\" There's no way to refer to references in -.\" .Sq \&Rs/Re -.\" blocks. -.\" .It -.\" The \-split and \-nosplit dictates via -.\" .Sq \&An -.\" are re-set when entering and leaving the AUTHORS section. -.\" .El -.\" . |