diff options
| -rw-r--r-- | man.3 | 48 | ||||
| -rw-r--r-- | man.7 | 44 | ||||
| -rw-r--r-- | mandoc.1 | 72 | ||||
| -rw-r--r-- | manuals.7 | 34 | ||||
| -rw-r--r-- | mdoc.3 | 64 | ||||
| -rw-r--r-- | mdoc.7 | 120 |
6 files changed, 191 insertions, 191 deletions
@@ -49,7 +49,7 @@ .Sh DESCRIPTION The .Nm man -library parses lines of +library parses lines of .Xr man 7 input (and .Em only @@ -58,12 +58,12 @@ man) into an abstract syntax tree (AST). .Pp In general, applications initiate a parsing sequence with .Fn man_alloc , -parse each line in a document with +parse each line in a document with .Fn man_parseln , close the parsing session with .Fn man_endparse , operate over the syntax tree returned by -.Fn man_node +.Fn man_node and .Fn man_meta , then free all allocated memory with @@ -76,13 +76,13 @@ sequence. See the section for a full example. .\" PARAGRAPH .Pp -This section further defines the +This section further defines the .Sx Types , -.Sx Functions +.Sx Functions and .Sx Variables available to programmers. Following that, the -.Sx Abstract Syntax Tree +.Sx Abstract Syntax Tree section documents the output tree. .\" SUBSECTION .Ss Types @@ -105,7 +105,7 @@ A set of message callbacks defined in .It Vt struct man_node A parsed node. Defined in .Pa man.h . -See +See .Sx Abstract Syntax Tree for details. .El @@ -118,8 +118,8 @@ Function descriptions follow: Allocates a parsing structure. The .Fa data pointer is passed to callbacks in -.Fa cb , -which are documented further in the header file. +.Fa cb , +which are documented further in the header file. The .Fa pflags arguments are defined in @@ -128,7 +128,7 @@ Returns NULL on failure. If non-NULL, the pointer must be freed with .Fn man_free . .\" LIST-ITEM .It Fn man_reset -Reset the parser for another parse routine. After its use, +Reset the parser for another parse routine. After its use, .Fn man_parseln behaves as if invoked for the first time. .\" LIST-ITEM @@ -138,26 +138,26 @@ invocation. .\" LIST-ITEM .It Fn man_parseln Parse a nil-terminated line of input. This line should not contain the -trailing newline. Returns 0 on failure, 1 on success. The input buffer +trailing newline. Returns 0 on failure, 1 on success. The input buffer .Fa buf is modified by this function. .\" LIST-ITEM .It Fn man_endparse -Signals that the parse is complete. Note that if +Signals that the parse is complete. Note that if .Fn man_endparse is called subsequent to .Fn man_node , the resulting tree is incomplete. Returns 0 on failure, 1 on success. .\" LIST-ITEM .It Fn man_node -Returns the first node of the parse. Note that if +Returns the first node of the parse. Note that if .Fn man_parseln or .Fn man_endparse return 0, the tree will be incomplete. .It Fn man_meta Returns the document's parsed meta-data. If this information has not -yet been supplied or +yet been supplied or .Fn man_parseln or .Fn man_endparse @@ -173,7 +173,7 @@ An array of string-ified token names. .El .\" SUBSECTION .Ss Abstract Syntax Tree -The +The .Nm functions produce an abstract syntax tree (AST) describing input in a regular form. It may be reviewed at any time with @@ -181,19 +181,19 @@ regular form. It may be reviewed at any time with however, if called before .Fn man_endparse , or after -.Fn man_endparse +.Fn man_endparse or .Fn man_parseln -fail, it may be incomplete. +fail, it may be incomplete. .\" PARAGRAPH .Pp This AST is governed by the ontological rules dictated in .Xr man 7 -and derives its terminology accordingly. +and derives its terminology accordingly. .\" PARAGRAPH .Pp -The AST is composed of +The AST is composed of .Vt struct man_node nodes with element, root and text types as declared by the @@ -206,9 +206,9 @@ and fields), its position in the tree (the .Va parent , .Va child , -.Va next +.Va next and -.Va prev +.Va prev fields) and some type-specific data. .\" PARAGRAPH .Pp @@ -234,10 +234,10 @@ next-lint scope as documented in .\" SECTION .Sh EXAMPLES The following example reads lines from stdin and parses them, operating -on the finished parse tree with +on the finished parse tree with .Fn parsed . Note that, if the last line of the file isn't newline-terminated, this -will truncate the file's last character (see +will truncate the file's last character (see .Xr fgetln 3 ) . Further, this example does not error-check nor free memory upon failure. .Bd -literal -offset "XXXX" @@ -273,5 +273,5 @@ man_free(man); .Sh AUTHORS The .Nm -utility was written by +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . @@ -25,15 +25,15 @@ .Sh DESCRIPTION The .Nm man -language was historically used to format +language was historically used to format .Ux manuals. This reference document describes its syntax, structure, and usage. .Pp -.Bf Em -Do not use +.Bf -emphasis +Do not use .Nm -to write your manuals. +to write your manuals. .Ef Use the .Xr mdoc 7 @@ -43,7 +43,7 @@ language, instead. An .Nm document follows simple rules: lines beginning with the control -character +character .Sq \&. are parsed for macros. Other lines are interpreted within the scope of prior macros: @@ -57,7 +57,7 @@ Other lines are interpreted within the current state. documents may contain only graphable 7-bit ASCII characters, the space character, and the tabs character. All manuals must have .Ux -line termination. +line termination. .Pp Blank lines are acceptable; where found, the output will assert a vertical space. @@ -71,8 +71,8 @@ subsequent word isn't off-set by whitespace. .\" SUB-SECTION .Ss Comments Anything following a -.Sq \e" -delimiter is considered a comment (unless the +.Sq \e" +delimiter is considered a comment (unless the .Sq \e itself has been escaped) and is ignored to the end of line. Furthermore, a macro line with only a control character @@ -82,7 +82,7 @@ optionally followed by whitespace, is ignored. .Ss Special Characters Special character sequences begin with the escape character .Sq \e -followed by either an open-parenthesis +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ @@ -114,7 +114,7 @@ macro describing the document's section and title. It may occur anywhere in the document, although conventionally, it appears as the first macro. .Pp -Beyond the +Beyond the .Sq \&.TH , at least one macro or text node must appear in the document. .\" SECTION @@ -129,11 +129,11 @@ and .Sq \&.\ \ \ \&PP are equivalent. .Pp -All +All .Nm macros follow the same structural rules: .Bd -literal -offset indent -\&.YO \(lBbody...\(rB +\&.YO \(lBbody...\(rB .Ed .Pp The @@ -141,7 +141,7 @@ The consists of zero or more arguments to the macro. .Pp .Nm -has a primitive notion of multi-line scope for the following macros: +has a primitive notion of multi-line scope for the following macros: .Sq \&.TM , .Sq \&.SM , .Sq \&.SB , @@ -152,23 +152,23 @@ has a primitive notion of multi-line scope for the following macros: .Sq \&.R , .Sq \&.B , .Sq \&.I , -.Sq \&.IR +.Sq \&.IR and .Sq \&.RI . When these macros are invoked without arguments, the subsequent line is considered a continuation of the macro. Thus: -.Bd -literal -offset indent -\&.RI +.Bd -literal -offset indent +\&.RI foo .Ed .Pp -is equivalent to +is equivalent to .Sq \&.RI foo . If two consecutive lines exhibit the latter behaviour, an error is raised. Thus, the following is not acceptable: -.Bd -literal -offset indent -\&.RI -\&.I +.Bd -literal -offset indent +\&.RI +\&.I Hello, world. .Ed .Pp @@ -178,7 +178,7 @@ macro is similar, but does not need an empty argument line to trigger the behaviour. .\" SECTION .Sh MACROS -This section contains a complete list of all +This section contains a complete list of all .Nm macros and corresponding number of arguments. .Pp @@ -232,7 +232,7 @@ for groff compatibility notes. .Sh AUTHORS The .Nm -utility was written by +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS @@ -34,13 +34,13 @@ .Sh DESCRIPTION The .Nm -utility formats +utility formats .Ux manual pages for display. The arguments are as follows: .Bl -tag -width Ds .\" ITEM .It Fl f Ns Ar option... -Override default compiler behaviour. See +Override default compiler behaviour. See .Sx Compiler Options for details. .\" ITEM @@ -63,9 +63,9 @@ Print version and exit. Configure warning messages. Use .Fl W Ns Ar all to print warnings, -.Fl W Ns Ar error +.Fl W Ns Ar error for warnings to be considered errors and cause utility -termination. Multiple +termination. Multiple .Fl W arguments may be comma-separated, such as .Fl W Ns Ar error,all . @@ -79,9 +79,9 @@ will halt with the first failed parse. .El .\" PARAGRAPH .Pp -By default, -.Nm -reads +By default, +.Nm +reads .Xr mdoc 7 or .Xr man 7 @@ -101,24 +101,24 @@ it's processed by .Nm according to the following rules: opening punctuation .Po -.Sq \&( , -.Sq \&[ , +.Sq \&( , +.Sq \&[ , and .Sq \&{ -.Pc +.Pc is not followed by a space; closing punctuation .Po -.Sq \&. , -.Sq \&, , -.Sq \&; , -.Sq \&: , -.Sq \&? , -.Sq \&! , -.Sq \&) , -.Sq \&] +.Sq \&. , +.Sq \&, , +.Sq \&; , +.Sq \&: , +.Sq \&? , +.Sq \&! , +.Sq \&) , +.Sq \&] and .Sq \&} -.Pc +.Pc is not preceded by whitespace. .Pp If the input is @@ -128,10 +128,10 @@ these rules are also applied to macro arguments when appropriate. White-space, in non-literal (normal) mode, is stripped from input and replaced on output by a single space. Thus, if you wish to preserve multiple spaces, they must be space-escaped -.Sq \e\ -or used in a literal display mode, e.g., -.Sq \&.Bd \-literal -in +.Sq \e\ +or used in a literal display mode, e.g., +.Sq \&.Bd \-literal +in .Xr mdoc 7 . .\" SUB-SECTION .Ss Input Formats @@ -149,26 +149,26 @@ respectively. The .Xr mdoc 7 format is .Em strongly -recommended; +recommended; .Xr man 7 should only be used for legacy manuals. .Pp A third option, .Fl m Ns Ar andoc , which is also the default, determines encoding on-the-fly: if the first -non-comment macro is +non-comment macro is .Sq \&.Dd or .Sq \&.Dt , -the +the .Xr mdoc 7 parser is used; otherwise, the .Xr man 7 parser is used. .Pp If multiple -files are specified with -.Fl m Ns Ar andoc , +files are specified with +.Fl m Ns Ar andoc , each has its file-type determined this way. If multiple files are specified and .Fl m Ns Ar doc @@ -222,11 +222,11 @@ Do not ignore unknown macros at the start of input lines. .It Fl f Ns Ar no-ign-chars Do not ignore disallowed characters. .It Fl f Ns Ar strict -Implies +Implies .Fl f Ns Ar no-ign-escape , -.Fl f Ns Ar no-ign-macro +.Fl f Ns Ar no-ign-macro and -.Fl f Ns Ar no-ign-chars . +.Fl f Ns Ar no-ign-chars . .El .\" PARAGRAPH .Pp @@ -247,19 +247,19 @@ To page manuals to the terminal: .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less .\" SECTION .Sh COMPATIBILITY -This section summarises +This section summarises .Nm -compatibility with +compatibility with .Xr groff 1 . .Pp .Bl -bullet -compact -.It +.It A list or display following .Sq \&.Ss does not assert a prior vertical break, just as it doesn't with .Sq \&.Sh . .It -The \-literal and \-unfilled +The \-literal and \-unfilled .Sq \&.Bd displays types are synonyms, as are \-filled and \-ragged. .It @@ -278,5 +278,5 @@ so double spaces following sentence closure are reduced to a single space .Sh AUTHORS The .Nm -utility was written by +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . @@ -13,7 +13,7 @@ .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" +.\" .Dd $Mdocdate$ .Dt MANUALS 7 .Os @@ -28,15 +28,15 @@ .Pp A system component's documentation describes the utility of that component, whether it's a device driver, an executable or, most -importantly, a game. +importantly, a game. .Pp -This document serves as a tutorial to writing -.Ux +This document serves as a tutorial to writing +.Ux documentation .Pq Dq manuals . .\" SECTION .Sh ENVIRONMENT -First, copy over the manual template from +First, copy over the manual template from .Pa /usr/share/misc/mdoc.template into your source directory. .Pp @@ -66,7 +66,7 @@ file and wire protocol formats games .It 7 tutorials, documents and papers -.It 8 +.It 8 administrator utilities .It 9 in-kernel routines @@ -95,7 +95,7 @@ other manuals by that same name before committing: .Pp .Dl % apropos myname .Pp -Manual files are named +Manual files are named .Pa myname.mysection , such as .Pa manuals.7 @@ -112,13 +112,13 @@ You may spell-check your work as follows: .Pp .Dl % deroff name.1 | spell .Pp -If +If .Xr ispell 1 is installed, it has a special mode for manuals: .Pp .Dl % ispell \-n name.1 .Pp -Use +Use .Xr cvs 1 or .Xr rcs 1 @@ -128,7 +128,7 @@ your document's date, use the following RCS tag for the date macro: .Dl \&.Dd $Mdocdate$ .\" SUBSECTION .Ss Viewing -mdoc documents may be paged to your terminal with +mdoc documents may be paged to your terminal with .Xr mandoc 1 . If you plan on distributing your work to systems without this tool, check it against @@ -139,7 +139,7 @@ check it against .Ed .\" SUBSECTION .Ss Automation -Consider adding your mdoc documents to +Consider adding your mdoc documents to .Xr make 1 Makefiles in order to automatically check your input: .Bd -literal -offset indent @@ -155,8 +155,8 @@ Your manual must have a license. It should be listed at the start of your document, just as in source code. .\" SECTION .Sh COMPOSITION -Manuals should -.Em always +Manuals should +.Em always be written in the .Xr mdoc 7 formatting language. @@ -167,7 +167,7 @@ Open the template you've copied into and begin editing. .\" SUBSECTION .Ss Language -.Bl -enum +.Bl -enum .It Use clear, concise language. Favour simplicity. .It @@ -187,15 +187,15 @@ symbols and so on), use the escapes dictated in .Ss Style The structure of the mdoc language makes it very hard to have any particular format style. Keep your lines under 72 characters in length. -If you must have long option lines, use +If you must have long option lines, use .Sq \&Oo/Oc . The same goes for function prototypes. .Em \&Do not -use +use .Sq \&Xo/Xc . Find another way to structure your line. .\" SUBSECTION -.Ss References +.Ss References Other components may be referenced with the .Sq \&Xr and @@ -13,7 +13,7 @@ .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" +.\" .Dd $Mdocdate$ .Dt MDOC 3 .Os @@ -50,7 +50,7 @@ .Sh DESCRIPTION The .Nm mdoc -library parses lines of +library parses lines of .Xr mdoc 7 input (and .Em only @@ -59,12 +59,12 @@ mdoc) into an abstract syntax tree (AST). .Pp In general, applications initiate a parsing sequence with .Fn mdoc_alloc , -parse each line in a document with +parse each line in a document with .Fn mdoc_parseln , close the parsing session with .Fn mdoc_endparse , operate over the syntax tree returned by -.Fn mdoc_node +.Fn mdoc_node and .Fn mdoc_meta , then free all allocated memory with @@ -77,13 +77,13 @@ sequence. See the section for a full example. .\" PARAGRAPH .Pp -This section further defines the +This section further defines the .Sx Types , -.Sx Functions +.Sx Functions and .Sx Variables available to programmers. Following that, the -.Sx Abstract Syntax Tree +.Sx Abstract Syntax Tree section documents the output tree. .\" SUBSECTION .Ss Types @@ -106,7 +106,7 @@ A set of message callbacks defined in .It Vt struct mdoc_node A parsed node. Defined in .Pa mdoc.h . -See +See .Sx Abstract Syntax Tree for details. .El @@ -119,8 +119,8 @@ Function descriptions follow: Allocates a parsing structure. The .Fa data pointer is passed to callbacks in -.Fa cb , -which are documented further in the header file. +.Fa cb , +which are documented further in the header file. The .Fa pflags arguments are defined in @@ -129,7 +129,7 @@ Returns NULL on failure. If non-NULL, the pointer must be freed with .Fn mdoc_free . .\" LIST-ITEM .It Fn mdoc_reset -Reset the parser for another parse routine. After its use, +Reset the parser for another parse routine. After its use, .Fn mdoc_parseln behaves as if invoked for the first time. If it returns 0, memory could not be allocated. @@ -140,26 +140,26 @@ invocation. .\" LIST-ITEM .It Fn mdoc_parseln Parse a nil-terminated line of input. This line should not contain the -trailing newline. Returns 0 on failure, 1 on success. The input buffer +trailing newline. Returns 0 on failure, 1 on success. The input buffer .Fa buf is modified by this function. .\" LIST-ITEM .It Fn mdoc_endparse -Signals that the parse is complete. Note that if +Signals that the parse is complete. Note that if .Fn mdoc_endparse is called subsequent to .Fn mdoc_node , the resulting tree is incomplete. Returns 0 on failure, 1 on success. .\" LIST-ITEM .It Fn mdoc_node -Returns the first node of the parse. Note that if +Returns the first node of the parse. Note that if .Fn mdoc_parseln or .Fn mdoc_endparse return 0, the tree will be incomplete. .It Fn mdoc_meta Returns the document's parsed meta-data. If this information has not -yet been supplied or +yet been supplied or .Fn mdoc_parseln or .Fn mdoc_endparse @@ -178,7 +178,7 @@ An array of string-ified token argument names. .El .\" SUBSECTION .Ss Abstract Syntax Tree -The +The .Nm functions produce an abstract syntax tree (AST) describing input in a regular form. It may be reviewed at any time with @@ -186,24 +186,24 @@ regular form. It may be reviewed at any time with however, if called before .Fn mdoc_endparse , or after -.Fn mdoc_endparse +.Fn mdoc_endparse or .Fn mdoc_parseln -fail, it may be incomplete. +fail, it may be incomplete. .\" PARAGRAPH .Pp This AST is governed by the ontological rules dictated in .Xr mdoc 7 -and derives its terminology accordingly. +and derives its terminology accordingly. .Qq In-line elements described in .Xr mdoc 7 -are described simply as +are described simply as .Qq elements . .\" PARAGRAPH .Pp -The AST is composed of +The AST is composed of .Vt struct mdoc_node nodes with block, head, body, element, root and text types as declared by the @@ -216,9 +216,9 @@ and fields), its position in the tree (the .Va parent , .Va child , -.Va next +.Va next and -.Va prev +.Va prev fields) and some type-specific data. .\" PARAGRAPH .Pp @@ -251,16 +251,16 @@ where capitalised non-terminals represent nodes. Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of the BLOCK production. These refer to punctuation marks. Furthermore, although a TEXT node will generally have a non-zero-length string, in -the specific case of +the specific case of .Sq \&.Bd \-literal , an empty line will produce a zero-length string. .\" SECTION .Sh EXAMPLES The following example reads lines from stdin and parses them, operating -on the finished parse tree with +on the finished parse tree with .Fn parsed . Note that, if the last line of the file isn't newline-terminated, this -will truncate the file's last character (see +will truncate the file's last character (see .Xr fgetln 3 ) . Further, this example does not error-check nor free memory upon failure. .Bd -literal -offset "XXXX" @@ -296,23 +296,23 @@ mdoc_free(mdoc); .Sh AUTHORS The .Nm -utility was written by +utility was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION .Sh CAVEATS .Bl -dash -compact .\" LIST-ITEM .It -The +The .Sq \&.Xc and .Sq \&.Xo macros aren't handled when used to span lines for the .Sq \&.It -macro. +macro. .\" LIST-ITEM .It -The +The .Sq \&.Bsx macro family doesn't yet understand version arguments. .\" LIST-ITEM @@ -321,9 +321,9 @@ If not given a value, the \-offset argument to .Sq \&.Bd and .Sq \&.Bl -should be the width of +should be the width of .Qq <string> ; -instead, a value of +instead, a value of .Li 10n is provided. .\" LIST-ITEM @@ -13,7 +13,7 @@ .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" +.\" .Dd $Mdocdate$ .Dt MDOC 7 .Os @@ -25,22 +25,22 @@ .Sh DESCRIPTION The .Nm mdoc -language is used to format -.Bx +language is used to format +.Bx .Ux manuals. In this reference document, we describe its syntax, structure, and usage. Our reference implementation is .Xr mandoc 1 . The .Sx COMPATIBILITY -section describes compatibility with +section describes compatibility with .Xr groff 1 . .\" PARAGRAPH------------ .Pp An .Nm document follows simple rules: lines beginning with the control -character +character .Sq \. are parsed for macros. Other lines are interpreted within the scope of prior macros: @@ -55,7 +55,7 @@ documents may contain only graphable 7-bit ASCII characters, the space character, and, in certain circumstances, the tab character. All manuals must have .Ux -line terminators. +line terminators. .\" SUB-SECTION---------------------- .Ss Comments Text following a @@ -87,9 +87,9 @@ Within a macro line, the following characters are reserved: .It \&? .Pq question .It \&! -.Pq exclamation +.Pq exclamation .It \&| -.Pq vertical bar +.Pq vertical bar .El .\" PARAGRAPH------------ .Pp @@ -98,13 +98,13 @@ Use of reserved characters is described in For general use in macro lines, these characters must either be escaped with a non-breaking space .Pq Sq \e& -or, if applicable, an appropriate escape sequence used. +or, if applicable, an appropriate escape sequence used. .\" SUB-SECTION---------------------- .Ss Special Characters Special characters may occur in both macro and free-form lines. Sequences begin with the escape character .Sq \e -followed by either an open-parenthesis +followed by either an open-parenthesis .Sq \&( for two-character sequences; an open-bracket .Sq \&[ @@ -112,10 +112,10 @@ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; or a single one-character sequence. See .Xr mandoc_char 1 -for a complete list. Examples include -.Sq \e(em -.Pq em-dash -and +for a complete list. Examples include +.Sq \e(em +.Pq em-dash +and .Sq \ee .Pq back-slash . .\" PARAGRAPH------------ @@ -137,7 +137,7 @@ In non-literal free-form lines, consecutive blocks of whitespace are pruned from input and added later in the output filter, if applicable: .Bd -literal -offset indent These spaces are pruned from input. -\&.Bd \-literal +\&.Bd \-literal These are not. \&.Ed .Ed @@ -149,7 +149,7 @@ arguments are quoted, whitespace within the quotes is retained. .Pp Blank lines are only permitted within literal contexts, as are lines containing only whitespace. Tab characters are only acceptable when -delimiting +delimiting .Sq \&Bl \-column or when in a literal context. .\" SUB-SECTION---------------------- @@ -158,17 +158,17 @@ Macro arguments may be quoted with a double-quote to group space-delimited terms or to retain blocks of whitespace. A quoted argument begins with a double-quote preceded by whitespace. The next double-quote not pair-wise adjacent to another double-quote terminates -the literal, regardless of surrounding whitespace. +the literal, regardless of surrounding whitespace. .\" PARAGRAPH------------ .Pp -This produces tokens +This produces tokens .Sq a" , .Sq b c , .Sq de , and .Sq fg" . Note that any quoted term, be it argument or macro, is indiscriminately -considered literal text. Thus, the following produces +considered literal text. Thus, the following produces .Sq \&Em a : .Bd -literal -offset indent \&.Em "Em a" @@ -180,14 +180,14 @@ In free-form mode, quotes are regarded as opaque text. .Sh MANUAL STRUCTURE Each .Nm -document must begin with a document prologue, containing, in order, +document must begin with a document prologue, containing, in order, .Sq \&Dd , .Sq \&Dt , and .Sq \&Os , then the NAME section containing at least one .Sq \&Nm -followed by +followed by .Sq \&Nd : .Bd -literal -offset indent \&.Dd $\&Mdocdate$ @@ -200,16 +200,16 @@ followed by .\" PARAGRAPH------------ .Pp Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, -but non-compulsory. +but non-compulsory. .\" SECTION--------------------------------------------- .Sh MACRO SYNTAX -Every line beginning with the control character +Every line beginning with the control character .Sq \. is processed for macros, two- or three-character sequences. .\" PARAGRAPH------------ .Pp The syntax of a macro depends on its classification. In this section, -.Sq \-arg +.Sq \-arg refers to macro arguments, which may be followed by zero or more .Sq parm parameters; @@ -222,7 +222,7 @@ closes it out. The .Em Callable column indicates that the macro may be called subsequent to the initial -line-macro. The +line-macro. The .Em Parsable column indicates whether the macro may be followed by further (ostensibly callable) macros. The @@ -235,8 +235,8 @@ contains bodies; only .Pq Sq \&Bf contains a head. .Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB \&.Yc .Ed .\" PARAGRAPH------------ @@ -255,20 +255,20 @@ contains a head. .\" SUB-SECTION---------------------- .Ss Block full-implicit Multi-line scope closed by end-of-file or implicitly by another macro. -All macros have bodies; some +All macros have bodies; some .Po -.Sq \&It \-bullet , -.Sq \-hyphen , +.Sq \&It \-bullet , +.Sq \-hyphen , .Sq \-dash , .Sq \-enum , -.Sq \-item +.Sq \-item .Pc -don't have heads, while +don't have heads, while .Sq \&It \-column may have multiple heads. .Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB -\(lBbody...\(rB +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB +\(lBbody...\(rB .Ed .\" PARAGRAPH------------ .Pp @@ -282,17 +282,17 @@ may have multiple heads. .\" SUB-SECTION---------------------- .Ss Block partial-explicit Like block full-explicit, but also with single-line scope. Each -has at least a body and, in limited circumstances, a head +has at least a body and, in limited circumstances, a head .Pq So \&Fo Sc , So \&Eo Sc -and/or tail +and/or tail .Pq So \&Ec Sc . .Bd -literal -offset indent -\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB -\(lBbody...\(rB -\&.Yc \(lBtail...\(rB +\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB +\(lBbody...\(rB +\&.Yc \(lBtail...\(rB \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ -\(lBbody...\(rB \&Yc \(lBtail...\(rB +\(lBbody...\(rB \&Yc \(lBtail...\(rB .Ed .\" PARAGRAPH------------ .Pp @@ -325,8 +325,8 @@ and/or tail .El .\" SUB-SECTION---------------------- .Ss Block partial-implicit -Like block full-implicit, but with single-line scope closed by -.Sx Reserved Characters +Like block full-implicit, but with single-line scope closed by +.Sx Reserved Characters or end of line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB @@ -349,12 +349,12 @@ or end of line. .El .\" SUB-SECTION---------------------- .Ss In-line -Closed by +Closed by .Sx Reserved Characters , end of line, fixed argument lengths, and/or subsequent macros. In-line macros have only text children. If a number (or inequality) of arguments is -.Pq n , +.Pq n , then the macro accepts an arbitrary number of arguments. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb @@ -443,13 +443,13 @@ then the macro accepts an arbitrary number of arguments. .\" SECTION--------------------------------------------- .Sh COMPATIBILITY This section documents compatibility with other roff implementations, at -this time limited to +this time limited to .Xr groff 1 . -The term +The term .Qq historic groff -refers to those versions before the +refers to those versions before the .Pa doc.tmac -file re-write +file re-write .Pq somewhere between 1.15 and 1.19 . .\" PARAGRAPH------------ .Pp @@ -461,13 +461,13 @@ standalone double-quote in formatted output. This idiosyncratic behaviour is no longer applicable. .\" LIST-ITEM .It -The +The .Sq \&sp macro does not accept negative numbers. .\" LIST-ITEM .It Some character sequences in groff are not handled depending on escape -style, e.g., +style, e.g., .Sq \e(ba and .Sq \e*(Ba @@ -485,7 +485,7 @@ some block-level macros) are now callable, conforming to the non-historic groff version. .\" LIST-ITEM .It -The vertical bar +The vertical bar .Sq \(ba made historic groff .Qq go orbital @@ -504,7 +504,7 @@ syntax where column widths may be preceded by other arguments (instead of proceeded) is not supported. .\" LIST-ITEM .It -The +The .Sq \&At macro only accepts a single parameter. .\" LIST-ITEM @@ -521,7 +521,7 @@ it will obviously not render the subsequent sequence. Even newer versions of groff seem to dither on this. .\" LIST-ITEM .It -In groff, the +In groff, the .Sq \&Fo macro only produces the first parameter. This is no longer the case. .El @@ -533,7 +533,7 @@ macro only produces the first parameter. This is no longer the case. .Sh AUTHORS The .Nm -reference was written by +reference was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION--------------------------------------------- .Sh CAVEATS @@ -544,7 +544,7 @@ There are many ambiguous parts of mdoc. .\" LIST-ITEM .It .Sq \&Fa -should be +should be .Sq \&Va as function arguments are variables. .\" LIST-ITEM @@ -567,7 +567,7 @@ variable name and optional, preceding type. .It .Sq \&Fd is ambiguous. It's commonly used to indicate an include file in the -synopsis section. +synopsis section. .Sq \&In should be used, instead. .\" LIST-ITEM @@ -579,7 +579,7 @@ argument to makes sense. The remaining ones should be removed. .\" LIST-ITEM .It -The +The .Sq \&Xo and .Sq \&Xc @@ -594,9 +594,9 @@ render when formatting the manual page. .It A .Sq \&Lx -should be provided for Linux (\(`a la +should be provided for Linux (\(`a la .Sq \&Ox , -.Sq \&Nx +.Sq \&Nx etc.). .\" LIST-ITEM .It @@ -605,7 +605,7 @@ There's no way to refer to references in blocks. .\" LIST-ITEM .It -The \-split and \-nosplit arguments to +The \-split and \-nosplit arguments to .Sq \&An are inane. .El |