-.\" $Id: mdoc.7,v 1.102 2010/05/14 14:21:17 kristaps Exp $
+.\" $Id: mdoc.7,v 1.113 2010/06/02 12:01:00 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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
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
\&.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
.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
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
.Ss \&Bf
.Ss \&Bk
.Ss \&Bl
-.\" Begins a list composed of one or more list entries. A list entry is
-.\" specified by the
-.\" .Sx \&It
-.\" macro, which consists of a head and optional body. By default, a list
-.\" is preceded by a blank line. A list must specify one of the following
-.\" list types:
-.\" .Bl -tag -width 12n
-.\" .It Fl bullet
-.\" A list offset by a bullet. The head of list entries must be empty.
-.\" List entry bodies are justified after the bullet.
-.\" .It Fl column
-.\" A columnated list. The number of columns is specified as arguments to
-.\" the
-.\" .Sx \&Bl
-.\" macro (the deprecated form of following the invocation of
-.\" .Fl column
-.\" is also accepted). Arguments dictate the width of columns specified in
-.\" list entries. List entry bodies must be left empty. Columns specified
-.\" in the list entry head are justified to their position in the sequence
-.\" of columns.
-.\" .It Fl dash
-.\" A list offset by a dash (hyphen). The head of list entries must be
-.\" empty. List entry bodies are justified past the dash.
-.\" .It Fl diag
-.\" Like
-.\" .Fl inset
-.\" lists, but with additional formatting to the head.
-.\" .It Fl enum
-.\" A list offset by a number indicating list entry position. The head of
-.\" list entries must be empty. List entry bodies are justified past the
-.\" enumeration.
-.\" .It Fl hang
-.\" Like
-.\" .Fl tag ,
-.\" but instead of list bodies justifying to the head on the first line,
-.\" they trail the head text.
-.\" .It Fl hyphen
-.\" Synonym for
-.\" .Fl dash .
-.\" .It Fl inset
-.\" Like
-.\" .Fl tag ,
-.\" but list entry bodies aren't justified.
-.\" .It Fl item
-.\" An un-justified list. This produces blocks of text.
-.\" .It Fl ohang
-.\" List bodies are placed on the line following the head.
-.\" .It Fl tag
-.\" A list offset by list entry heads. List entry bodies are justified
-.\" after the head.
-.\" .El
-.\" .Pp
-.\" More...
-.\" .
+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
+type).
+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
+.Fl width
+argument varies the width of list bodies' left-margins.
+.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
+.Sx Scaling Widths
+or literal text.
+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
+.Pp
+where columns may be separated by tabs, the literal string
+.Qq \&Ta ,
+or a mixture of both.
+These are equivalent except that quoted sections propogate over tabs,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.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.
+.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.
+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.
+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.
+The
+.Fl width
+argument is ignored.
+.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.
+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
+.Fl width
+argument.
+.El
.Ss \&Bo
Begins a block enclosed by square brackets.
Does not have any head arguments.
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
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 .
.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
.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 \&Sy
.Ss \&Tn
.Ss \&Ud
+Prints out
+.Dq currently under development.
.Ss \&Ux
Format the UNIX name.
Accepts no argument.
In groff, the
.Sx \&Cd ,
.Sx \&Er ,
+.Sx \&Ex ,
and
-.Sx \&Ex
+.Sx \&Rv
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 ,
git.ckatri.com / mandoc.git / blobdiff