More documentation clarification.

4 files changed, 86 insertions, 9 deletions

diff --git a/Makefile b/Makefile
index 1ef0764a..b7d83b37 100644
--- a/Makefile
+++ b/Makefile
@@ -36,13 +36,13 @@ OBJS	   = $(LIBOBJS) $(MAINOBJS)
 SRCS	   = $(LIBSRCS) $(MAINSRCS)
 DATAS	   = arch.in att.in lib.in msec.in st.in vol.in ascii.in
 HEADS	   = mdoc.h private.h term.h 
-SGMLS	   = index.sgml
+SGMLS	   = index.sgml 
 HTMLS	   = index.html
 STATICS	   = style.css external.png
 TARGZS	   = mdocml-$(VERSION).tar.gz \
 	     mdocml-oport-$(VERSION).tar.gz \
 	     mdocml-nport-$(VERSION).tar.gz
-MANS	   = mandoc.1 mdoc.3 mdoc.7
+MANS	   = mandoc.1 mdoc.3 mdoc.7 manuals.7
 BINS	   = mandoc
 CLEAN	   = $(BINS) $(LNS) $(LLNS) $(LIBS) $(OBJS) $(HTMLS) $(TARGZS) 
 INSTALL	   = $(SRCS) $(HEADS) Makefile DESCR $(MANS) $(SGMLS) \
diff --git a/manuals.7 b/manuals.7
new file mode 100644
index 00000000..1f98a905
--- /dev/null
+++ b/manuals.7
@@ -0,0 +1,39 @@
+.Dd $Mdocdate$
+.Dt "Writing Unix Documentation" paper
+.Os
+.Sh NAME
+.Nm Writing Unix Documentation
+.Nd a guide to writing Unix manuals
+.Sh DESCRIPTION
+					<h1>
+					Writing Unix Documentation
+					</h1>
+
+					<p>
+					<span class="attn">A utility without documentation is of no utility at all.</span>
+					</p>
+
+					<p>
+					A system component's documentation describes the utility of that component, whether it's a device
+					driver, an executable or, most importantly, a game.  Although there are plenty of documents available on
+					how to <i>read</i> Unix documents, or where to find them, few focus on how to <i>write</i> them.
+					</p>
+
+					<p>
+					This document serves as a reference guide to writing Unix documentation.  If you add something to your
+					operating system, whether it's a new file format or directory structure or device driver, it needs
+					documentation.
+					</p>
+				</td>
+			</tr>
+			<tr>
+				<td>
+					<div class="foot">
+						Copyright &#169; 2009 Kristaps D&#382;onsons, $Date$
+					</div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</body>
+</html>
diff --git a/mdoc.3 b/mdoc.3
index eda5435d..132d736c 100644
--- a/mdoc.3
+++ b/mdoc.3
@@ -345,4 +345,7 @@ if not included.
 List-width suffix
 .Qq m
 isn't handled.
+.\" LIST-ITEM
+.It
+Contents of the SYNOPSIS section aren't checked.
 .El
diff --git a/mdoc.7 b/mdoc.7
index 492a8ef7..ba786c44 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -30,18 +30,33 @@ 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 .
@@ -529,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 
@@ -729,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