[Fwd: work towards mdoc(7) installation]

[Fwd: work towards mdoc(7) installation]

[Kristaps Dzonsons]

Hi,

This is a forwarded copy of mdoc(7) updates provided by schwarze@.  Just
getting things moving...

-------- Original Message --------
[snip]

This patch does the following:
 * rewrite the following descriptions to make them shorter and
   easier to understand: .An, .Bd, .Bk, .Bl, .Ex
 * correct "parsable" to "parsed", which is both the traditional
   terminus technicus and more to the point
 * correct a factual error in .At: .At V is not "system version",
   but "system five"
 * fix a few cases were arguments were formatted with Fl or Cm
   instead of Ar
 * remove a sentence that doesn't seem to make sense:
   "This produces tokens..."
 * change a couple of descriptions from indicative to infinitive
   form (e.g. begins -> begin)
 * improve a few examples
 * add a few missing cross references
 * several minor wording tweaks
 * reuse a few patches committed to man(7)


Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.140
diff -u -p -r1.140 mdoc.7
--- mdoc.7      19 Jul 2010 21:59:48 -0000      1.140
+++ mdoc.7      23 Jul 2010 22:38:23 -0000
@@ -93,10 +93,10 @@ Within a macro line, the following chara
 .Pp
 Use of reserved characters is described in
 .Sx MACRO SYNTAX .
-For general use in macro lines, these characters must either be escaped
+For general use in macro lines, these characters can 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 can be used.
 .Ss Special Characters
 Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character
@@ -180,24 +180,18 @@ within literal contexts.
 In macro lines, whitespace delimits arguments and is discarded.
 If arguments are quoted, whitespace within the quotes is retained.
 .Ss Quotation
-Macro arguments may be quoted with a double-quote to group
+Macro arguments may be quoted with double-quotes 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.
 .Pp
-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.
+Note that any quoted text, even if it would cause a macro invocation
+when unquoted, is considered literal text.
 Thus, the following produces
-.Sq \&Em a :
+.Sq Op "Fl a" :
 .Bd -literal -offset indent
-\&.Em "Em a"
+\&.Op "Fl a"
 .Ed
 .Pp
 In free-form mode, quotes are regarded as opaque text.
@@ -304,12 +298,12 @@ A well-formed
 document consists of a document prologue followed by one or more
 sections.
 .Pp
-The prologue, which consists of (in order) the
+The prologue, which consists of the
 .Sx \&Dd ,
 .Sx \&Dt ,
 and
 .Sx \&Os
-macros, is required for every document.
+macros in that order, is required for every document.
 .Pp
 The first section (sections are denoted by
 .Sx \&Sh )
@@ -373,13 +367,13 @@ document are conventionally ordered as t
 Sections should be composed as follows:
 .Bl -ohang -offset Ds
 .It Em NAME
-The name(s) and a short description of the documented material.
+The name(s) and a one-line description of the documented material.
 The syntax for this as follows:
 .Bd -literal -offset indent
 \&.Nm name0
 \&.Nm name1
 \&.Nm name2
-\&.Nd a short description
+\&.Nd a one-line description
 .Ed
 .Pp
 The
@@ -472,7 +466,7 @@ with the text immediately following the
 .Sx \&Nm
 macro, up to the next
 .Sx \&Nm ,
-.Sx \&Sx ,
+.Sx \&Sh ,
 or
 .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.
@@ -503,14 +497,17 @@ It documents the return values of functi
 See
 .Sx \&Rv .
 .It Em ENVIRONMENT
-Documents any usages of environment variables, e.g.,
-.Xr environ 7 .
+Lists the environment variables used by the utility,
+and explains the syntax and semantics of their values.
+The
+.Xr environ 7
+manual provides examples of typical content and formatting.
 .Pp
 See
 .Sx \&Ev .
 .It Em FILES
 Documents files used.
-It's helpful to document both the file and a short description of how
+It's helpful to document both the file name and a short description of how
 the file is used (created, modified, etc.).
 .Pp
 See
@@ -568,21 +565,22 @@ The history of any manual without a
 section should be described in this section.
 .It Em AUTHORS
 Credits to authors, if applicable, should appear in this section.
-Authors should generally be noted by both name and an e-mail address.
+Authors should generally be noted by both name and email address.
 .Pp
 See
 .Sx \&An .
 .It Em CAVEATS
