===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.9
retrieving revision 1.12
diff -u -p -r1.9 -r1.12
--- mandoc/Attic/manuals.7	2009/03/24 10:59:50	1.9
+++ mandoc/Attic/manuals.7	2009/04/12 19:19:57	1.12
@@ -1,4 +1,4 @@
-.\" $Id: manuals.7,v 1.9 2009/03/24 10:59:50 kristaps Exp $
+.\" $Id: manuals.7,v 1.12 2009/04/12 19:19:57 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
 .\"
@@ -16,8 +16,8 @@
 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 .\" PERFORMANCE OF THIS SOFTWARE.
 .\" 
-.Dd $Mdocdate: March 24 2009 $
-.Dt manuals 7
+.Dd $Mdocdate: April 12 2009 $
+.Dt MANUALS 7
 .Os
 .\" SECTION
 .Sh NAME
@@ -30,33 +30,27 @@
 .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
-from 
-.Pa /usr/share/misc/mdoc.template .
+First, copy over the manual template from 
+.Pa /usr/share/misc/mdoc.template
+into your source directory.
 .Pp
-If this file doesn't exist, bug your administrator.
+.Dl % cp /usr/share/misc/mdoc.template \.
+.Pp
 .Em \&Do not
 start afresh or by copying another manual unless you know exactly what
-you're doing!
+you're doing!  If the template doesn't exist, bug your administrator.
 .\" 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 +92,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
@@ -107,7 +101,9 @@ Manual files are named 
 .Pa myname.mysection ,
 such as
 .Pa manuals.7
-for this document.
+for this document.  Rename the template file:
+.Pp
+.Dl % mv mdoc.template myname.mysection
 .\" SUBSECTION
 .Ss Input Language
 Manuals should 
@@ -121,13 +117,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
@@ -140,7 +132,7 @@ macro reference
 .El
 .Pp
 Open the template you've copied into
-.Pa name.section
+.Pa myname.mysection
 and begin editing.
 .\" SUBSECTION
 .Ss Development Tools
@@ -151,58 +143,43 @@ While writing, make sure that your manual is correctly
 You may spell-check your work as follows:
 .Pp
 .Dl % deroff name.1 | spell
+.Pp
+If 
+.Xr ispell 1
+is installed, it has a special mode for manuals:
+.Pp
 .Dl % ispell \-n name.1
 .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: April 12 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
+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
-% nroff \-mandoc name.1 | less
-% groff \-Tascii \-mandoc name.1 | less
-% mandoc name.1 | less
+% mandoc \-Wall name.1 2>&1 | less
+% groff -mandoc name.1 2>&1 | less
 .Ed
-.Pp
-Other output formats are also supported:
-.\" DISPLAY
-.Bd -literal -offset indent
-% groff \-Tps \-mandoc name.1 | less
-% mandoc \-Thtml name.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 +219,11 @@ The structure of the mdoc language makes it very hard 
 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,12 +244,14 @@ 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
 .Sh MAINTENANCE
 As your component changes and bugs are fixed, your manual may become out
-of date.  You may be tempted to use automation tools like Doxygen to
-smooth the development of your manuals.  Don't.  Source documentation is
-different from a component manual. 
+of date.  You may be tempted to use tools like Doxygen to automate the
+development of your manuals.  Don't.
+.Pp
+.Em Manuals are part of a system component :
+if you modify your code or specifications, modify the documentation.