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

Diff for /mandoc/mdoc.7 between version 1.111 and 1.118

version 1.111, 2010/05/30 11:00:53 version 1.118, 2010/06/04 21:49:39
Line 33  section describes compatibility with other troff \-mdo
Line 33  section describes compatibility with other troff \-mdo
 .Pp  .Pp
 An  An
 .Nm  .Nm
 document follows simple rules:  lines beginning with the control  document follows simple rules: lines beginning with the control
 character  character
 .Sq \.  .Sq \.
 are parsed for macros.  Other lines are interpreted within the scope of  are parsed for macros.  Other lines are interpreted within the scope of
Line 122  escape followed by an indicator: B (bold), I, (italic)
Line 122  escape followed by an indicator: B (bold), I, (italic)
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,  A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.  respectively) may be used instead.
 A text decoration is valid within  A text decoration is valid within
 the current font scope only:  if a macro opens a font scope alongside  the current font scope only: if a macro opens a font scope alongside
 its own scope, such as  its own scope, such as
 .Sx \&Bf  .Sx \&Bf
 .Cm \&Sy ,  .Cm \&Sy ,
Line 343  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, & 9 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 1139  macro.
Line 1136  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.
Line 1209  after the head as specified by the
Line 1202  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 1336  See also
Line 1332  See also
 and  and
 .Sx \&Dl .  .Sx \&Dl .
 .Ss \&Db  .Ss \&Db
   Start a debugging context.
   This macro is parsed, but generally ignored.
   Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Db Cm on | off
 .Ss \&Dc  .Ss \&Dc
 Closes a  Closes a
 .Sx \&Do  .Sx \&Do
Line 1563  and
Line 1564  and
 .Ss \&Ef  .Ss \&Ef
 .Ss \&Ek  .Ss \&Ek
 .Ss \&El  .Ss \&El
   Ends a list context started by
   .Sx \&Bl .
   .Pp
   See also
   .Sx \&Bl
   and
   .Sx \&It .
 .Ss \&Em  .Ss \&Em
 Denotes text that should be emphasised.  Denotes text that should be emphasised.
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
Line 1602  is not provided, the document's name as stipulated in
Line 1610  is not provided, the document's name as stipulated in
 .Sx \&Nm  .Sx \&Nm
 is provided.  is provided.
 .Ss \&Fa  .Ss \&Fa
   Function argument.
   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
   section when documenting multi-line function prototypes.
   If invoked with multiple arguments, the arguments are separated by a
   comma.
   Furthermore, if the following macro is another
   .Sx \&Fa ,
   the last argument will also have a trailing comma.
   .Pp
   Examples:
   .D1 \&.Fa \(dqconst char *p\(dq
   .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
   .D1 \&.Fa foo
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
   Historically used to document include files.
   This usage has been deprecated in favour of
   .Sx \&In .
   Do not use this macro.
   .Pp
   See also
   .Sx \&In .
 .Ss \&Fl  .Ss \&Fl
 Command-line flag.  Command-line flag.
 Used when listing arguments to command-line utilities.  Used when listing arguments to command-line utilities.
Line 1646  and
Line 1679  and
 .Ss \&Hf  .Ss \&Hf
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
   An
   .Qq include
   file.
   In the
   .Em SYNOPSIS
   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.
   .Pp
   Examples
   .D1 \&.In sys/types
 .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.  Specify a library.
 The calling syntax is as follows:  The calling syntax is as follows:
Line 1686  See also
Line 1812  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 1912  Heirloom troff, the other significant troff implementa
Line 2047  Heirloom troff, the other significant troff implementa
 \-mdoc, is similar to historic groff.  \-mdoc, is similar to historic groff.
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
   .It
   Historic groff formats the
   .Sx \&In
   badly: trailing arguments are trashed and
   .Em SYNOPSIS
   is not specially treated.
   .It
   groff does not accept the
   .Sq \&Ta
   pseudo-macro as a line macro.
   mandoc does.
 .It  .It
 The comment syntax  The comment syntax
 .Sq \e."  .Sq \e."
Legend:
Removed from v.1.111  
changed lines
  Added in v.1.118
CVSweb