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>
 .\"
@@ -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.
 .\"
-.Dd $Mdocdate: May 14 2010 $
+.Dd $Mdocdate: June 2 2010 $
 .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,
-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
-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
@@ -335,18 +343,15 @@ file:
 \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7
 \&.Os
-\&.
 \&.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
-\&.
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Ar
-\&.
 \&.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
-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
@@ -723,7 +728,9 @@ Note that the
 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
@@ -1133,11 +1140,11 @@ List entry bodies must be left empty.
 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
-.Qq Ta ,
+.Qq \&Ta ,
 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
-.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
-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
@@ -1441,8 +1450,9 @@ This may be one of
 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 .
@@ -1514,7 +1524,6 @@ Examples:
 .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
@@ -1636,6 +1645,28 @@ and
 .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.
@@ -1788,6 +1819,8 @@ line.
 .Ss \&Sy
 .Ss \&Tn
 .Ss \&Ud
+Prints out
+.Dq currently under development.
 .Ss \&Ux
 Format the UNIX name.
 Accepts no argument.