[BACK]Return to mdoc.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.103 and 1.116

version 1.103, 2010/05/14 15:02:03 version 1.116, 2010/06/03 15:54:27
Line 301  When composing a manual, make sure that your sentences
Line 301  When composing a manual, make sure that your sentences
 a line.  a line.
 By doing so, front-ends will be able to apply the proper amount of  By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,  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  .Pp
 The proper spacing is also intelligently preserved if a sentence ends at  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  .Sh MANUAL STRUCTURE
 A well-formed  A well-formed
 .Nm  .Nm
Line 335  file:
Line 343  file:
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
 \&.Os  \&.Os
 \&.  
 \&.Sh NAME  \&.Sh NAME
 \&.Nm foo  \&.Nm foo
 \&.Nd a description goes here  \&.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  \&.Sh SYNOPSIS
 \&.Nm foo  \&.Nm foo
 \&.Op Fl options  \&.Op Fl options
 \&.Ar  \&.Ar
 \&.  
 \&.Sh DESCRIPTION  \&.Sh DESCRIPTION
 The  The
 \&.Nm  \&.Nm
Line 401  and
Line 406  and
 .Sx \&Nd .  .Sx \&Nd .
 .It Em LIBRARY  .It Em LIBRARY
 The name of the library containing the documented material, which is  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:  The syntax for this is as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Lb libarm  \&.Lb libarm
Line 723  Note that the
Line 728  Note that the
 macro is a  macro is a
 .Sx Block partial-implicit  .Sx Block partial-implicit
 only when invoked as the first macro  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 .  .Sx In-line .
 .Ss In-line  .Ss In-line
 Closed by  Closed by
