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 61190af5e6d8402d9cc2ba3327a228c42f3d76e9..184ccf737fcdbabe32a091c02ff00f026923c6e6 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.106 2010/05/14 17:31:25 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


@@ -1133,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,


@@ -1398,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


@@ -1441,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 .


@@ -1514,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


@@ -1636,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.


@@ -1788,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.