Strip empty-line markers from mdoc.template and its mdoc.7 embedded form

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 2795a785ed816554edc4b4a6c5c01d5085e05fbf..184ccf737fcdbabe32a091c02ff00f026923c6e6 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.103 2010/05/14 15:02:03 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.113 2010/06/02 12:01:00 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: May 14 2010 $
+.Dd $Mdocdate: June 2 2010 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -301,10 +301,18 @@ When composing a manual, make sure that your sentences end at the end of
 a line.
 By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,
 a line.
 By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,

-or question mark.
+or question mark followed by zero or more non-sentence closing
+delimiters (
+.Ns Sq \&) ,
+.Sq \&] ,
+.Sq \&' ,
+.Sq \&" ) .

 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at
 .Pp
 The proper spacing is also intelligently preserved if a sentence ends at

-the boundary of a macro line.
+the boundary of a macro line, e.g.,
+.Pp
+.D1 \&Xr mandoc 1 \.
+.D1 \&Fl T \&Ns \&Cm ascii \.

 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm
 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm


@@ -335,18 +343,15 @@ file:
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os

-\&.

 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here

-\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q The next is for sections 2, 3, & 9 only.

 \&.\e\*q .Sh LIBRARY
 \&.\e\*q .Sh LIBRARY

-\&.

 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Ar
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Ar

-\&.

 \&.Sh DESCRIPTION
 The
 \&.Nm
 \&.Sh DESCRIPTION
 The
 \&.Nm


@@ -401,7 +406,7 @@ and
 .Sx \&Nd .
 .It Em LIBRARY
 The name of the library containing the documented material, which is
 .Sx \&Nd .
 .It Em LIBRARY
 The name of the library containing the documented material, which is

-assumed to be a function in a section 2 or 3 manual.
+assumed to be a function in a section 2, 3, or 9 manual.

 The syntax for this is as follows:
 .Bd -literal -offset indent
 \&.Lb libarm
 The syntax for this is as follows:
 .Bd -literal -offset indent
 \&.Lb libarm


@@ -723,7 +728,9 @@ Note that the
 macro is a
 .Sx Block partial-implicit
 only when invoked as the first macro
 macro is a
 .Sx Block partial-implicit
 only when invoked as the first macro

-in a SYNOPSIS section line, else it is
+in a
+.Em SYNOPSIS
+section line, else it is

 .Sx In-line .
 .Ss In-line
 Closed by
 .Sx In-line .
 .Ss In-line
 Closed by


@@ -1093,6 +1100,18 @@ and
 .Ss \&Bk
 .Ss \&Bl
 Begins a list composed of one or more list entries.
 .Ss \&Bk
 .Ss \&Bl
 Begins a list composed of one or more list entries.

