More documentation clarification.

diff --git a/Makefile b/Makefile
index 1ef0764a6bf1d783c62f50fdc8c3dd76126cdfe4..b7d83b37617ceb70764e65f29d0e382dab280c86 100644 (file)
--- 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 (file)
index 0000000..049c938
--- /dev/null
+++ b/manuals.7
@@ -0,0 +1,39 @@
+.Dd $Mdocdate: March 22 2009 $
+.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: 2009/03/22 08:52:27 $
+                                       </div>
+                               </td>
+                       </tr>
+               </tbody>
+       </table>
+       </body>
+</html>

diff --git a/mdoc.3 b/mdoc.3
index f7e32d04470386409e3e1a0dd572082e9bfbb805..959cca9716c76637b4376999ce419f39c12b754d 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.3,v 1.21 2009/03/21 21:09:00 kristaps Exp $
+.\" $Id: mdoc.3,v 1.22 2009/03/22 08:52:27 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -16,7 +16,7 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 21 2009 $
+.Dd $Mdocdate: March 22 2009 $
 .Dt mdoc 3
 .Os
 .\" SECTION
@@ -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 a659efc70c1aee3d4081dca1f86f1cce61c12293..6f0749f2c07cc2376f8014b32166c4c61eacc9c3 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.12 2009/03/21 13:47:02 kristaps Exp $
+.\" $Id: mdoc.7,v 1.13 2009/03/22 08:52:27 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -16,7 +16,7 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 21 2009 $
+.Dd $Mdocdate: March 22 2009 $
 .Dt mdoc 7
 .Os
 .\" SECTION
@@ -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