Clean-ups to documentation.

3 files changed, 38 insertions, 87 deletions

diff --git a/man.7 b/man.7
index 6ce607ca..df187523 100644
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\" $Id: man.7,v 1.4 2009/03/26 16:23:22 kristaps Exp $
+.\" $Id: man.7,v 1.5 2009/03/26 23:01:26 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -53,10 +53,6 @@ prior macros:
 \&.SH Macro lines change control state.
 Other lines are interpreted within the current state.
 .Ed
-.\" PARAGRAPH
-.Pp
-Macros are character sequences whose structural rules are described
-later in this document.
 .\" SECTION
 .Sh INPUT ENCODING
 .Nm
@@ -64,10 +60,11 @@ documents may contain only graphable 7-bit ASCII characters and the
 space character
 .Sq \  .
 All manuals must have
+.Ux
 .Sq \en
 line termination.  
 .Pp
-Blank lines are acceptable; where found, the output will also assert a
+Blank lines are acceptable; where found, the output will assert a
 vertical space.
 .Pp
 The
@@ -135,25 +132,15 @@ and
 .Sq \&.RI .
 When these macros are invoked without arguments, the subsequent line is
 considered a continuation of the macro.  Thus:
-.Bd -literal -offset indent
-\&.RI foo
-.Ed
-.Pp
-and
-.Bd -literal -offset indent 
-\&.RI 
-foo
-.Ed
-.Pp
-are equivalent.  If two consecutive lines exhibit the latter behaviour,
-an error is raised.  Thus, the following is acceptable:
 .Bd -literal -offset indent 
 \&.RI 
-\&.I Hello, world.
 foo
 .Ed
 .Pp
-The following, however, is not:
+is equivalent to 
+.Sq \&.RI foo .  
+If two consecutive lines exhibit the latter behaviour,
+an error is raised.  Thus, the following is not acceptable:
 .Bd -literal -offset indent 
 \&.RI 
 \&.I 
@@ -162,13 +149,13 @@ Hello, world.
 .Pp
 The
 .Sq \&.TP
-macro has similar behaviour, but does not need an empty argument line in
-order to trigger scope.
+macro is similar, but does not need an empty argument line to trigger
+the behaviour.
 .\" PARAGRAPH
 .Sh MACROS
 This section contains a complete list of all 
 .Nm
-macros, arranged alphabetically, with the number of arguments.
+macros and corresponding number of arguments.
 .Pp
 .Bl -column "MacroX" "Arguments" -compact -offset indent
 .It Em Macro Ta Em Arguments
diff --git a/manuals.7 b/manuals.7
index f4fc9b09..eb793b35 100644
--- a/manuals.7
+++ b/manuals.7
@@ -1,4 +1,4 @@
-.\" $Id: manuals.7,v 1.9 2009/03/24 10:59:50 kristaps Exp $
+.\" $Id: manuals.7,v 1.10 2009/03/26 23:01:26 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 24 2009 $
+.Dd $Mdocdate: March 26 2009 $
 .Dt manuals 7
 .Os
 .\" SECTION
@@ -30,18 +30,12 @@
 .Pp
 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 read 
-.Ux 
-documents, or where to find them, few focus on composition.
-.\" PARAGRAPH
+importantly, a game.  
 .Pp
 This document serves as a tutorial to writing 
 .Ux 
 documentation
 .Pq Dq manuals .
-If you add something to your operating system, whether it's a new file
-format or directory structure or device driver, it needs documentation.
 .\" SECTION
 .Sh COMPOSITION
 Prepare your composition environment by copying over the manual template
@@ -55,8 +49,7 @@ you're doing!
 .\" SUBSECTION
 .Ss Section Numbering
 Find an appropriate section for your manual.  There may exist multiple
-manual names per section, so be specific.  A table of all available
-manual sections follows:
+manual names per section, so be specific:
 .Pp
 .\" LIST
 .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact
@@ -98,8 +91,8 @@ myname (3) - library description
 .Ed
 .\" SUBSECTION
 .Ss Naming
-Name your component.  Be terse, erring on the side of clarity.  You may
-want to look for other manuals by that same name before committing:
+Name your component.  Be terse, erring on the side of clarity.  Look for
+other manuals by that same name before committing:
 .Pp
 .Dl % apropos myname
 .Pp
@@ -121,13 +114,9 @@ historical
 .Xr man 7
 package of 
 .Xr roff 7 ;
-newer languages such as DocBook, texinfo or schema-driven XML; or even
-ad-hoc conventions such as README files.  
+newer languages such as DocBook or texinfo; or even ad-hoc conventions
+such as README files.  
 .Em Avoid these formats .
-Historical formats fail to capture a manual's semantic content, instead
-only modelling its style.  Newer methods requires special,
-system-specific tools and may change or become obsolete over the
-life-time of your component.
 .Pp
 There are two canonical references for writing mdoc.  Read them.
 .Pp
