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

Diff for /mandoc/mdoc.7 between version 1.3 and 1.4

version 1.3, 2009/03/13 13:56:13 version 1.4, 2009/03/14 05:21:58
Line 78  Within a macro line, the following characters are rese
Line 78  Within a macro line, the following characters are rese
 Use of these characters must either be escaped with a non-breaking space  Use of these characters must either be escaped with a non-breaking space
 .Pq Sq \e&  .Pq Sq \e&
 or, if applicable, an appropriate escape-sequence used.  Use of reserved  or, if applicable, an appropriate escape-sequence used.  Use of reserved
 characters is described later in this document.  characters is described in
   .Sx Closure .
 .\" SUB-SECTION  .\" SUB-SECTION
 .Ss Special Characters  .Ss Special Characters
 Special character sequences begin with the escape character  Special character sequences begin with the escape character
 .Sq \\  .Sq \\
 and 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 93  or a single one-character sequence.
Line 94  or a single one-character sequence.
 .Pp  .Pp
 Characters may alternatively be escaped by a slash-asterisk,  Characters may alternatively be escaped by a slash-asterisk,
 .Sq \\* ,  .Sq \\* ,
 with the same combinations as described above.  This form, however, is  with the same combinations as described above.  This form is deprecated.
 deprecated.  The following is a table of all available escapes, arranged  
 by classification.  
 .Pp  .Pp
   The following is a table of all available escapes.
   .Pp
 Grammatic:  Grammatic:
 .Bl -tag -width 12n -offset "XXXX" -compact  .Bl -tag -width 12n -offset "XXXX" -compact
 .It \\(em  .It \\(em
Line 228  Special symbols:
Line 229  Special symbols:
 .\" SECTION  .\" SECTION
 .Sh ONTOLOGY  .Sh ONTOLOGY
 Macros are classified in an ontology described by scope rules.  Macros are classified in an ontology described by scope rules.
   .\" SUB-SECTION
   .Ss Scope
 .Bl -inset  .Bl -inset
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Em Block  .It Em Block
 macros enclose other block macros, in-line macros or text, and  macros enclose other block macros, in-line macros or text, and
 may span multiple lines.  may span multiple lines.
 .Qq Implicit  
 block scope is closed by a subsequent invocation of the same macro,  
 one of a set of corresponding closure macros or end-of-file.  
 .Qq Explicit  
 block scope is closed by a corresponding closure macro.  
 .Bl -inset -offset XXXX  .Bl -inset -offset XXXX
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Em Full-block  .It Em Full-block
Line 259  text or macros following the head on the same and subs
Line 257  text or macros following the head on the same and subs
 optionally a  optionally a
 .Qq tail ,  .Qq tail ,
 text immediately following closure.  text immediately following closure.
 .El  
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Em In-line  .It Em In-line
 macros may only enclose text and span at most a single line.  If  macros may only enclose text and span at most a single line.
 a macro is parsable, its scope may be closed by subsequent macros or  
 delimiting punctuation.  In-line macros follow different conventions for  
 closure; see  
 .Sx MACROS  
 for per-macro details.  
 .El  .El
   .El
   .\" SUB-SECTION
   .Ss Closure
   Closure of a macro's scope depends first on its classification, then
   on whether it's parsable.  In this table,
   .Sq BFE
   refers to block full-explicit and so on.
   .\" PARAGRAPH
   .Pp
   .Bl -tag -width 12n -offset XXXX -compact
   .It BPE , BFE
   corresponding explicit closure macro
   .It BFI
   end-of-file or a corresponding implicit closure macro
   .It BPI
   end-of-line (body may be closed by >0 space-separated
   .Sx Reserved Characters ,
   although block scope will still be open)
   .It INL
   end-of-line
   .El
   .\" PARAGRAPH
   .Pp
   If a macro (block or in-line) is parsable, it may also be closed out by
   one of the following scenarios (unless specifically noted otherwise):
   .\" PARAGRAPH
   .Pp
   .Bl -dash -offset XXXX -compact
   .It
   a sequence of >0 space-separated
   .Sx Reserved Characters ,
   .It
   another macro,
   .It
   end-of-line, or
   .It
   completion of a set number of arguments.
   .El
   .\" PARAGRAPH
   .Pp
   If >0 space-separated
   .Sx Reserved Characters
   are followed by non-reserved characters, the behaviour differs per
   macro.  In general, scope of the macro is closed and re-opened:
   subsequent tokens are interpreted as if the scope had just been opened.
   In other circumstances, scope is simply closed out.
 .\" .\" SUB-SECTION  .\" .\" SUB-SECTION
 .\" .Ss Examples  .\" .Ss Examples
 .\" The following examples illustrate each macro classification.  .\" The following examples illustrate each macro classification.
Line 369  In these illustrations, 
Line 407  In these illustrations, 
 opens the scope of a macro, and if specified,  opens the scope of a macro, and if specified,
 .Sq \&.Yc  .Sq \&.Yc
 closes it out (closure may be implicit at end-of-line or end-of-file).  closes it out (closure may be implicit at end-of-line or end-of-file).
   .\" PARAGRAPH
 .Pp  .Pp
 Block full-explicit (may contain head, body, tail):  Block full-explicit (may contain head, body, tail).
 .Bd -literal -offset XXXX  .Bd -literal -offset XXXX
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc \(lBtail...\(rB  \&.Yc \(lBtail...\(rB
 .Ed  .Ed
   .\" PARAGRAPH
 .Pp  .Pp
 Block full-implicit (may contain zero or more heads, body, no tail):  Block full-implicit (may contain zero or more heads, body, no tail).
 .Bd -literal -offset XXXX  .Bd -literal -offset XXXX
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc  \&.Yc
 .Ed  .Ed
   .\" PARAGRAPH
 .Pp  .Pp
 Block partial-explicit (may contain head, multi-line body, tail):  Block partial-explicit (may contain head, multi-line body, tail).
 .Bd -literal -offset XXXX  .Bd -literal -offset XXXX
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc \(lBtail...\(rB  \&.Yc \(lBtail...\(rB
   
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB  \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed  .Ed
   .\" PARAGRAPH
 .Pp  .Pp
 Block partial-implicit (no head, body, no tail):  Block partial-implicit (no head, body, no tail).  Note that the body
   section may be followed by zero or more
   .Sx Reserved Words .
   These are in the block scope, but not in the body scope.
 .Bd -literal -offset XXXX  .Bd -literal -offset XXXX
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
 .Ed  .Ed
   .\" PARAGRAPH
 .Pp  .Pp
 In-line (may be closed by end-of-line, reserved character, subsequent  In-lines have \(>=0 scoped arguments.
 macro invocation or finite number of arguments):  
 .Bd -literal -offset XXX  .Bd -literal -offset XXX
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB args...  \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
   
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB args... ;  
   
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB args... Xx  
   
 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN  \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed  .Ed
 .\"  .\"
Line 589  then the macro accepts an arbitrary number of argument
Line 630  then the macro accepts an arbitrary number of argument
 .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0  .It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
 .El  .El
 .\" SECTION  .\" SECTION
   .Sh COMPATIBILITY
   The mdoc language was traditionally a
   .Qq roff
   macro package; most existing manuals were written with mdoc syntax
   dictated by system-dependent roff installations.  This section documents
   compatibility with these systems.
   .Pp
   .Bl -dash -compact
   .\" LIST-ITEM
   .It
   .Sq \&It \-nested
   is assumed for all lists: any list may be nested and
   .Sq \-enum
   lists will restart the sequence only for the sub-list.
   .\" LIST-ITEM
   .It
   .Sq \&It \-column
   syntax where column widths may be preceeded by other arguments (instead
   of proceeded) is not supported.
   .\" LIST-ITEM
   .It
   The
   .Sq \&At
   macro only accepts a single parameter.
   .\" LIST-ITEM
   .It
   The system-name macros (
   .Ns Sq \&At ,
   .Sq \&Bsx ,
   .Sq \&Bx ,
   .Sq \&Fx ,
   .Sq \&Nx ,
   .Sq \&Ox ,
   and
   .Sq \&Ux )
   are callable.
   .\" LIST-ITEM
   .It
   Some manuals use
   .Sq \&Li
   incorrectly by following it with a reserved character and expecting the
   delimiter to render.  This is not supported.
   .\" LIST-ITEM
   .It
   .Sq \&Cd
   is callable.
   .El
   .\" SECTION
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mdoctree 1 ,  .Xr mdoctree 1 ,
 .Xr mdoclint 1 ,  .Xr mdoclint 1 ,
 .Xr mdocterm 1 ,  .Xr mdocterm 1 ,
 .Xr mdoc 3  .Xr mdoc 3
 .\" SECTION  
 .Sh HISTORY  
 This manual describes the language accepted by  
 .Xr mdoc 3 ,  
 which implements the roff-mdoc macro package.  
 .\" SECTION  .\" SECTION
 .Sh AUTHORS  .Sh AUTHORS
 The  The
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4
CVSweb