`Bl -column' now correctly handles tail entries (Bl -column -more... arg0...).

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index d7ea42531a45fdb842390bb64474e4619cb66bc7..214f9018a8ae39030103aa83a9a5b1faac49c076 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.26 2009/06/11 20:02:37 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.30 2009/06/17 14:08:47 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: June 11 2009 $
+.Dd $Mdocdate: June 17 2009 $

 .Dt MDOC 7
 .Os
 .\" SECTION
 .Dt MDOC 7
 .Os
 .\" SECTION


@@ -31,7 +31,12 @@ language is used to format
 manuals.  In this reference document, we describe the syntax, ontology
 and structure of the 
 .Nm
 manuals.  In this reference document, we describe the syntax, ontology
 and structure of the 
 .Nm

-language.
+language.  Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with 
+.Xr groff 1 .

 .\" PARAGRAPH
 .Pp
 An
 .\" PARAGRAPH
 .Pp
 An


@@ -73,9 +78,19 @@ or
 .Sq \&.Bd \-unfilled
 contexts.
 .\" SUB-SECTION
 .Sq \&.Bd \-unfilled
 contexts.
 .\" SUB-SECTION

+.Ss Comments
+Anything following a
+.Sq \e" 
+delimiter is considered a comment (unless the 
+.Sq \e
+itself has been escaped) and is ignored to the end of line.
+Furthermore, a macro line with only a control character
+.Sq \. ,
+optionally followed by whitespace, is ignored.
+.\" SUB-SECTION

 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:

-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset XXXX -compact

 .It \&.
 .Pq period
 .It \&,
 .It \&.
 .Pq period
 .It \&,


@@ -96,6 +111,8 @@ Within a macro line, the following characters are reserved:
 .Pq question
 .It \&!
 .Pq exclamation 
 .Pq question
 .It \&!
 .Pq exclamation 

+.It \&|
+.Pq vertical bar 

 .El
 .\" PARAGRAPH
 .Pp
 .El
 .\" PARAGRAPH
 .Pp


@@ -284,7 +301,7 @@ some
 .Pc
 don't have heads.
 .Pp
 .Pc
 don't have heads.
 .Pp

-.Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "Closing"

 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
 .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
 .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
 .It \&.Sh    Ta    \&No    Ta    \&No    Ta    \&.Sh
 .It \&.Ss    Ta    \&No    Ta    \&No    Ta    \&.Sh, \&.Ss


@@ -296,7 +313,7 @@ None of these macros are callable or parsed.  The last column indicates
 the explicit scope rules.  All contains bodies, some may contain heads 
 .Pq So \&Bf Sc .
 .Pp
 the explicit scope rules.  All contains bodies, some may contain heads 
 .Pq So \&Bf Sc .
 .Pp

-.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
+.Bl -column -compact -offset XXXX "MacroX" "CallableX" "ParsableX" "closed by XXX"

 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
 .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
 .It \&.Bd    Ta    \&No    Ta    \&No    Ta    closed by \&.Ed
 .It \&.Ed    Ta    \&No    Ta    \&No    Ta    opened by \&.Bd


@@ -455,8 +472,8 @@ then the macro accepts an arbitrary number of arguments.
 .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0
 .It \&.Lb    Ta    \&No  Ta    \&No    Ta    1
 .It \&.Ap    Ta    Yes   Ta    Yes     Ta    0
 .It \&.Lp    Ta    \&No  Ta    \&No    Ta    0

-.It \&.Lk    Ta    \&No  Ta    Yes     Ta    >0
-.It \&.Mt    Ta    \&No  Ta    Yes     Ta    >0
+.It \&.Lk    Ta    Yes   Ta    Yes     Ta    n
+.It \&.Mt    Ta    Yes   Ta    Yes     Ta    >0

 .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
 .It \&.En    Ta    \&No  Ta    \&No    Ta    0
 .El
 .It \&.Es    Ta    \&No  Ta    \&No    Ta    0
 .It \&.En    Ta    \&No  Ta    \&No    Ta    0
 .El


@@ -470,25 +487,34 @@ and
 macros are obsolete.
 .\" SECTION
 .Sh COMPATIBILITY
 macros are obsolete.
 .\" 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.
+This section documents compatibility with other roff implementations, at
+this time limited to 
+.Xr groff 1 .
+The term 
+.Qq historic groff
+refers to those versions before the 
+.Pa doc.tmac
+file re-write 
+.Pq somewhere between 1.15 and 1.19 .

 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM
 .It
 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM
 .It

-.Sq \&.An ,
-.Sq \&.Fo ,
-.Sq \&.Ms ,
-and
-.Sq \&.St
-historically weren't callable (they are now).
+Historic groff has many un-callable macros.  Most of these (excluding
+some block-level macros) are now callable, conforming to the
+non-historic groff version.
+.\" LIST-ITEM
+.It
+The vertical bar 
+.Sq \(Ba
+made historic groff
+.Qq go orbital
+but is a proper delimiter in this implementation.

 .\" LIST-ITEM
 .It
 .Sq \&.It \-nested
 .\" LIST-ITEM
 .It
 .Sq \&.It \-nested

-is assumed for all lists: any list may be nested and
+is assumed for all lists (it wasn't in historic groff): any list may be
+nested and

 .Sq \-enum
 lists will restart the sequence only for the sub-list.
 .\" LIST-ITEM
 .Sq \-enum
 lists will restart the sequence only for the sub-list.
 .\" LIST-ITEM


@@ -503,26 +529,17 @@ The
 macro only accepts a single parameter.
 .\" LIST-ITEM
 .It
 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
 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.
+If an special-character control character 
+.Sq \e 
+is escaped, it will
+obviously not render the sequence.  Even newer versions of groff seem to
+dither on this.

 .El
 .\" SECTION
 .Sh SEE ALSO
 .El
 .\" SECTION
 .Sh SEE ALSO


@@ -536,7 +553,7 @@ utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS

-There are several ambiguous parts of mdoc.
+There are many ambiguous parts of mdoc.

 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM
 .Pp
 .Bl -dash -compact
 .\" LIST-ITEM