@@ -155,54 +144,34 @@ You may spell-check your work as follows:
 .Pp
 Use 
 .Xr cvs 1
-or, if not available,
+or
 .Xr rcs 1
 to version-control your work.  If you wish the last check-in to effect
 your document's date, use the following RCS tag for the date macro:
 .Pp
-.Dl \&.Dd $Mdocdate: March 24 2009 $
-.Pp
-If using version control, the first line in your manual should be a
-comment with the 
-.Li $Id: manuals.7,v 1.9 2009/03/24 10:59:50 kristaps Exp $
-rcs tag.
+.Dl \&.Dd $Mdocdate: March 26 2009 $
 .\" SUBSECTION
 .Ss Viewing
-mdoc documents may be paged to your terminal with traditional 
-tools such as
-.Xr nroff 1 ,
-.Xr groff 1 ,
-or with newer, more powerful tools such as
-.Xr mandoc 1 :
-.\" DISPLAY
-.Bd -literal -offset indent
-% nroff \-mandoc name.1 | less
-% groff \-Tascii \-mandoc name.1 | less
-% mandoc name.1 | less
-.Ed
-.Pp
-Other output formats are also supported:
-.\" DISPLAY
+mdoc documents may be paged to your terminal with 
+.Xr mandoc 1 .
+If you plan on distributing your work to systems without this tool,
+check it against
+.Xr groff 1 :
 .Bd -literal -offset indent
-% groff \-Tps \-mandoc name.1 | less
-% mandoc \-Thtml name.1 | less
+% mandoc \-Wall name.1 2>&1 | less
+% groff -mandoc name.1 2>&1 | less
 .Ed
 .\" SUBSECTION
 .Ss Automation
 Consider adding your mdoc documents to 
 .Xr make 1
-Makefiles in order to automatically check your input and generate
-output:
+Makefiles in order to automatically check your input:
 .Bd -literal -offset indent
-\&.SUFFIXES: .html .txt .1 .in
+\&.SUFFIXES: .1 .in
 
 \&.in.1:
 	mandoc -Wall,error -Tlint $<
 	cp -f $< $@
-\&.1.html:
-	mandoc -Thtml $< >$@
-\&.1.txt:
-	mandoc -Tascii $< | col -b >$@
 .Ed
 .\" SUBSECTION
 .Ss Licensing
@@ -242,11 +211,11 @@ The structure of the mdoc language makes it very hard to have any
 particular format style.  Keep your lines under 72 characters in length.
 If you must have long option lines, use 
 .Sq \&Oo/Oc .
+The same goes for function prototypes.
 .Em \&Do not
 use 
-.Sq \&Xo/Xc ;
-instead, either fine another way to write long lines, or, at the
-absolute worst, use CPP-style newline escapes.
+.Sq \&Xo/Xc .
+Find another way to structure your line.
 .\" SUBSECTION
 .Ss References 
 Other components may be referenced with the
@@ -267,7 +236,7 @@ publications, please use the
 block macros.
 .\" SUBSECTION
 .Ss Formatting
-.Em Don't style your manual.
+.Em Don't style your manual .
 Give it meaningful content.  The front-end will worry about formatting
 and style.
 .\" SECTION
diff --git a/mdoc.7 b/mdoc.7
index 11af24ad..90f1f68a 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\" $Id: mdoc.7,v 1.16 2009/03/26 16:23:22 kristaps Exp $
+.\" $Id: mdoc.7,v 1.17 2009/03/26 23:01:26 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -47,11 +47,6 @@ prior macros:
 \&.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 INPUT ENCODING
 .Nm
@@ -543,7 +538,7 @@ Special symbols:
 .Pq ampersand, deprecated
 .El 
 .\" SECTION
-.Sh ONTOLOGY
+.Sh STRUCTURE
 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
@@ -630,8 +625,8 @@ subsequent tokens are interpreted as if the scope had just been opened.
 In other circumstances, scope is simply closed out.
 .\" SECTION
 .Sh SYNTAX
-Macros are generally two and at times three characters in length.  The
-syntax of macro invocation depends on its classification.  
+Macros are two or three characters in length.  The syntax of macro
+invocation depends on its classification.  
 .Qq \-arg
 refers to the macro arguments (which may contain zero or more values).
 In these illustrations, 
@@ -689,7 +684,7 @@ This section contains a complete list of all
 .Nm
 macros, arranged ontologically.  A 
 .Qq callable
-macro is may be invoked subsequent to the initial macro-line macro.  A
+macro is invoked subsequent to the initial macro-line macro.  A
 .Qq parsable
 macro may be followed by further (ostensibly callable) macros.
 .\" SUB-SECTION