-.\" $Id: mdoc.7,v 1.119 2010/06/04 22:16:27 kristaps Exp $
+.\" $Id: mdoc.7,v 1.127 2010/06/27 13:30:51 schwarze 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: June 4 2010 $
+.Dd $Mdocdate: June 27 2010 $
.Dt MDOC 7
.Os
.Sh NAME
whether in a macro or free-form text line, is ignored to the end of
line. A macro line with only a control character and comment escape,
.Sq \&.\e" ,
-is also ignored. Macro lines with only a control charater and optionally
+is also ignored. Macro lines with only a control character and optionally
whitespace are stripped from input.
.Ss Reserved Characters
Within a macro line, the following characters are reserved:
.Dq predefined strings ,
which, like
.Sx Special Characters ,
-demark special output characters and strings by way of input codes.
+mark special output characters and strings by way of input codes.
Predefined strings are escaped with the slash-asterisk,
.Sq \e* :
single-character
followed by
.Sx \&Nd .
.Pp
-Following that, convention dictates specifying at least the SYNOPSIS and
-DESCRIPTION sections, although this varies between manual sections.
+Following that, convention dictates specifying at least the
+.Em SYNOPSIS
+and
+.Em DESCRIPTION
+sections, although this varies between manual sections.
.Pp
The following is a well-formed skeleton
.Nm
Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.Pp
-See
-.Sx \&Op ,
+Some macros are displayed differently in the
+.Em SYNOPSIS
+section, particularly
+.Sx \&Nm ,
.Sx \&Cd ,
+.Sx \&Fd ,
.Sx \&Fn ,
-.Sx \&Ft ,
+.Sx \&Fo ,
+.Sx \&In ,
+.Sx \&Vt ,
and
-.Sx \&Vt .
+.Sx \&Ft .
+All of these macros are output on their own line. If two such
+dissimilar macros are pair-wise invoked (except for
+.Sx \&Ft
+before
+.Sx \&Fo
+or
+.Sx \&Fn ) ,
+they are separated by a vertical space, unless in the case of
+.Sx \&Fo ,
+.Sx \&Fn ,
+and
+.Sx \&Ft ,
+which are always separated by vertical space.
.It Em DESCRIPTION
This expands upon the brief, one-line description in
.Em NAME .
.Sx \&Aq .
.Ss \&Ap
Inserts an apostrophe without any surrounding white-space.
-This is generally used as a grammatic device when referring to the verb
+This is generally used as a grammatical device when referring to the verb
form of a function:
.Bd -literal -offset indent
\&.Fn execve Ap d
As the calculated string length of the opaque string.
.El
.Pp
-If unset, it will revert to the value of
-.Ar 8n
-as described in
-.Sx Scaling Widths .
+If not provided an argument, it will be ignored.
.It Fl compact
Do not assert a vertical space before the block.
.It Fl file Ar file
.Sx \&Dl .
.Ss \&Bf
.Ss \&Bk
+Begins a keep block, containing a collection of macros or text
+to be kept together in the output.
+One argument is required; additional arguments are ignored.
+Currently, the only argument implemented is
+.Fl words ,
+requesting to keep together all words of the contained text
+on the same output line.
+A
+.Fl lines
+argument to keep together all lines of the contained text
+on the same page has been desired for a long time,
+but has never been implemented.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op o Ar output_file
+\&.Ek
+.Ed
.Ss \&Bl
Begins a list composed of one or more list entries.
A list is associated with a type, which is a required argument.
.Ss \&Db
Start a debugging context.
This macro is parsed, but generally ignored.
-Its calling syntax is as follows:
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Db Cm on | off
+.D1 Pf \. Sx \&Db Cm on | off
.Ss \&Dc
Closes a
.Sx \&Do
This is the mandatory first macro of any
.Nm
manual.
-Its calling syntax is as follows:
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Cm date
.Pp
The
.Cm date
This is the mandatory second macro of any
.Nm
file.
-Its calling syntax is as follows:
-.Pp
-.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Dt
+.Oo
+.Cm title
+.Oo
+.Cm section
+.Op Cm volume | arch
+.Oc
+.Oc
+.Ed
.Pp
Its arguments are as follows:
.Bl -tag -width Ds -offset Ds
.Ss \&Ed
.Ss \&Ef
.Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
.Ss \&El
Ends a list context started by
.Sx \&Bl .
is provided.
.Ss \&Fa
Function argument.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fa
+.Op Cm argtype
+.Cm argname
+.Ed
+.Pp
This may be invoked for names with or without the corresponding type.
It is also used to specify the field name of a structure.
Most often, the
.Sx \&Fa
macro is used in the
.Em SYNOPSIS
+within
+.Sx \&Fo
section when documenting multi-line function prototypes.
If invoked with multiple arguments, the arguments are separated by a
comma.
.D1 \&.Fa \(dqconst char *p\(dq
.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
.D1 \&.Fa foo
+.Pp
+See also
+.Sx \&Fo .
.Ss \&Fc
.Ss \&Fd
Historically used to document include files.
Do not use this macro.
.Pp
See also
+.Sx MANUAL STRUCTURE
+and
.Sx \&In .
.Ss \&Fl
Command-line flag.
.Sx \&Cm .
.Ss \&Fn
A function name.
-Its calling syntax is as follows:
+Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Ns Sx \&Fn
.Op Cm functype
.Cm funcname
.Op Oo Cm argtype Oc Cm argname
.Ed
-If invoked in the
-.Em SYNOPSIS
-section, vertical space is asserted before and after the macro.
-In all cases, the function arguments are surrounded in parenthesis and
+.Pp
+Function arguments are surrounded in parenthesis and
are delimited by commas.
If no arguments are specified, blank parenthesis are output.
.Pp
Examples:
.D1 \&.Fn "int funcname" "int arg0" "int arg1"
-.D1 \&.Fn funcname
.D1 \&.Fn funcname "int arg0"
.D1 \&.Fn funcname arg0
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
.Pp
See also
-.Sx \&Fa ,
-.Sx \&Fo ,
-.Sx \&Fc ,
+.Sx MANUAL STRUCTURE
and
.Sx \&Ft .
.Ss \&Fo
-.Ss \&Fr
+Begin a function block.
+This is a multi-line version of
+.Sx \&Fn .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Fo Cm funcname
+.Pp
+Invocations usually occur in the following context:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Ft Cm functype
+.br
+.Pf \. Sx \&Fo Cm funcname
+.br
+.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
+.br
+\.\.\.
+.br
+.Pf \. Sx \&Fc
+.Ed
+.Pp
+A
+.Sx \&Fo
+scope is closed by
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fa ,
+.Sx \&Fc ,
+and
.Ss \&Ft
+A function type.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ft Cm functype
+.Pp
+Examples:
+.D1 \&.Ft int
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fn ,
+and
+.Sx \&Fo .
.Ss \&Fx
Format the FreeBSD version provided as an argument, or a default value
if no argument is provided.
section (only if invoked as the line macro), the first argument is
preceded by
.Qq #include ,
-the arguments is enclosed in angled braces, and a newline is asserted.
-In all other invocations, only angled braces will enclose the argument.
+the arguments is enclosed in angled braces.
.Pp
-Examples
+Examples:
.D1 \&.In sys/types
+.Pp
+See also
+.Sx MANUAL STRUCTURE .
.Ss \&It
-A list item. The syntax of this macro depends on the list type.
+A list item.
+The syntax of this macro depends on the list type.
.Pp
Lists
of type
.Fl inset ,
and
.Fl diag
-have the following calling syntax:
+have the following syntax:
.Pp
-.D1 \. Ns Sx \&It Cm args
+.D1 Pf \. Sx \&It Cm args
.Pp
Lists of type
.Fl bullet ,
.Fl hyphen
and
.Fl item
-have the following calling syntax:
+have the following syntax:
.Pp
-.D1 \. Ns Sx \&It
+.D1 Pf \. Sx \&It
.Pp
with subsequent lines interpreted within the scope of the
.Sx \&It
.Pp
The
.Fl tag
-list has syntax
+list has the following syntax:
.Pp
-.D1 \. Ns Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Op Cm args
.Pp
-with subsequent lines interpreted as with
+Subsequent lines are interpreted as with
.Fl bullet
and family.
The line arguments correspond to the list's left-hand side; body
The
.Fl column
list is the most complicated.
-Its syntax is
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Op Cm args
.Pp
-where
+The
.Cm args
are phrases, a mix of macros and text corresponding to a line column,
delimited by tabs or the special
Subsequent this, only the
.Sq \&Ta
pseudo-macro may be used to delimit phrases.
-Furthermore, note that quoted sections propogate over tab-delimited
+Furthermore, note that quoted sections propagate over tab-delimited
phrases on an
.Sx \&It ,
for example,
.Pp
-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
.Pp
will preserve the semicolon whitespace except for the last.
.Pp
.Sx \&Bl .
.Ss \&Lb
Specify a library.
-The calling syntax is as follows:
+The syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Lb Cm library
+.D1 Pf \. Sx \&Lb Cm library
.Pp
The
.Cm library
.Ss \&Li
.Ss \&Lk
Format a hyperlink.
-The calling syntax is as follows:
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.D1 Pf \. Sx \&Lk Cm uri Op Cm name
.Pp
Examples:
.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
Format a
.Qq mailto:
hyperlink.
-The calling syntax is as follows:
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Mt Cm address
+.D1 Pf \. Sx \&Mt Cm address
.Pp
Examples:
.D1 \&.Mt discuss@manpages.bsd.lv
This is the mandatory third macro of
any
.Nm
-file. Its calling syntax is as follows:
+file.
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system
.Pp
The optional
.Cm system
.Sx \&%Q ,
.Sx \&%R ,
.Sx \&%T ,
+.Sx \&%U ,
and
.Sx \&%V
child macros (at least one must be specified).
.Ss \&Va
.Ss \&Vt
A variable type.
-This is also used for indicating global variables in the SYNOPSIS
+This is also used for indicating global variables in the
+.Em SYNOPSIS
section, in which case a variable name is also specified.
Note that it accepts
.Sx Block partial-implicit
-syntax when invoked as the first macro in the SYNOPSIS section, else it
-accepts ordinary
+syntax when invoked as the first macro in the
+.Em SYNOPSIS
+section, else it accepts ordinary
.Sx In-line
syntax.
.Pp
.Pp
Examples:
.D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] ;
+.D1 \&.Vt extern const char * const sys_signame[] \&;
.Pp
See also
-.Sx \&Ft
+.Sx MANUAL STRUCTURE
and
.Sx \&Va .
.Ss \&Xc
.Ss \&Xr
Link to another manual
.Pq Qq cross-reference .
-Its calling syntax is
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Xr Cm name section
+.D1 Pf \. Sx \&Xr Cm name section
.Pp
The
.Cm name
.Pp
Examples:
.D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&;
.D1 \&.Xr mandoc 1 \&Ns s behaviour
.Ss \&br
.Ss \&sp
.Pp
.Bl -dash -compact
.It
+Old groff fails to assert a newline before
+.Sx \&Bd Fl ragged compact .
+.It
+groff behaves inconsistently when encountering
+.Pf non- Sx \&Fa
+children of
+.Sx \&Fo
+regarding spacing between arguments.
+In mandoc, this is not the case: each argument is consistently followed
+by a single space and the trailing
+.Sq \&)
+suppresses prior spacing.
+.It
+groff behaves inconsistently when encountering
+.Sx \&Ft
+and
+.Sx \&Fn
+in the
+.Em SYNOPSIS :
+at times newline(s) are suppressed depending on whether a prior
+.Sx \&Fn
+has been invoked.
+In mandoc, this is not the case.
+See
+.Sx \&Ft
+and
+.Sx \&Fn
+for the normalised behaviour.
+.It
Historic groff does not break before an
.Sx \&Fn
when not invoked as the line macro in the
standalone double-quote in formatted output.
This idiosyncratic behaviour is not applicable in mandoc.
.It
-Display types
+Display offsets
.Sx \&Bd
-.Fl center
+.Fl offset Ar center
and
-.Fl right
-are aliases for
-.Fl left
-in manodc. Furthermore, the
+.Fl offset Ar right
+are disregarded in mandoc.
+Furthermore, the
.Fl file Ar file
-argument is ignored.
+argument is not supported in mandoc.
Lastly, since text is not right-justified in mandoc (or even groff),
.Fl ragged
and
This is not supported in mandoc.
.It
In groff, the
-.Sx \&Fo
-macro only produces the first parameter.
-This is not the case in mandoc.
-.It
-In groff, the
.Sx \&Cd ,
.Sx \&Er ,
.Sx \&Ex ,
git.ckatri.com / mandoc.git / blobdiff