Initial documentation in place for man.7.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index a28619fff75cc491809521d7edc70ff3a9068f20..186a92af62229dd708cffe7868a1869728dcd39c 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.8 2009/03/19 18:30:26 kristaps Exp $
+.\" $Id: mdoc.7,v 1.15 2009/03/23 16:02:56 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"


@@ -16,13 +16,13 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 

-.Dd $Mdocdate: March 19 2009 $
+.Dd $Mdocdate: March 23 2009 $

 .Dt mdoc 7
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc
 .Dt mdoc 7
 .Os
 .\" SECTION
 .Sh NAME
 .Nm mdoc

-.Nd mdoc macro reference
+.Nd mdoc language reference

 .\" SECTION
 .Sh DESCRIPTION
 The
 .\" SECTION
 .Sh DESCRIPTION
 The


@@ -30,24 +30,55 @@ The
 language is used to format 
 .Bx 
 .Ux
 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
 .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
 .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
 .\" SECTION

-.Sh CHARACTER ENCODING
+.Sh INPUT ENCODING

 .Nm
 .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
 .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:
 .\" SUB-SECTION
 .Ss Reserved Characters
 Within a macro line, the following characters are reserved:


@@ -130,16 +161,14 @@ Enclosures:
 .Pq left hand
 .It \\(rh
 .Pq right hand
 .Pq left hand
 .It \\(rh
 .Pq right hand

-.It \\(<<
+.It \\(Fo

 .Pq left guillemet
 .It \\(Fc
 .Pq right guillemet
 .Pq left guillemet
 .It \\(Fc
 .Pq right guillemet

-.It \\(Fo
+.It \\(fo

 .Pq left guilsing
 .It \\(fc
 .Pq right guilsing
 .Pq left guilsing
 .It \\(fc
 .Pq right guilsing

-.It \\(fo
-.Pq right guilsing

 .It \\(rC
 .Pq right brace
 .It \\(lC
 .It \\(rC
 .Pq right brace
 .It \\(lC


@@ -200,6 +229,60 @@ Indicatives:
 .Pp
 Mathematical:
 .Bl -tag -width 12n -offset "XXXX" -compact
 .Pp
 Mathematical:
 .Bl -tag -width 12n -offset "XXXX" -compact

+.It \\(es
+.Pq empty set
+.It \\(ca
+.Pq intersection
+.It \\(cu
+.Pq union
+.It \\(gr
+.Pq gradient
+.It \\(pd
+.Pq partial differential
+.It \\(ap
+.Pq similarity
+.It \\(=)
+.Pq proper superset
+.It \\((=
+.Pq proper subset
+.It \\(eq
+.Pq equals
+.It \\(di
+.Pq division
+.It \\(mu
+.Pq multiplication
+.It \\(pl
+.Pq addition
+.It \\(nm
+.Pq not element
+.It \\(mo
+.Pq element
+.It \\(Im
+.Pq imaginary
+.It \\(Re
+.Pq real
+.It \\(Ah
+.Pq aleph
+.It \\(te
+.Pq existential quantifier
+.It \\(fa
+.Pq universal quantifier
+.It \\(AN
+.Pq logical AND
+.It \\(OR
+.Pq logical OR
+.It \\(no
+.Pq logical NOT
+.It \\(st
+.Pq such that
+.It \\(tf
+.Pq therefore
+.It \\(~~
+.Pq approximate
+.It \\(~=
+.Pq approximately equals
+.It \\(=~
+.Pq congruent

 .It \\(Gt
 .Pq greater-than, deprecated
 .It \\(Lt
 .It \\(Gt
 .Pq greater-than, deprecated
 .It \\(Lt


@@ -428,8 +511,16 @@ Monetary:
 .Pp
 Special symbols:
 .Bl -tag -width 12n -offset "XXXX" -compact
 .Pp
 Special symbols:
 .Bl -tag -width 12n -offset "XXXX" -compact

-.It \\(bu
-.Pq bullet
+.It \\(de
+.Pq degree
+.It \\(ps
+.Pq paragraph
+.It \\(sc
+.Pq section
+.It \\(dg
+.Pq dagger
+.It \\(dd
+.Pq double dagger

 .It \\(ci
 .Pq circle
 .It \\(ba
 .It \\(ci
 .Pq circle
 .It \\(ba


@@ -453,7 +544,11 @@ Special symbols:
 .El 
 .\" SECTION
 .Sh ONTOLOGY
 .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 
 .\" SUB-SECTION
 .Ss Scope
 .Bl -inset 


@@ -653,6 +748,22 @@ close at the invocation's end-of-line.
 .It \&.Dl    Ta    \&No  Ta    Yes
 .It \&.Ql    Ta    Yes   Ta    Yes
 .El
 .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
 .\" SUB-SECTION
 .Ss Block partial-explicit
 Each of these contains at least a body and, in limited circumstances, a


@@ -706,25 +817,25 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&.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 \&.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 \&.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 \&.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 \&.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
 .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


@@ -743,7 +854,7 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&.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
 .It \&.Fx    Ta    Yes   Ta    Yes     Ta    n
 .It \&.Ms    Ta    \&No  Ta    Yes     Ta    >0
 .It \&.No    Ta    Yes   Ta    Yes     Ta    0


@@ -833,10 +944,7 @@ is callable.
 .El
 .\" SECTION
 .Sh SEE ALSO
 .El
 .\" SECTION
 .Sh SEE ALSO

-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Xr mandoc 1

 .\" SECTION
 .Sh AUTHORS
 The
 .\" SECTION
 .Sh AUTHORS
 The


@@ -905,4 +1013,9 @@ should be provided for Linux (\(`a la
 .Sq \&Ox ,
 .Sq \&Nx 
 etc.).
 .Sq \&Ox ,
 .Sq \&Nx 
 etc.).

+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&Rs/Re
+blocks.

 .El
 .El