-Explanations of common misuses and misunderstandings should be explained
+Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
-Extant bugs should be described in this section.
+Known bugs, limitations and work-arounds should be described
+in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.
 .El
 .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a
-control character ,
+control character,
 .Sq \&. ,
 at the beginning of the line.
 An arbitrary amount of whitespace may sit between the control character
@@ -615,10 +613,10 @@ produces
 .Sq Fl \&Sh .
 .Pp
 The
-.Em Parsable
+.Em Parsed
 column indicates whether the macro may be followed by further
 (ostensibly callable) macros.
-If a macro is not parsable, subsequent macro invocations on the line
+If a macro is not parsed, subsequent macro invocations on the line
 will be interpreted as opaque text.
 .Pp
 The
@@ -635,8 +633,8 @@ contains a head.
 \&.Yc
 .Ed
 .Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX"
"closed by XXX"
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX"
"closed by XXX"
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ed
 .It Sx \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ef
 .It Sx \&Bk  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Ek
@@ -658,7 +656,9 @@ All macros have bodies; some
 .Pc
 don't have heads; only one
 .Po
-.Sx \&It Fl column
+.Sx \&It
+in
+.Sx \&Bl Fl column
 .Pc
 has multiple heads.
 .Bd -literal -offset indent
@@ -666,8 +666,8 @@ has multiple heads.
 \(lBbody...\(rB
 .Ed
 .Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX"
"closed by XXXXXXXXXXX"
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX"
"closed by XXXXXXXXXXX"
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&It  Ta    \&No     Ta    Yes      Ta    closed by Sx \&It , Sx
\&El
 .It Sx \&Nd  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Nm  Ta    \&No     Ta  Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx
\&Ss
@@ -702,8 +702,8 @@ and/or tail
 \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed
 .Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact
-offset indent
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact
-offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
 .It Sx \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Ao
 .It Sx \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Ac
 .It Sx \&Bc  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Bo
@@ -737,8 +737,8 @@ or end of line.
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed
 .Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
-.It Em Macro Ta Em Callable Ta Em Parsable
+.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed
 .It Sx \&Aq  Ta    Yes      Ta    Yes
 .It Sx \&Bq  Ta    Yes      Ta    Yes
 .It Sx \&Brq Ta    Yes      Ta    Yes
@@ -778,8 +778,8 @@ then the macro accepts an arbitrary numb
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed
 .Pp
-.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact
-offset indent
-.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset
indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
 .It Sx \&%A  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%B  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%C  Ta    \&No     Ta    \&No     Ta    >0
@@ -933,60 +933,49 @@ Volume number of an
 .Sx \&Rs
 block.
 .Ss \&Ac
-Closes an
+Close an
 .Sx \&Ao
 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.
+Memory address.  Do not use this for postal addresses.
 .Pp
 Examples:
 .D1 \&.Ad [0,$]
 .D1 \&.Ad 0x00000000
 .Ss \&An
 Author name.
-This macro may alternatively accepts the following arguments, although
-these may not be specified along with a parameter:
+Requires either the name of an author or one of the following arguments:
 .Pp
 .Bl -tag -width "-nosplitX" -offset indent -compact
 .It Fl split
-Renders a line break before each author listing.
+Start a new output line before each subsequent invocation of
+.Sx \&An .
 .It Fl nosplit
 The opposite of
 .Fl split .
 .El
 .Pp
+The default is
+.Fl nosplit .
+The effect of selecting either of the
+.Fl split
+modes ends at the beginning of the
+.Em AUTHORS
+section.
 In the
 .Em AUTHORS
-section, the default is not to split the first author
-listing, but all subsequent author listings, whether or not they're
-interspersed by other macros or text, are split.
-Thus, specifying
+section, the default is
+.Fl nosplit
+for the first author listing and
 .Fl split
-will cause the first listing also to be split.
-If not in the
-.Em AUTHORS
-section, the default is not to split.
+for all other author listings.
 .Pp
 Examples:
 .D1 \&.An -nosplit
-.D1 \&.An J. D. Ullman .
-.Pp
-.Em Remarks :
-the effects of
-.Fl split
-or
-.Fl nosplit
-are re-set when entering the
-.Em AUTHORS
-section, so if one specifies
-.Sx \&An Fl nosplit
-in the general document body, it must be re-specified in the
-.Em AUTHORS
-section.
+.D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
 .Ss \&Ao
-Begins a block enclosed by angled brackets.
+Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 .Pp
 Examples:
@@ -1002,7 +991,7 @@ form of a function.
 Examples:
 .D1 \&.Fn execve \&Ap d
 .Ss \&Aq
-Encloses its arguments in angled brackets.
+Encloses its arguments in angle brackets.
 .Pp
 Examples:
 .D1 \&.Fl -key= \&Ns \&Aq \&Ar val
@@ -1022,7 +1011,7 @@ See also
 .Ss \&Ar
 Command arguments.
 If an argument is not provided, the string
-.Dq file ...
+.Dq file ...\&
 is used as a default.
 .Pp
 Examples:
@@ -1031,18 +1020,18 @@ Examples:
 .D1 \&.Ar arg1 , arg2 .
 .Ss \&At
 Formats an AT&T version.
-Accepts at most one parameter:
+Accepts one optional argument:
 .Pp
 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
 .It Cm v[1-7] | 32v
 A version of
 .At .
 .It Cm V[.[1-4]]?
-A system version of
-.At .
+A version of
+.At V .
 .El
 .Pp
-Note that these parameters do not begin with a hyphen.
+Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:
 .D1 \&.At
@@ -1058,83 +1047,93 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Bc
-Closes a
+Close a
 .Sx \&Bo
 block.
 Does not have any tail arguments.
 .Ss \&Bd
-Begins a display block.
+Begin a display block.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Bd
-.Fl type
+.Fl Ns Ar type
 .Op Fl offset Ar width
 .Op Fl compact
 .Ed
 .Pp
-A display is collection of macros or text which may be collectively
-offset or justified in a manner different from that
-of the enclosing context.
-By default, the block is preceded by a vertical space.
+Display blocks are used to select a different indentation and
+justification than the one used by the surrounding text.
+They may contain both macro lines and free-form text lines.
+By default, a display block is preceded by a vertical space.
 .Pp
-Each display is associated with a type, which must be one of the
-following arguments:
-.Bl -tag -width 12n -offset indent
-.It Fl ragged
-Only left-justify the block.
-.It Fl unfilled
-Do not justify the block at all.
+The
+.Ar type
+must be one of the following:
+.Bl -tag -width 13n -offset indent
+.It Fl centered
+Centre-justify each line.
+Using this display type is not recommended; many
+.Nm
+implementations render it poorly.
 .It Fl filled
 Left- and right-justify the block.
 .It Fl literal
-Alias for
-.Fl unfilled .
-.It Fl centered
-Centre-justify each line.
+Do not justify the block at all.
+Preserve white space as it appears in the input.
+.It Fl ragged
+Only left-justify the block.
+.It Fl unfilled
+An alias for
+.Fl literal .
 .El
 .Pp
-The type must be provided first.
-Secondary arguments are as follows:
-.Bl -tag -width 12n -offset indent
-.It Fl offset Ar val
-Offset by the value of
-.Ar val ,
-which is interpreted as one of the following, specified in order:
+The
+.Ar type
+must be provided first.
+Additional arguments may follow:
+.Bl -tag -width 13n -offset indent
+.It Fl offset Ar width
+Indent the display by the
+.Ar width ,
+which may be one of the following:
 .Bl -item
 .It
-As one of the pre-defined strings
-.Ar indent ,
+One of the pre-defined strings
+.Cm indent ,
 the width of standard indentation;
-.Ar indent-two ,
+.Cm indent-two ,
 twice
-.Ar indent ;
-.Ar left ,
+.Cm indent ;
+.Cm left ,
 which has no effect;
-.Ar right ,
-which justifies to the right margin; and
-.Ar center ,
+.Cm right ,
+which justifies to the right margin; or
+.Cm center ,
 which aligns around an imagined centre axis.
 .It
-As a precalculated width for a named macro.
+A macro invocation, which selects a predefined width
+associated with that macro.
 The most popular is the imaginary macro
 .Ar \&Ds ,
 which resolves to
-.Ar 6n .
+.Sy 6n .
 .It
-As a scaling unit following the syntax described in
+A width using the syntax described in
 .Sx Scaling Widths .
 .It
-As the calculated string length of the opaque string.
+An arbitrary string, which indents by the length of this string.
 .El
 .Pp
-If not provided an argument, it will be ignored.
+When the argument is missing,
+.Fl offset
+is ignored.
 .It Fl compact
-Do not assert a vertical space before the block.
+Do not assert vertical space before the display.
 .El
 .Pp
 Examples:
 .Bd -literal -offset indent
-\&.Bd \-unfilled \-offset two-indent \-compact
+\&.Bd \-literal \-offset indent \-compact
    Hello       world.
 \&.Ed
 .Ed
@@ -1175,21 +1174,22 @@ is encountered.
 See also
 .Sx \&Li ,
 .Sx \&Ef ,
+.Sx \&Em ,
 and
 .Sx \&Sy .
 .Ss \&Bk
-Begins a collection of macros or text not breaking the line.
-Its syntax is as follows:
+Keep the output generated from each macro input line together
+on one single output line.
+Line breaks in free-form text lines are unaffected.
+The syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Bk Fl words
 .Pp
-Subsequent arguments are ignored.
 The
 .Fl words
-argument is required.
+argument is required; additional arguments are ignored.
 .Pp
-Each line within a keep block is kept intact, so the following example
-will not break within each
+The following example will not break within each
 .Sx \&Op
 macro line:
 .Bd -literal -offset indent
@@ -1202,124 +1202,128 @@ macro line:
 Be careful in using over-long lines within a keep block!
 Doing so will clobber the right margin.
 .Ss \&Bl
-Begins a list composed of one or more list entries.
-Its syntax is as follows:
+Begin a list.
+Lists consist of items started by the
+.Sx \&It
+macro, containing a head or a body or both.
+The list syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Bl
-.Fl type
+.Fl Ns Ar type
 .Op Fl width Ar val
 .Op Fl offset Ar val
 .Op Fl compact
 .Op HEAD ...
 .Ed
 .Pp
-A list is associated with a type, which is a required argument.
-Other arguments are
-.Fl width ,
-defined per-type as accepting a literal or
-.Sx Scaling Widths
-value;
-.Fl offset ,
-also accepting a literal or
+The list
+.Ar type
+is mandatory and must be specified first.
+The
+.Fl width
+and
+.Fl offset
+arguments accept
 .Sx Scaling Widths
-value setting the list's global offset; and
-.Fl compact ,
-suppressing the default vertical space printed before each list entry.
-A list entry is specified by the
-.Sx \&It
-macro, which consists of a head and optional body (depending on the list
-type).
+or use the length of the given string.
+The
+.Fl offset
+is a global indentation for the whole list, affecting both item heads
+and bodies.
+For those list types supporting it, the
+.Fl width
+argument requests an additional indentation of item bodies,
+to be added to the
+.Fl offset .
+Unless the
+.Fl compact
+argument is specified, list entries are separated by vertical space.
+.Pp
 A list must specify one of the following list types:
 .Bl -tag -width 12n -offset indent
 .It Fl bullet
-A list offset by a bullet.
-The head of list entries must be empty.
-List entry bodies are positioned after the bullet.
-The
+No item heads can be specified, but a bullet will be printed at the head
+of each item.
+Item bodies start on the same output line as the bullet
+and are indented according to the
 .Fl width
-argument varies the width of list bodies' left-margins.
+argument.
 .It Fl column
 A columnated list.
 The
 .Fl width
-argument has no effect.
-The number of columns is specified as parameters to the
-.Sx \&Bl
-macro.
-These dictate the width of columns either as
+argument has no effect; instead, each argument specifies the width
+of one column, using either the
 .Sx Scaling Widths
-or literal text.
-If the initial macro of a
+syntax or the string length of the argument.
+If the first line of the body of a
 .Fl column
 list is not an
-.Sx \&It ,
-an
 .Sx \&It
-context spanning each line is implied until an
+macro line,
 .Sx \&It
-line macro is encountered, at which point list bodies are interpreted as
+contexts spanning one input line each are implied until an
+.Sx \&It
+macro line is encountered, at which point items start being interpreted as
 described in the
 .Sx \&It
 documentation.
 .It Fl dash
-A list offset by a dash (hyphen).
-The head of list entries must be empty.
-List entry bodies are positioned past the dash.
-The
-.Fl width
-argument varies the width of list bodies' left-margins.
+Like
+.Fl bullet ,
+except that dashes are used in place of bullets.
 .It Fl diag
 Like
 .Fl inset ,
-but with additional formatting to the head.
-The
-.Fl width
-argument varies the width of list bodies' left-margins.
+except that item heads are not parsed for macro invocations.
+.\" but with additional formatting to the head.
 .It Fl enum
-An enumerated list offset by the enumeration from 1.
-The head of list entries must be empty.
-List entry bodies are positioned after the enumeration.
-The
-.Fl width
-argument varies the width of list bodies' left-margins.
+A numbered list.
+Formatted like
+.Fl bullet ,
+except that cardinal numbers are used in place of bullets,
+starting at 1.
 .It Fl hang
 Like
 .Fl tag ,
-but instead of list bodies positioned after the head, they trail the
-head text.
-The
-.Fl width
-argument varies the width of list bodies' left-margins.
+except that the first lines of item bodies are not indented, but follow
+the item heads like in
+.Fl inset
+lists.
 .It Fl hyphen
 Synonym for
 .Fl dash .
 .It Fl inset
-List bodies follow the list head.
-The
+Item bodies follow items heads on the same line, using normal inter-word
+spacing.
+Bodies are not indented, and the
 .Fl width
 argument is ignored.
 .It Fl item
-This produces blocks of text.
-The head of list entries must be empty.
-The
+No item heads can be specified, and none are printed.
+Bodies are not indented, and the
 .Fl width
 argument is ignored.
 .It Fl ohang
-List bodies are positioned on the line following the head.
+Item bodies start on the line following item heads and are not indented.
 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
+Item bodies are indented according to the
 .Fl width
 argument.
+When an item head fits inside the indentation, the item body follows
+this head on the same output line.
+Otherwise, the body starts on the output line following the head.
 .El
 .Pp
 See also
+.Sx \&El
+and
 .Sx \&It .
 .Ss \&Bo
-Begins a block enclosed by square brackets.
+Begin a block enclosed by square brackets.
 Does not have any head arguments.
 .Pp
 Examples:
@@ -1347,12 +1351,12 @@ and
 See also
 .Sx \&Bo .
 .Ss \&Brc
-Closes a
+Close a
 .Sx \&Bro
 block.
 Does not have any tail arguments.
 .Ss \&Bro
-Begins a block enclosed by curly braces.
+Begin a block enclosed by curly braces.
 Does not have any head arguments.
 .Pp
 Examples:
@@ -1409,7 +1413,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Cd
-Configuration declaration.
+Kernel configuration declaration.
 This denotes strings accepted by
 .Xr config 8 .
 .Pp
@@ -1446,13 +1450,15 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
-Start a debugging context.
-This macro is parsed, but generally ignored.
+Switch debugging mode.
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Db Cm on | off
+.Pp
+This macro is ignored by
+.Xr mandoc 1 .
 .Ss \&Dc
-Closes a
+Close a
 .Sx \&Do
 block.
 Does not have any tail arguments.
@@ -1463,11 +1469,11 @@ This is the mandatory first macro of any
 manual.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Ar date
 .Pp
 The
-.Cm date
-field may be either
+.Ar date
+may be either
 .Ar $\&Mdocdate$ ,
 which signifies the current manual revision date dictated by
 .Xr cvs 1 ,
@@ -1498,7 +1504,7 @@ See also
 and
 .Sx \&D1 .
 .Ss \&Do
-Begins a block enclosed by double quotes.
+Begin a block enclosed by double quotes.
 Does not have any head arguments.
 .Pp
 Examples:
@@ -1536,22 +1542,22 @@ Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Dt
 .Oo
-.Cm title
+.Ar title
 .Oo
-.Cm section
-.Op Cm volume | arch
+.Ar section
+.Op Ar volume | arch
 .Oc
 .Oc
 .Ed
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
-.It Cm title
+.It Ar title
 The document's title (name), defaulting to
 .Dq UNKNOWN
 if unspecified.
 It should be capitalised.
-.It Cm section
+.It Ar section
 The manual section.
 This may be one of
 .Ar 1
@@ -1590,7 +1596,7 @@ or
 It should correspond to the manual's filename suffix and defaults to
 .Dq 1
 if unspecified.
-.It Cm volume
+.It Ar volume
 This overrides the volume inferred from
 .Ar section .
 This field is optional, and if specified, must be one of
@@ -1619,10 +1625,10 @@ This field is optional, and if specified
 or
 .Ar CON
 .Pq contributed manuals .
-.It Cm arch
+.It Ar arch
 This specifies a specific relevant architecture.
 If
-.Cm volume
+.Ar volume
 is not provided, it may be used in its place, else it may be used
 subsequent that.
 It, too, is optional.
@@ -1697,10 +1703,10 @@ Close a scope started by
 .Sx \&Eo .
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Ec Op Cm TERM
+.D1 Pf \. Sx \&Ec Op Ar TERM
 .Pp
 The
-.Cm TERM
+.Ar TERM
 argument is used as the enclosure tail, for example, specifying \e(rq
 will emulate
 .Sx \&Dc .
@@ -1708,13 +1714,13 @@ will emulate
 End a display context started by
 .Sx \&Bd .
 .Ss \&Ef
-Ends a font mode context started by
+End a font mode context started by
 .Sx \&Bf .
 .Ss \&Ek
-Ends a keep context started by
+End a keep context started by
 .Sx \&Bk .
 .Ss \&El
-Ends a list context started by
+End a list context started by
 .Sx \&Bl .
 .Pp
 See also
@@ -1736,15 +1742,16 @@ See also
 and
 .Sx \&Li .
 .Ss \&En
-This macro is obsolete and not implemented.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Eo Op Cm TERM
+.D1 Pf \. Sx \&Eo Op Ar TERM
 .Pp
 The
-.Cm TERM
+.Ar TERM
 argument is used as the enclosure head, for example, specifying \e(lq
 will emulate
 .Sx \&Do .
@@ -1767,16 +1774,16 @@ Examples:
 .D1 \&.Ev DISPLAY
 .D1 \&.Ev PATH
 .Ss \&Ex
-Inserts text regarding a utility's exit value.
-This macro must consist of the
-.Fl std
-argument followed by an optional
-.Ar utility .
-If
+Insert a standard sentence regarding exit values.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ex Fl std Op Ar utility
+.Pp
+When
 .Ar utility
-is not provided, the document's name as stipulated in
+is not specified, the document's name set by
 .Sx \&Nm
-is provided.
+is used.
 .Pp
 See also
 .Sx \&Rv .
@@ -1812,7 +1819,7 @@ Examples:
 See also
 .Sx \&Fo .
 .Ss \&Fc
-Ends a function context started by
+End a function context started by
 .Sx \&Fo .
 .Ss \&Fd
 Historically used to document include files.
@@ -1963,7 +1970,7 @@ In the
 section (only if invoked as the line macro), the first argument is
 preceded by
 .Dq #include ,
-the arguments is enclosed in angled braces.
+the arguments is enclosed in angle brackets.
 .Pp
 Examples:
 .D1 \&.In sys/types
@@ -2217,7 +2224,7 @@ See also
 and
 .Sx \&Ux .
 .Ss \&Oc
-Closes multi-line
+Close multi-line
 .Sx \&Oo
 context.
 .Ss \&Oo
@@ -2351,12 +2358,12 @@ See also
 and
 .Sx \&Qo .
 .Ss \&Re
-Closes a
+Close an
 .Sx \&Rs
 block.
 Does not have any tail arguments.
 .Ss \&Rs
-Begins a bibliographic
+Begin a bibliographic
 .Pq Dq reference
 block.
 Does not have any head arguments.

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: [Fwd: work towards mdoc(7) installation]

[Kristaps Dzonsons]

> This is a forwarded copy of mdoc(7) updates provided by schwarze@.  Just
> getting things moving...
> 
> -------- Original Message --------
> [snip]
> 
> This patch does the following:
>  * rewrite the following descriptions to make them shorter and
>    easier to understand: .An, .Bd, .Bk, .Bl, .Ex
>  * correct "parsable" to "parsed", which is both the traditional
>    terminus technicus and more to the point
>  * correct a factual error in .At: .At V is not "system version",
>    but "system five"
>  * fix a few cases were arguments were formatted with Fl or Cm
>    instead of Ar
>  * remove a sentence that doesn't seem to make sense:
>    "This produces tokens..."
>  * change a couple of descriptions from indicative to infinitive
>    form (e.g. begins -> begin)
>  * improve a few examples
>  * add a few missing cross references
>  * several minor wording tweaks
>  * reuse a few patches committed to man(7)

Note that I've committed this already (plus a new-sentence fix noted by
Jason McIntyre), so please use the modified version if you have changes
to make.

Thanks,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: work towards mdoc(7) installation

[Ingo Schwarze]

Hi,

i have checked the old mdoc.7 that we have in the OpenBSD tree
and found very little worth keeping.  This is all i came up with.

OK to commit?

Yours,
  Ingo


--- mdoc.7	Sun Aug  1 18:52:23 2010
+++ mdoc.7.new	Sun Aug  1 18:30:15 2010
@@ -560,11 +560,9 @@
 See
 .Sx \&St .
 .It Em HISTORY
-The history of any manual without a
-.Em STANDARDS
-section should be described in this section.
+A brief history of the subject, including where support first appeared.
 .It Em AUTHORS
-Credits to authors, if applicable, should appear in this section.
+Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
 .Pp
 See
@@ -2257,7 +2255,7 @@
 file.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system Op Cm version
 .Pp
 The optional
 .Cm system
@@ -2859,8 +2857,10 @@
 older groff did nothing.
 .El
 .Sh SEE ALSO
+.Xr man 1 ,
 .Xr mandoc 1 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
+.Xr mdoc.samples 7
 .Sh AUTHORS
 The
 .Nm
--- man.7	31 Jul 2010 21:51:33 -0000	1.5
+++ man.7.new	1 Aug 2010 17:17:56 -0000
@@ -338,11 +338,9 @@
 .Em HISTORY
 section should be used.
 .It Em HISTORY
-The history of any manual without a
-.Em STANDARDS
-section should be described in this section.
+A brief history of the subject, including where support first appeared.
 .It Em AUTHORS
-Credits to authors, if applicable, should appear in this section.
+Credits to the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.
 .It Em CAVEATS
 Common misuses and misunderstandings should be explained
@@ -939,8 +937,10 @@
 control character.
 .El
 .Sh SEE ALSO
+.Xr man 1 ,
 .Xr mandoc 1 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
+.Xr mdoc 7
 .Sh HISTORY
 The
 .Nm
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: work towards mdoc(7) installation

[Jason McIntyre]

On Sun, Aug 01, 2010 at 07:20:46PM +0200, Ingo Schwarze wrote:
> Hi,
> 
> i have checked the old mdoc.7 that we have in the OpenBSD tree
> and found very little worth keeping.  This is all i came up with.
> 
> OK to commit?
> 
> Yours,
>   Ingo
> 

looks ok to me.
jmc

> 
> --- mdoc.7	Sun Aug  1 18:52:23 2010
> +++ mdoc.7.new	Sun Aug  1 18:30:15 2010
> @@ -560,11 +560,9 @@
>  See
>  .Sx \&St .
>  .It Em HISTORY
> -The history of any manual without a
> -.Em STANDARDS
> -section should be described in this section.
> +A brief history of the subject, including where support first appeared.
>  .It Em AUTHORS
> -Credits to authors, if applicable, should appear in this section.
> +Credits to the person or persons who wrote the code and/or documentation.
>  Authors should generally be noted by both name and email address.
>  .Pp
>  See
> @@ -2257,7 +2255,7 @@
>  file.
>  Its syntax is as follows:
>  .Pp
> -.D1 Pf \. Sx \&Os Op Cm system
> +.D1 Pf \. Sx \&Os Op Cm system Op Cm version
>  .Pp
>  The optional
>  .Cm system
> @@ -2859,8 +2857,10 @@
>  older groff did nothing.
>  .El
>  .Sh SEE ALSO
> +.Xr man 1 ,
>  .Xr mandoc 1 ,
> -.Xr mandoc_char 7
> +.Xr mandoc_char 7 ,
> +.Xr mdoc.samples 7
>  .Sh AUTHORS
>  The
>  .Nm
> --- man.7	31 Jul 2010 21:51:33 -0000	1.5
> +++ man.7.new	1 Aug 2010 17:17:56 -0000
> @@ -338,11 +338,9 @@
>  .Em HISTORY
>  section should be used.
>  .It Em HISTORY
> -The history of any manual without a
> -.Em STANDARDS
> -section should be described in this section.
> +A brief history of the subject, including where support first appeared.
>  .It Em AUTHORS
> -Credits to authors, if applicable, should appear in this section.
> +Credits to the person or persons who wrote the code and/or documentation.
>  Authors should generally be noted by both name and email address.
>  .It Em CAVEATS
>  Common misuses and misunderstandings should be explained
> @@ -939,8 +937,10 @@
>  control character.
>  .El
>  .Sh SEE ALSO
> +.Xr man 1 ,
>  .Xr mandoc 1 ,
> -.Xr mandoc_char 7
> +.Xr mandoc_char 7 ,
> +.Xr mdoc 7
>  .Sh HISTORY
>  The
>  .Nm
> --
>  To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv