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

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 65121472136fbc314df835fbd340b9000f76165c..214f9018a8ae39030103aa83a9a5b1faac49c076 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.27 2009/06/12 09:18:00 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.30 2009/06/17 14:08:47 kristaps Exp $
 .\"
 .\" 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.
 .\" 
-.Dd $Mdocdate: June 12 2009 $
+.Dd $Mdocdate: June 17 2009 $
 .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
-language.
+language.  Our reference implementation is
+.Xr mandoc 1 .
+The
+.Sx COMPATIBILITY
+section describes compatibility with 
+.Xr groff 1 .
 .\" PARAGRAPH
 .Pp
 An
@@ -73,9 +78,19 @@ or
 .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:
-.Bl -tag -width 12n -offset XXXX -compact
+.Bl -tag -width Ds -offset XXXX -compact
 .It \&.
 .Pq period
 .It \&,
@@ -96,6 +111,8 @@ Within a macro line, the following characters are reserved:
 .Pq question
 .It \&!
 .Pq exclamation 
+.It \&|
+.Pq vertical bar 
 .El
 .\" PARAGRAPH
 .Pp
@@ -284,7 +301,7 @@ some
 .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
@@ -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
-.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
@@ -470,27 +487,34 @@ and
 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
-.Sq \&.An ,
-.Sq \&.Fo ,
-.Sq \&.Lk ,
-.Sq \&.Ms ,
-.Sq \&.Mt ,
-and
-.Sq \&.St
-historically weren't callable.
+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
-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
@@ -505,26 +529,17 @@ The
 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.
+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
@@ -538,7 +553,7 @@ utility was written by
 .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