+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
+.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
 A list entry is specified by the
 .Sx \&It
 macro, which consists of a head and optional body (depending on the list


@@ -1103,8 +1122,14 @@ A list must specify one of the following list types:
 A list offset by a bullet.
 The head of list entries must be empty.
 List entry bodies are positioned after the bullet.
 A list offset by a bullet.
 The head of list entries must be empty.
 List entry bodies are positioned after the bullet.

+The
+.Fl width
+argument varies the width of list bodies' left-margins.

 .It Fl column
 A columnated list.
 .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.
 The number of columns is specified as parameters to the
 .Sx \&Bl
 macro.


@@ -1115,11 +1140,11 @@ List entry bodies must be left empty.
 Column bodies have the following syntax:
 .Pp
 .D1 .It col1 <TAB> ... coln
 Column bodies have the following syntax:
 .Pp
 .D1 .It col1 <TAB> ... coln

-.D1 .It col1 Ta ... coln
-.D1 .It col1 <TAB> col2 Ta coln
+.D1 .It col1 \&Ta ... coln
+.D1 .It col1 <TAB> col2 \&Ta coln

 .Pp
 where columns may be separated by tabs, the literal string
 .Pp
 where columns may be separated by tabs, the literal string

-.Qq Ta ,
+.Qq \&Ta ,

 or a mixture of both.
 These are equivalent except that quoted sections propogate over tabs,
 for example,
 or a mixture of both.
 These are equivalent except that quoted sections propogate over tabs,
 for example,


@@ -1131,29 +1156,50 @@ will preserve the semicolon whitespace except for the last.
 A list offset by a dash (hyphen).
 The head of list entries must be empty.
 List entry bodies are positioned past the 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.

 .It Fl diag
 Like
 .Fl inset ,
 but with additional formatting to the head.
 .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.

 .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.
 .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.

 .It Fl hang
 Like
 .Fl tag ,
 but instead of list bodies positioned after the head, they trail the
 head text.
 .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.

 .It Fl hyphen
 Synonym for
 .Fl dash .
 .It Fl inset
 List bodies follow the list head.
 .It Fl hyphen
 Synonym for
 .Fl dash .
 .It Fl inset
 List bodies follow the list head.

+The
+.Fl width
+argument is ignored.

 .It Fl item
 This produces blocks of text.
 The head of list entries must be empty.
 .It Fl item
 This produces blocks of text.
 The head of list entries must be empty.

+The
+.Fl width
+argument is ignored.

 .It Fl ohang
 List bodies are positioned on the line following the head.
 .It Fl ohang
 List bodies are positioned on the line following the head.

+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
 .It Fl tag
 A list offset by list entry heads.  List entry bodies are positioned
 after the head as specified by the


@@ -1359,13 +1405,15 @@ This is the mandatory second macro of any
 file.
 Its calling syntax is as follows:
 .Pp
 file.
 Its calling syntax is as follows:
 .Pp

-.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
+.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch

 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
 .It Cm title
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
 .It Cm title

-The document's title (name).
-This should be capitalised and is required.
+The document's title (name), defaulting to
+.Qq UNKNOWN
+if unspecified.
+It should be capitalised.

 .It Cm section
 The manual section.
 This may be one of
 .It Cm section
 The manual section.
 This may be one of


@@ -1402,8 +1450,9 @@ This may be one of
 or
 .Ar paper
 .Pq paper .
 or
 .Ar paper
 .Pq paper .

-It is also required and should correspond to the manual's filename
-suffix.
+It should correspond to the manual's filename suffix and defaults to
+.Qq 1
+if unspecified.

 .It Cm volume
 This overrides the volume inferred from
 .Ar section .
 .It Cm volume
 This overrides the volume inferred from
 .Ar section .


@@ -1475,7 +1524,6 @@ Examples:
 .D1 \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386
 .D1 \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386

-.D1 \&.Dt FOO 9 KM i386

 .Pp
 See also
 .Sx \&Dd
 .Pp
 See also
 .Sx \&Dd


@@ -1597,6 +1645,28 @@ and
 .Ss \&In
 .Ss \&It
 .Ss \&Lb
 .Ss \&In
 .Ss \&It
 .Ss \&Lb

+Specify a library.
+The calling syntax is as follows:
+.Pp
+.D1 \. Ns Sx \&Lb Cm library
+.Pp
+The
+.Cm library
+parameter may be a system library, such as
+.Cm libz
+or
+.Cm libpam ,
+in which case a small library description is printed next to the linker
+invocation; or a custom library, in which case the library name is
+printed in quotes.
+This is most commonly used in the
+.Em SYNOPSIS
+section as described in
+.Sx MANUAL STRUCTURE .
+.Pp
+Examples:
+.D1 \&.Lb libz
+.D1 \&.Lb mdoc

 .Ss \&Li
 .Ss \&Lk
 Format a hyperlink.
 .Ss \&Li
 .Ss \&Lk
 Format a hyperlink.


@@ -1749,6 +1819,8 @@ line.
 .Ss \&Sy
 .Ss \&Tn
 .Ss \&Ud
 .Ss \&Sy
 .Ss \&Tn
 .Ss \&Ud

+Prints out
+.Dq currently under development.

 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.


@@ -1917,10 +1989,17 @@ This is not the case in mandoc.
 In groff, the
 .Sx \&Cd ,
 .Sx \&Er ,
 In groff, the
 .Sx \&Cd ,
 .Sx \&Er ,

+.Sx \&Ex ,

 and
 and

-.Sx \&Ex
+.Sx \&Rv

 macros were stipulated only to occur in certain manual sections.
 mandoc does not have these restrictions.
 macros were stipulated only to occur in certain manual sections.
 mandoc does not have these restrictions.

+.It
+Newer groff and mandoc print
+.Qq AT&T UNIX
+prior to unknown arguments of
+.Sx \&At ;
+older groff did nothing.

 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,