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

Diff for /mandoc/mdoc.7 between version 1.49 and 1.50

version 1.49, 2009/07/19 09:17:42 version 1.50, 2009/07/20 13:45:11
Line 13 
Line 13 
 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"  .\"
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt MDOC 7  .Dt MDOC 7
 .Os  .Os
Line 25 
Line 25 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm mdoc  .Nm mdoc
 language is used to format  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  In this reference document, we describe its syntax, structure,  manuals.  In this reference document, we describe its syntax, structure,
 and usage.  Our reference implementation is  and usage.  Our reference implementation is
 .Xr mandoc 1 .  .Xr mandoc 1 .
 The  The
 .Sx COMPATIBILITY  .Sx COMPATIBILITY
 section describes compatibility with  section describes compatibility with
 .Xr groff 1 .  .Xr groff 1 .
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .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
 prior macros:  prior macros:
Line 55  documents may contain only graphable 7-bit ASCII chara
Line 55  documents may contain only graphable 7-bit ASCII chara
 character, and, in certain circumstances, the tab character.  All  character, and, in certain circumstances, the tab character.  All
 manuals must have  manuals must have
 .Ux  .Ux
 line terminators.  line terminators.
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss Comments  .Ss Comments
 Text following a  Text following a
Line 87  Within a macro line, the following characters are rese
Line 87  Within a macro line, the following characters are rese
 .It \&?  .It \&?
 .Pq question  .Pq question
 .It \&!  .It \&!
 .Pq exclamation  .Pq exclamation
 .It \&|  .It \&|
 .Pq vertical bar  .Pq vertical bar
 .El  .El
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
Line 98  Use of reserved characters is described in
Line 98  Use of reserved characters is described in
 For general use in macro lines, these characters must either be escaped  For general use in macro lines, these characters must either be escaped
 with a non-breaking space  with a non-breaking space
 .Pq Sq \e&  .Pq Sq \e&
 or, if applicable, an appropriate escape sequence used.  or, if applicable, an appropriate escape sequence used.
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss Special Characters  .Ss Special Characters
 Special characters may occur in both macro and free-form lines.  Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character  Sequences begin with the escape character
 .Sq \e  .Sq \e
 followed by either an open-parenthesis  followed by either an open-parenthesis
 .Sq \&(  .Sq \&(
 for two-character sequences; an open-bracket  for two-character sequences; an open-bracket
 .Sq \&[  .Sq \&[
Line 112  for n-character sequences (terminated at a close-brack
Line 112  for n-character sequences (terminated at a close-brack
 .Sq \&] ) ;  .Sq \&] ) ;
 or a single one-character sequence.  See  or a single one-character sequence.  See
 .Xr mandoc_char 1  .Xr mandoc_char 1
 for a complete list.  Examples include  for a complete list.  Examples include
 .Sq \e(em  .Sq \e(em
 .Pq em-dash  .Pq em-dash
 and  and
 .Sq \ee  .Sq \ee
 .Pq back-slash .  .Pq back-slash .
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
Line 137  In non-literal free-form lines, consecutive blocks of 
Line 137  In non-literal free-form lines, consecutive blocks of 
 pruned from input and added later in the output filter, if applicable:  pruned from input and added later in the output filter, if applicable:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 These     spaces   are    pruned       from    input.  These     spaces   are    pruned       from    input.
 \&.Bd \-literal  \&.Bd \-literal
 These         are              not.  These         are              not.
 \&.Ed  \&.Ed
 .Ed  .Ed
Line 149  arguments are quoted, whitespace within the quotes is 
Line 149  arguments are quoted, whitespace within the quotes is 
 .Pp  .Pp
 Blank lines are only permitted within literal contexts, as are lines  Blank lines are only permitted within literal contexts, as are lines
 containing only whitespace.  Tab characters are only acceptable when  containing only whitespace.  Tab characters are only acceptable when
 delimiting  delimiting
 .Sq \&Bl \-column  .Sq \&Bl \-column
 or when in a literal context.  or when in a literal context.
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
Line 158  Macro arguments may be quoted with a double-quote to g
Line 158  Macro arguments may be quoted with a double-quote to g
 space-delimited terms or to retain blocks of whitespace.  A quoted  space-delimited terms or to retain blocks of whitespace.  A quoted
 argument begins with a double-quote preceded by whitespace.  The next  argument begins with a double-quote preceded by whitespace.  The next
 double-quote not pair-wise adjacent to another double-quote terminates  double-quote not pair-wise adjacent to another double-quote terminates
 the literal, regardless of surrounding whitespace.  the literal, regardless of surrounding whitespace.
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
 This produces tokens  This produces tokens
 .Sq a" ,  .Sq a" ,
 .Sq b c ,  .Sq b c ,
 .Sq de ,  .Sq de ,
 and  and
 .Sq fg" .  .Sq fg" .
 Note that any quoted term, be it argument or macro, is indiscriminately  Note that any quoted term, be it argument or macro, is indiscriminately
 considered literal text.  Thus, the following produces  considered literal text.  Thus, the following produces
 .Sq \&Em a :  .Sq \&Em a :
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Em "Em a"  \&.Em "Em a"
Line 180  In free-form mode, quotes are regarded as opaque text.
Line 180  In free-form mode, quotes are regarded as opaque text.
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 Each  Each
 .Nm  .Nm
 document must begin with a document prologue, containing, in order,  document must begin with a document prologue, containing, in order,
 .Sq \&Dd ,  .Sq \&Dd ,
 .Sq \&Dt ,  .Sq \&Dt ,
 and  and
 .Sq \&Os ,  .Sq \&Os ,
 then the NAME section containing at least one  then the NAME section containing at least one
 .Sq \&Nm  .Sq \&Nm
 followed by  followed by
 .Sq \&Nd :  .Sq \&Nd :
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
Line 200  followed by 
Line 200  followed by 
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,  Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
 but non-compulsory.  but non-compulsory.
 .\" SECTION---------------------------------------------  .\" SECTION---------------------------------------------
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
 Every line beginning with the control character  Every line beginning with the control character
 .Sq \.  .Sq \.
 is processed for macros, two- or three-character sequences.  is processed for macros, two- or three-character sequences.
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
 The syntax of a macro depends on its classification.  In this section,  The syntax of a macro depends on its classification.  In this section,
 .Sq \-arg  .Sq \-arg
 refers to macro arguments, which may be followed by zero or more  refers to macro arguments, which may be followed by zero or more
 .Sq parm  .Sq parm
 parameters;  parameters;
Line 222  closes it out.
Line 222  closes it out.
 The  The
 .Em Callable  .Em Callable
 column indicates that the macro may be called subsequent to the initial  column indicates that the macro may be called subsequent to the initial
 line-macro.  The  line-macro.  The
 .Em Parsable  .Em Parsable
 column indicates whether the macro may be followed by further  column indicates whether the macro may be followed by further
 (ostensibly callable) macros.  The  (ostensibly callable) macros.  The
Line 235  contains bodies; only
Line 235  contains bodies; only
 .Pq Sq \&Bf  .Pq Sq \&Bf
 contains a head.  contains a head.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc  \&.Yc
 .Ed  .Ed
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
Line 255  contains a head.
Line 255  contains a head.
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss Block full-implicit  .Ss Block full-implicit
 Multi-line scope closed by end-of-file or implicitly by another macro.  Multi-line scope closed by end-of-file or implicitly by another macro.
 All macros have bodies; some  All macros have bodies; some
 .Po  .Po
 .Sq \&It \-bullet ,  .Sq \&It \-bullet ,
 .Sq \-hyphen ,  .Sq \-hyphen ,
 .Sq \-dash ,  .Sq \-dash ,
 .Sq \-enum ,  .Sq \-enum ,
 .Sq \-item  .Sq \-item
 .Pc  .Pc
 don't have heads, while  don't have heads, while
 .Sq \&It \-column  .Sq \&It \-column
 may have multiple heads.  may have multiple heads.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 .Ed  .Ed
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
Line 282  may have multiple heads.
Line 282  may have multiple heads.
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss Block partial-explicit  .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.  Each  Like block full-explicit, but also with single-line scope.  Each
 has at least a body and, in limited circumstances, a head  has at least a body and, in limited circumstances, a head
 .Pq So \&Fo Sc , So \&Eo Sc  .Pq So \&Fo Sc , So \&Eo Sc
 and/or tail  and/or tail
 .Pq So \&Ec Sc .  .Pq So \&Ec Sc .
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc \(lBtail...\(rB  \&.Yc \(lBtail...\(rB
   
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB  \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed  .Ed
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
Line 325  and/or tail 
Line 325  and/or tail 
 .El  .El
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss Block partial-implicit  .Ss Block partial-implicit
 Like block full-implicit, but with single-line scope closed by  Like block full-implicit, but with single-line scope closed by
 .Sx Reserved Characters  .Sx Reserved Characters
 or end of line.  or end of line.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
Line 349  or end of line.
Line 349  or end of line.
 .El  .El
 .\" SUB-SECTION----------------------  .\" SUB-SECTION----------------------
 .Ss In-line  .Ss In-line
 Closed by  Closed by
 .Sx Reserved Characters ,  .Sx Reserved Characters ,
 end of line, fixed argument lengths, and/or subsequent macros.  In-line  end of line, fixed argument lengths, and/or subsequent macros.  In-line
 macros have only text children.  If a number (or inequality) of  macros have only text children.  If a number (or inequality) of
 arguments is  arguments is
 .Pq n ,  .Pq n ,
 then the macro accepts an arbitrary number of arguments.  then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
Line 443  then the macro accepts an arbitrary number of argument
Line 443  then the macro accepts an arbitrary number of argument
 .\" SECTION---------------------------------------------  .\" SECTION---------------------------------------------
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 This section documents compatibility with other roff implementations, at  This section documents compatibility with other roff implementations, at
 this time limited to  this time limited to
 .Xr groff 1 .  .Xr groff 1 .
 The term  The term
 .Qq historic groff  .Qq historic groff
 refers to those versions before the  refers to those versions before the
 .Pa doc.tmac  .Pa doc.tmac
 file re-write  file re-write
 .Pq somewhere between 1.15 and 1.19 .  .Pq somewhere between 1.15 and 1.19 .
 .\" PARAGRAPH------------  .\" PARAGRAPH------------
 .Pp  .Pp
Line 461  standalone double-quote in formatted output.  This idi
Line 461  standalone double-quote in formatted output.  This idi
 behaviour is no longer applicable.  behaviour is no longer applicable.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&sp  .Sq \&sp
 macro does not accept negative numbers.  macro does not accept negative numbers.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 Some character sequences in groff are not handled depending on escape  Some character sequences in groff are not handled depending on escape
 style, e.g.,  style, e.g.,
 .Sq \e(ba  .Sq \e(ba
 and  and
 .Sq \e*(Ba  .Sq \e*(Ba
Line 485  some block-level macros) are now callable, conforming 
Line 485  some block-level macros) are now callable, conforming 
 non-historic groff version.  non-historic groff version.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The vertical bar  The vertical bar
 .Sq \(ba  .Sq \(ba
 made historic groff  made historic groff
 .Qq go orbital  .Qq go orbital
Line 504  syntax where column widths may be preceded by other ar
Line 504  syntax where column widths may be preceded by other ar
 of proceeded) is not supported.  of proceeded) is not supported.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&At  .Sq \&At
 macro only accepts a single parameter.  macro only accepts a single parameter.
 .\" LIST-ITEM  .\" LIST-ITEM
Line 521  it will obviously not render the subsequent sequence. 
Line 521  it will obviously not render the subsequent sequence. 
 versions of groff seem to dither on this.  versions of groff seem to dither on this.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 In groff, the  In groff, the
 .Sq \&Fo  .Sq \&Fo
 macro only produces the first parameter.  This is no longer the case.  macro only produces the first parameter.  This is no longer the case.
 .El  .El
Line 533  macro only produces the first parameter.  This is no l
Line 533  macro only produces the first parameter.  This is no l
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION---------------------------------------------  .\" SECTION---------------------------------------------
 .Sh CAVEATS  .Sh CAVEATS
Line 544  There are many ambiguous parts of mdoc.
Line 544  There are many ambiguous parts of mdoc.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 .Sq \&Fa  .Sq \&Fa
 should be  should be
 .Sq \&Va  .Sq \&Va
 as function arguments are variables.  as function arguments are variables.
 .\" LIST-ITEM  .\" LIST-ITEM
Line 567  variable name and optional, preceding type.
Line 567  variable name and optional, preceding type.
 .It  .It
 .Sq \&Fd  .Sq \&Fd
 is ambiguous.  It's commonly used to indicate an include file in the  is ambiguous.  It's commonly used to indicate an include file in the
 synopsis section.  synopsis section.
 .Sq \&In  .Sq \&In
 should be used, instead.  should be used, instead.
 .\" LIST-ITEM  .\" LIST-ITEM
Line 579  argument to
Line 579  argument to
 makes sense.  The remaining ones should be removed.  makes sense.  The remaining ones should be removed.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&Xo  .Sq \&Xo
 and  and
 .Sq \&Xc  .Sq \&Xc
Line 594  render when formatting the manual page.
Line 594  render when formatting the manual page.
 .It  .It
 A  A
 .Sq \&Lx  .Sq \&Lx
 should be provided for Linux (\(`a la  should be provided for Linux (\(`a la
 .Sq \&Ox ,  .Sq \&Ox ,
 .Sq \&Nx  .Sq \&Nx
 etc.).  etc.).
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
Line 605  There's no way to refer to references in
Line 605  There's no way to refer to references in
 blocks.  blocks.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The \-split and \-nosplit arguments to  The \-split and \-nosplit arguments to
 .Sq \&An  .Sq \&An
 are inane.  are inane.
 .El  .El

Legend:
Removed from v.1.49  
changed lines
  Added in v.1.50

CVSweb