Small clarity updates (section names, contents).

1 files changed, 14 insertions, 42 deletions

diff --git a/manuals.7 b/manuals.7
index c4be01fd..aba6d7f2 100644
--- a/manuals.7
+++ b/manuals.7
@@ -1,4 +1,4 @@
-.\"	$Id: manuals.7,v 1.15 2009/06/25 10:55:40 kristaps Exp $
+.\"	$Id: manuals.7,v 1.16 2009/07/16 22:16:44 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -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: June 25 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: June 25 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 practises:
+formatting language.
+.\" PARAGRAPH
+.Pp
+Open the template you've copied into
+.Pa myname.mysection
+and begin editing.
 .\" SUBSECTION
 .Ss Language
 .Bl -enum