Line 1093  and
Line 1100  and
 .Ss \&Bk  .Ss \&Bk
 .Ss \&Bl  .Ss \&Bl
 Begins a list composed of one or more list entries.  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  A list entry is specified by the
 .Sx \&It  .Sx \&It
 macro, which consists of a head and optional body (depending on the list  macro, which consists of a head and optional body (depending on the list
Line 1103  A list must specify one of the following list types:
Line 1122  A list must specify one of the following list types:
 A list offset by a bullet.  A list offset by a bullet.
 The head of list entries must be empty.  The head of list entries must be empty.
 List entry bodies are positioned after the bullet.  List entry bodies are positioned after the bullet.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
 .It Fl column  .It Fl column
 A columnated list.  A columnated list.
   The
   .Fl width
   argument has no effect.
 The number of columns is specified as parameters to the  The number of columns is specified as parameters to the
 .Sx \&Bl  .Sx \&Bl
 macro.  macro.
 These dictate the width of columns either as  These dictate the width of columns either as
 .Sx Scaling Widths  .Sx Scaling Widths
 or literal text.  or literal text.
 List entry bodies must be left empty.  If the initial macro of a
 Column bodies have the following syntax:  .Fl column
 .Pp  list is not an
 .D1 .It col1 <TAB> ... coln  .Sx \&It ,
 .D1 .It col1 Ta ... coln  an
 .D1 .It col1 <TAB> col2 Ta coln  .Sx \&It
 .Pp  context spanning each line is implied until an
 where columns may be separated by tabs, the literal string  .Sx \&It
 .Qq Ta ,  line macro is encountered, at which point list bodies are interpreted as
 or a mixture of both.  described in the
 These are equivalent except that quoted sections propogate over tabs,  .Sx \&It
 for example,  documentation.
 .Pp  
 .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;  
 .Pp  
 will preserve the semicolon whitespace except for the last.  
 .It Fl dash  .It Fl dash
 A list offset by a dash (hyphen).  A list offset by a dash (hyphen).
 The head of list entries must be empty.  The head of list entries must be empty.
 List entry bodies are positioned past the dash.  List entry bodies are positioned past the dash.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
 .It Fl diag  .It Fl diag
 Like  Like
 .Fl inset ,  .Fl inset ,
 but with additional formatting to the head.  but with additional formatting to the head.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
 .It Fl enum  .It Fl enum
 An enumerated list offset by the enumeration from 1.  An enumerated list offset by the enumeration from 1.
 The head of list entries must be empty.  The head of list entries must be empty.
 List entry bodies are positioned after the enumeration.  List entry bodies are positioned after the enumeration.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
 .It Fl hang  .It Fl hang
 Like  Like
 .Fl tag ,  .Fl tag ,
 but instead of list bodies positioned after the head, they trail the  but instead of list bodies positioned after the head, they trail the
 head text.  head text.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
 .It Fl hyphen  .It Fl hyphen
 Synonym for  Synonym for
 .Fl dash .  .Fl dash .
 .It Fl inset  .It Fl inset
 List bodies follow the list head.  List bodies follow the list head.
   The
   .Fl width
   argument is ignored.
 .It Fl item  .It Fl item
 This produces blocks of text.  This produces blocks of text.
 The head of list entries must be empty.  The head of list entries must be empty.
   The
   .Fl width
   argument is ignored.
 .It Fl ohang  .It Fl ohang
 List bodies are positioned on the line following the head.  List bodies are positioned on the line following the head.
   The
   .Fl width
   argument is ignored.
 .It Fl tag  .It Fl tag
 A list offset by list entry heads.  List entry bodies are positioned  A list offset by list entry heads.  List entry bodies are positioned
 after the head as specified by the  after the head as specified by the
 .Fl width  .Fl width
 argument.  argument.
 .El  .El
   .Pp
   See also
   .Sx \&It .
 .Ss \&Bo  .Ss \&Bo
 Begins a block enclosed by square brackets.  Begins a block enclosed by square brackets.
 Does not have any head arguments.  Does not have any head arguments.
Line 1359  This is the mandatory second macro of any
Line 1404  This is the mandatory second macro of any
 file.  file.
 Its calling syntax is as follows:  Its calling syntax is as follows:
 .Pp  .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  .Pp
 Its arguments are as follows:  Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -tag -width Ds -offset Ds
 .It Cm title  .It Cm title
 The document's title (name).  The document's title (name), defaulting to
 This should be capitalised and is required.  .Qq UNKNOWN
   if unspecified.
   It should be capitalised.
 .It Cm section  .It Cm section
 The manual section.  The manual section.
 This may be one of  This may be one of
Line 1402  This may be one of
Line 1449  This may be one of
 or  or
 .Ar paper  .Ar paper
 .Pq paper .  .Pq paper .
 It is also required and should correspond to the manual's filename  It should correspond to the manual's filename suffix and defaults to
 suffix.  .Qq 1
   if unspecified.
 .It Cm volume  .It Cm volume
 This overrides the volume inferred from  This overrides the volume inferred from
 .Ar section .  .Ar section .
Line 1475  Examples:
Line 1523  Examples:
 .D1 \&.Dt FOO 1  .D1 \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM  .D1 \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386  .D1 \&.Dt FOO 9 i386
 .D1 \&.Dt FOO 9 KM i386  
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
Line 1596  and
Line 1643  and
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
 .Ss \&It  .Ss \&It
   A list item.  The syntax of this macro depends on the list type.
   .Pp
   Lists
   of type
   .Fl hang ,
   .Fl ohang ,
   .Fl inset ,
   and
   .Fl diag
   have the following calling syntax:
   .Pp
   .D1 \. Ns Sx \&It Cm args
   .Pp
   Lists of type
   .Fl bullet ,
   .Fl dash ,
   .Fl enum ,
   .Fl hyphen
   and
   .Fl item
   have the following calling syntax:
   .Pp
   .D1 \. Ns Sx \&It
   .Pp
   with subsequent lines interpreted within the scope of the
   .Sx \&It
   until either a closing
   .Sx \&El
   or another
   .Sx \&It .
   .Pp
   The
   .Fl tag
   list has syntax
   .Pp
   .D1 \. Ns Sx \&It Op Cm args
   .Pp
   with subsequent lines interpreted as with
   .Fl bullet
   and family.
   The line arguments correspond to the list's left-hand side; body
   arguments correspond to the list's contents.
   .Pp
   The
   .Fl column
   list is the most complicated.
   Its syntax is
   .Pp
   .D1 \. Ns Sx \&It Op Cm args
   .Pp
   where
   .Cm args
   are phrases, a mix of macros and text corresponding to a line column,
   delimited by tabs or the special
   .Sq \&Ta
   pseudo-macro.
   Lines subsequent the
   .Sx \&It
   are interpreted within the scope of the last phrase.
   Calling the pseudo-macro
   .Sq \&Ta
   will open a new phrase scope (this must occur on a macro line to be
   interpreted as a macro).  Note that the tab phrase delimiter may only be
   used within the
   .Sx \&It
   line itself.
   Subsequent this, only the
   .Sq \&Ta
   pseudo-macro may be used to delimit phrases.
   Furthermore, note that quoted sections propogate over tab-delimited
   phrases on an
   .Sx \&It ,
   for example,
   .Pp
   .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
   .Pp
   will preserve the semicolon whitespace except for the last.
   .Pp
   See also
   .Sx \&Bl .
 .Ss \&Lb  .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 \&Li
 .Ss \&Lk  .Ss \&Lk
 Format a hyperlink.  Format a hyperlink.
Line 1613  See also
Line 1762  See also
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
   Format a
   .Qq mailto:
   hyperlink.
   The calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Mt Cm address
   .Pp
   Examples:
   .D1 \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd  .Ss \&Nd
 .Ss \&Nm  .Ss \&Nm
 .Ss \&No  .Ss \&No
Line 1749  line.
Line 1907  line.
 .Ss \&Sy  .Ss \&Sy
 .Ss \&Tn  .Ss \&Tn
 .Ss \&Ud  .Ss \&Ud
   Prints out
   .Dq currently under development.
 .Ss \&Ux  .Ss \&Ux
 Format the UNIX name.  Format the UNIX name.
 Accepts no argument.  Accepts no argument.
Line 1838  Heirloom troff, the other significant troff implementa
Line 1998  Heirloom troff, the other significant troff implementa
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
   groff does not accept the
   .Sq \&Ta
   pseudo-macro as a line macro.
   mandoc does.
   .It
 The comment syntax  The comment syntax
 .Sq \e."  .Sq \e."
 is no longer accepted.  is no longer accepted.
Line 1917  This is not the case in mandoc.
Line 2082  This is not the case in mandoc.
 In groff, the  In groff, the
 .Sx \&Cd ,  .Sx \&Cd ,
 .Sx \&Er ,  .Sx \&Er ,
   .Sx \&Ex ,
 and  and
 .Sx \&Ex  .Sx \&Rv
 macros were stipulated only to occur in certain manual sections.  macros were stipulated only to occur in certain manual sections.
 mandoc does not have these restrictions.  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  .El
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
Legend:
Removed from v.1.103  
changed lines
  Added in v.1.116
CVSweb