Fixed misspelt "Loongson" (noted by Ingo Schwarze).

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 4ee41962e9d2aef3fe2fec3a1971c468e8024648..eb83a25d4334b8d3d8b890dd5b3bb0e8da6343e7 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.80 2010/01/01 16:27:32 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.86 2010/03/26 07:07:58 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"


@@ -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: January 1 2010 $
+.Dd $Mdocdate: March 26 2010 $

 .Dt MDOC 7
 .Os
 .
 .Dt MDOC 7
 .Os
 .


@@ -132,7 +132,7 @@ and
 Terms may be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
 Terms may be text-decorated using the
 .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P

-(revert to previous mode):  
+(revert to previous mode):

 .Pp
 .D1 \efBbold\efR \efIitalic\efP
 .Pp
 .Pp
 .D1 \efBbold\efR \efIitalic\efP
 .Pp


@@ -170,19 +170,19 @@ for arbitrary-digit numerals:
 .D1 \es+(10much bigger\es-(10
 .D1 \es+'100'much much bigger\es-'100'
 .Pp
 .D1 \es+(10much bigger\es-(10
 .D1 \es+'100'much much bigger\es-'100'
 .Pp

-Note these forms are 
+Note these forms are

 .Em not
 .Em not

-recommended for 
+recommended for

 .Nm ,
 which encourages semantic annotation.
 .
 .
 .Ss Predefined Strings
 .Nm ,
 which encourages semantic annotation.
 .
 .
 .Ss Predefined Strings

-Historically, 
+Historically,

 .Xr groff 1
 .Xr groff 1

-also defined a set of package-specific 
+also defined a set of package-specific

 .Dq predefined strings ,
 .Dq predefined strings ,

-which, like 
+which, like

 .Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,
 .Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,


@@ -343,7 +343,7 @@ and
 .Sx \&Os
 macros, is required for every document.
 .Pp
 .Sx \&Os
 macros, is required for every document.
 .Pp

-The first section (sections are denoted by 
+The first section (sections are denoted by

 .Sx \&Sh )
 must be the NAME section, consisting of at least one
 .Sx \&Nm
 .Sx \&Sh )
 must be the NAME section, consisting of at least one
 .Sx \&Nm


@@ -420,7 +420,7 @@ macro(s) must precede the
 .Sx \&Nd
 macro.
 .Pp
 .Sx \&Nd
 macro.
 .Pp

-See 
+See

 .Sx \&Nm
 and
 .Sx \&Nd .
 .Sx \&Nm
 and
 .Sx \&Nd .


@@ -438,7 +438,7 @@ See
 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device

-configuration. 
+configuration.

 .Pp
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:
 .Pp
 For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:


@@ -469,10 +469,10 @@ And for the third, configurations (section 4):
 \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed
 .Pp
 \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed
 .Pp

-Manuals not in these sections generally don't need a 
+Manuals not in these sections generally don't need a

 .Em SYNOPSIS .
 .Pp
 .Em SYNOPSIS .
 .Pp

-See 
+See

 .Sx \&Op ,
 .Sx \&Cd ,
 .Sx \&Fn ,
 .Sx \&Op ,
 .Sx \&Cd ,
 .Sx \&Fn ,


@@ -481,7 +481,7 @@ and
 .Sx \&Vt .
 .
 .It Em DESCRIPTION
 .Sx \&Vt .
 .
 .It Em DESCRIPTION

-This expands upon the brief, one-line description in 
+This expands upon the brief, one-line description in

 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command), such as:
 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command), such as:


@@ -683,7 +683,7 @@ All macros have bodies; some
 don't have heads; only one
 .Po
 .Sx \&It Fl column
 don't have heads; only one
 .Po
 .Sx \&It Fl column

-.Pc 
+.Pc

 has multiple heads.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 has multiple heads.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB


@@ -770,7 +770,16 @@ or end of line.
 .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Qq  Ta    Yes      Ta    Yes
 .It Sx \&Sq  Ta    Yes      Ta    Yes
 .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Qq  Ta    Yes      Ta    Yes
 .It Sx \&Sq  Ta    Yes      Ta    Yes

+.It Sx \&Vt  Ta    Yes      Ta    Yes

 .El
 .El

+.Pp
+Note that the
+.Sx \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a SYNOPSIS section line, else it is
+.Sx In-line .

 .
 .
 .Ss In-line
 .
 .
 .Ss In-line


@@ -863,10 +872,10 @@ then the macro accepts an arbitrary number of arguments.
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Vt  Ta    Yes      Ta    Yes      Ta    >0

-.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0, <3
+.It Sx \&Xr  Ta    Yes      Ta    Yes      Ta    >0

 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1

-.El   
+.El

 .
 .
 .Sh REFERENCE
 .
 .
 .Sh REFERENCE


@@ -1026,7 +1035,7 @@ a function:
 .Ed
 .
 .Ss \&Aq
 .Ed
 .
 .Ss \&Aq

-Encloses its arguments in angled brackets.  
+Encloses its arguments in angled brackets.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -1073,7 +1082,7 @@ Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent

-\&.At 
+\&.At

 \&.At V.1
 .Ed
 .Pp
 \&.At V.1
 .Ed
 .Pp


@@ -1242,7 +1251,7 @@ See also
 .Sx \&Bq .
 .
 .Ss \&Bq
 .Sx \&Bq .
 .
 .Ss \&Bq

-Encloses its arguments in square brackets.  
+Encloses its arguments in square brackets.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -1389,7 +1398,7 @@ manual.  Its calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp

-The 
+The

 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,
 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,


@@ -1438,7 +1447,7 @@ See also
 .Sx \&Dq .
 .
 .Ss \&Dq
 .Sx \&Dq .
 .
 .Ss \&Dq

-Encloses its arguments in double quotes.  
+Encloses its arguments in double quotes.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -1544,6 +1553,7 @@ subsequent that.  It, too, is optional.  It must be one of
 .Ar hppa64 ,
 .Ar i386 ,
 .Ar landisk ,
 .Ar hppa64 ,
 .Ar i386 ,
 .Ar landisk ,

+.Ar loongson ,

 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,


@@ -1892,9 +1902,58 @@ and
 .
 .Ss \&Va
 .Ss \&Vt
 .
 .Ss \&Va
 .Ss \&Vt

+A variable type.  This is also used for indicating global variables in the
+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
+.Sx In-line
+syntax.
+.Pp
+Note that this should not be confused with
+.Sx \&Ft ,
+which is used for function return types.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Vt unsigned char
+\&.Vt extern const char * const sys_signame[] ;
+.Ed
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
+.

 .Ss \&Xc
 .Ss \&Xo
 .Ss \&Xr
 .Ss \&Xc
 .Ss \&Xo
 .Ss \&Xr

+Link to another manual
+.Pq Qq cross-reference .
+Its calling syntax is
+.Pp
+.D1 \. Ns Sx \&Xr Cm name section
+.Pp
+The
+.Cm name
+and
+.Cm section
+are the name and section of the linked manual.  If
+.Cm section
+is followed by non-punctuation, an
+.Sx \&Ns
+is inserted into the token stream.  This behaviour is for compatibility
+with
+.Xr groff 1 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Xr mandoc 1
+\&.Xr mandoc 1 ;
+\&.Xr mandoc 1 s behaviour
+.Ed
+.

 .Ss \&br
 .Ss \&sp
 .
 .Ss \&br
 .Ss \&sp
 .


@@ -1913,6 +1972,10 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It

 In
 .Xr groff 1 ,
 the
 In
 .Xr groff 1 ,
 the


@@ -1920,9 +1983,9 @@ the
 macro does not format its arguments when used in the FILES section under
 certain list types.  This irregular behaviour has been discontinued.
 .It
 macro does not format its arguments when used in the FILES section under
 certain list types.  This irregular behaviour has been discontinued.
 .It

-Historic 
+Historic

 .Xr groff 1
 .Xr groff 1

-does not print a dash for empty 
+does not print a dash for empty

 .Sx \&Fl
 arguments.  This behaviour has been discontinued.
 .It
 .Sx \&Fl
 arguments.  This behaviour has been discontinued.
 .It