-.\" $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>
.\"
.\" 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
-.Nd mdoc macro reference
+.Nd mdoc language reference
.\" SECTION
.Sh DESCRIPTION
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:
.Pq left hand
.It \\(rh
.Pq right hand
-.It \\(<<
+.It \\(Fo
.Pq left guillemet
.It \\(Fc
.Pq right guillemet
-.It \\(Fo
+.It \\(fo
.Pq left guilsing
.It \\(fc
.Pq right guilsing
-.It \\(fo
-.Pq right guilsing
.It \\(rC
.Pq right brace
.It \\(lC
.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
.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
.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
.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
.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
.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
.El
.\" SECTION
.Sh SEE ALSO
-.Xr mdoctree 1 ,
-.Xr mdoclint 1 ,
-.Xr mdocterm 1 ,
-.Xr mdoc 3
+.Xr mandoc 1
.\" SECTION
.Sh AUTHORS
The
.Sq \&Ox ,
.Sq \&Nx
etc.).
+.\" LIST-ITEM
+.It
+There's no way to refer to references in
+.Sq \&Rs/Re
+blocks.
.El
git.ckatri.com / mandoc.git / blobdiff