===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.6
retrieving revision 1.10
diff -u -p -r1.6 -r1.10
--- mandoc/Attic/manuals.7	2009/03/22 20:55:18	1.6
+++ mandoc/Attic/manuals.7	2009/03/26 23:01:26	1.10
@@ -1,4 +1,22 @@
-.Dd $Mdocdate: March 22 2009 $
+.\" $Id: manuals.7,v 1.10 2009/03/26 23:01:26 kristaps Exp $
+.\"
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the
+.\" above copyright notice and this permission notice appear in all
+.\" copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
+.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
+.\" 
+.Dd $Mdocdate: March 26 2009 $
 .Dt manuals 7
 .Os
 .\" SECTION
@@ -12,31 +30,26 @@
 .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 .
+.Pp
+If this file doesn't exist, bug your administrator.
 .Em \&Do not
 start afresh or by copying another manual unless you know exactly what
 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
@@ -72,13 +85,14 @@ to see the specific section manual (section 1, in this
 .\" DISPLAY
 .Bd -literal -offset indent
 % apropos myname
-myname (1) - some description here
+myname (1) - utility description
+myname (3) - library description
 % man \-s 1 myname
 .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
@@ -97,19 +111,12 @@ formatting language.
 .Pp
 There exist other documentation-specific languages, such as the
 historical
-.Xr me 7 ,
-.Xr ms 7
-and
 .Xr man 7
-packages of 
+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
@@ -137,50 +144,39 @@ 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 22 2009 $
+.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
+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
+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
@@ -210,6 +206,17 @@ symbols and so on), use the escapes dictated in
 .Xr mdoc 7 .
 .El
 .\" SUBSECTION
+.Ss Style
+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 .
+Find another way to structure your line.
+.\" SUBSECTION
 .Ss References 
 Other components may be referenced with the
 .Sq \&Xr
@@ -229,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