=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.9 retrieving revision 1.13 diff -u -p -r1.9 -r1.13 --- mandoc/mdoc.7 2009/03/19 20:43:13 1.9 +++ mandoc/mdoc.7 2009/03/22 08:52:27 1.13 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.9 2009/03/19 20:43:13 kristaps Exp $ +.\" $Id: mdoc.7,v 1.13 2009/03/22 08:52:27 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -16,7 +16,7 @@ .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 19 2009 $ +.Dd $Mdocdate: March 22 2009 $ .Dt mdoc 7 .Os .\" SECTION @@ -30,24 +30,55 @@ The language is used to format .Bx .Ux -manuals. An +manuals. In this reference document, we describe the syntax, ontology +and structure of the .Nm +language. +.\" PARAGRAPH +.Pp +An +.Nm document follows simple rules: lines beginning with the control -character +character .Sq \. are parsed for macros. Other lines are interpreted within the scope of -prior macros. This document describes the encoding, ontology and syntax -of these macros. +prior macros: +.Bd -literal -offset XXX +\&.Sh Macro lines change control state. +Other lines are interpreted within the current state. +.Ed +.\" PARAGRAPH +.Pp +Macros are two- or three-character sequences whose scope rules, rules +that dictate handling of subsequent-line or same-line arguments, are +governed by one of five classifications described in this document. .\" SECTION -.Sh CHARACTER ENCODING +.Sh INPUT ENCODING .Nm -documents may contain only printable characters, the space character +documents may contain only graphable 7-bit ASCII characters, the space +character .Sq \ , and, in certain circumstances, the tab character .Sq \et . All manuals must have .Sq \en -line termination. +line termination. +.Pp +The only time a blank line is acceptable is within +the context of +.Sq \&Bd \-literal +or +.Sq \&Bd \-unfilled . +.Pp +Tab characters +.Pq \et +are only acceptable when delimiting +.Sq \&Bl \-column +and in +.Sq \&Bd \-literal +or +.Sq \&Bd \-unfilled +contexts. .\" SUB-SECTION .Ss Reserved Characters Within a macro line, the following characters are reserved: @@ -513,7 +544,11 @@ Special symbols: .El .\" SECTION .Sh ONTOLOGY -Macros are classified in an ontology described by scope rules. +Macros are classified in an ontology described by their scope rules. +Some macros are allowed to deviate from their classifications to +preserve backward-compatibility with old macro combinations still found +in the manual corpus. These are specifically noted on a per-macro +basis. .\" SUB-SECTION .Ss Scope .Bl -inset @@ -713,6 +748,22 @@ close at the invocation's end-of-line. .It \&.Dl Ta \&No Ta Yes .It \&.Ql Ta Yes Ta Yes .El +.\" PARAGRAPH +.Pp +The +.Sq \&Op +may be broken by \&Oc as in the following example: +.Bd -literal -offset XXXX +\&.Oo +\&.Op Fl a Oc +.Ed +.Pp +In the above example, the scope of +.Sq \&Op +is technically broken by +.Sq \&Oc , +however, due to the overwhelming existence of this sequence, it's +allowed. .\" SUB-SECTION .Ss Block partial-explicit Each of these contains at least a body and, in limited circumstances, a @@ -766,25 +817,25 @@ then the macro accepts an arbitrary number of argument .It \&.Ar Ta Yes Ta Yes Ta n .It \&.Cd Ta Yes Ta \&No Ta >0 .It \&.Cm Ta Yes Ta Yes Ta n -.It \&.Dv Ta Yes Ta Yes Ta >0 +.It \&.Dv Ta Yes Ta Yes Ta n .It \&.Er Ta Yes Ta Yes Ta >0 -.It \&.Ev Ta Yes Ta Yes Ta >0 +.It \&.Ev Ta Yes Ta Yes Ta n .It \&.Ex Ta \&No Ta \&No Ta 0 -.It \&.Fa Ta Yes Ta Yes Ta >0 +.It \&.Fa Ta Yes Ta Yes Ta n .It \&.Fd Ta \&No Ta \&No Ta >0 .It \&.Fl Ta Yes Ta Yes Ta n .It \&.Fn Ta Yes Ta Yes Ta >0 .It \&.Ft Ta \&No Ta Yes Ta n .It \&.Ic Ta Yes Ta Yes Ta >0 .It \&.In Ta \&No Ta \&No Ta n -.It \&.Li Ta Yes Ta Yes Ta >0 +.It \&.Li Ta Yes Ta Yes Ta n .It \&.Nd Ta \&No Ta \&No Ta n .It \&.Nm Ta Yes Ta Yes Ta n .It \&.Ot Ta \&No Ta \&No Ta n .It \&.Pa Ta Yes Ta Yes Ta n .It \&.Rv Ta \&No Ta \&No Ta 0 .It \&.St Ta \&No Ta Yes Ta 1 -.It \&.Va Ta Yes Ta Yes Ta >0 +.It \&.Va Ta Yes Ta Yes Ta n .It \&.Vt Ta Yes Ta Yes Ta >0 .It \&.Xr Ta Yes Ta Yes Ta >0, <3 .It \&.%A Ta \&No Ta \&No Ta >0 @@ -803,7 +854,7 @@ then the macro accepts an arbitrary number of argument .It \&.Bsx Ta Yes Ta Yes Ta n .It \&.Bx Ta Yes Ta Yes Ta n .It \&.Db Ta \&No Ta \&No Ta 1 -.It \&.Em Ta Yes Ta Yes Ta >0 +.It \&.Em Ta Yes Ta Yes Ta n .It \&.Fx Ta Yes Ta Yes Ta n .It \&.Ms Ta \&No Ta Yes Ta >0 .It \&.No Ta Yes Ta Yes Ta 0