===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.13
retrieving revision 1.16
diff -u -p -r1.13 -r1.16
--- mandoc/Attic/manuals.7	2009/04/12 19:45:26	1.13
+++ mandoc/Attic/manuals.7	2009/07/16 22:16:44	1.16
@@ -1,6 +1,6 @@
-.\"	$Id: manuals.7,v 1.13 2009/04/12 19:45:26 kristaps Exp $
+.\"	$Id: manuals.7,v 1.16 2009/07/16 22:16:44 kristaps Exp $
 .\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: April 12 2009 $
+.Dd $Mdocdate: July 16 2009 $
 .Dt MANUALS 7
 .Os
 .\" SECTION
@@ -35,7 +35,7 @@ This document serves as a tutorial to writing 
 documentation
 .Pq Dq manuals .
 .\" SECTION
-.Sh COMPOSITION
+.Sh ENVIRONMENT
 First, copy over the manual template from 
 .Pa /usr/share/misc/mdoc.template
 into your source directory.
@@ -103,36 +103,6 @@ for this document.  Rename the template file:
 .Pp
 .Dl % mv mdoc.template myname.mysection
 .\" SUBSECTION
-.Ss Input Language
-Manuals should 
-.Em always 
-be written in the
-.Xr mdoc 7
-formatting language.
-.Pp
-There exist other documentation-specific languages, such as the
-historical
-.Xr man 7
-package of 
-.Xr roff 7 ;
-newer languages such as DocBook or texinfo; or even ad-hoc conventions
-such as README files.  
-.Em Avoid these formats .
-.Pp
-There are two canonical references for writing mdoc.  Read them.
-.Pp
-.\" LIST
-.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact
-.It Xr mdoc 7
-formal language reference
-.It Xr mdoc.samples 7
-macro reference
-.El
-.Pp
-Open the template you've copied into
-.Pa myname.mysection
-and begin editing.
-.\" SUBSECTION
 .Ss Development Tools
 While writing, make sure that your manual is correctly structured:
 .Pp
@@ -155,7 +125,7 @@ or
 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: April 12 2009 $
+.Dl \&.Dd $Mdocdate: July 16 2009 $
 .\" SUBSECTION
 .Ss Viewing
 mdoc documents may be paged to your terminal with 
@@ -184,15 +154,17 @@ Makefiles in order to automatically check your input:
 Your manual must have a license.  It should be listed at the start of
 your document, just as in source code.
 .\" SECTION
-.Sh BEST PRACTICES
-The
+.Sh COMPOSITION
+Manuals should 
+.Em always 
+be written in the
 .Xr mdoc 7
-and 
-.Xr mdoc.samples 7
-files are indispensable in guiding composition.  In this section, we
-introduce some 
-.Ux
-manual best practices:
+formatting language.
+.\" PARAGRAPH
+.Pp
+Open the template you've copied into
+.Pa myname.mysection
+and begin editing.
 .\" SUBSECTION
 .Ss Language
 .Bl -enum