===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.5
retrieving revision 1.20
diff -u -p -r1.5 -r1.20
--- mandoc/Attic/manuals.7	2009/03/22 19:01:11	1.5
+++ mandoc/Attic/manuals.7	2010/04/13 05:26:49	1.20
@@ -1,5 +1,21 @@
-.Dd $Mdocdate: March 22 2009 $
-.Dt manuals 7
+.\"	$Id: manuals.7,v 1.20 2010/04/13 05:26:49 kristaps Exp $
+.\"
+.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
+.\"
+.\" 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: April 13 2010 $
+.Dt MANUALS 7
 .Os
 .\" SECTION
 .Sh NAME
@@ -12,31 +28,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 
+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 .
+.Sh ENVIRONMENT
+First, copy over the manual template from
+.Pa /usr/share/misc/mdoc.template
+into your source directory.
+.Pp
+.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
@@ -54,7 +66,7 @@ file and wire protocol formats
 games
 .It 7
 tutorials, documents and papers
-.It 8 
+.It 8
 administrator utilities
 .It 9
 in-kernel routines
@@ -72,128 +84,99 @@ 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
-Manual files are named 
+Manual files are named
 .Pa myname.mysection ,
 such as
 .Pa manuals.7
-for this document.
-.\" SUBSECTION
-.Ss Input Language
-Manuals should 
-.Em always 
-be written in the
-.Xr mdoc 7
-formatting language.
+for this document.  Rename the template file:
 .Pp
-There exist other documentation-specific languages, such as the
-historical
-.Xr me 7 ,
-.Xr ms 7
-and
-.Xr man 7
-packages of 
-.Xr roff 7 ;
-newer languages such as DocBook, texinfo or schema-driven XML; 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
-.\" 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 name.section
-and begin editing.
+.Dl % mv mdoc.template myname.mysection
 .\" SUBSECTION
 .Ss Development Tools
 While writing, make sure that your manual is correctly structured:
 .Pp
-.Dl % mandoc \-Tlint \-Wall name.1
+.Dl % mandoc \-Tlint \-Wall \-fstrict name.1
 .Pp
+The quick-fix feature of
+.Xr vim 1
+is useful for checking over many manuals:
+.Bd -literal -offset indent
+% mandoc \-Wall \-fstrict \-Tlint \-fign-errors \e
+  ./path/to/manuals/* 2>&1 > /tmp/mandoc.errs
+% vim -q /tmp/mandoc.errs
+.Ed
+.Pp
 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 
+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: April 13 2010 $
 .\" 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 
+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
+.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 
+.Bl -enum
 .It
 Use clear, concise language.  Favour simplicity.
 .It
@@ -210,7 +193,18 @@ symbols and so on), use the escapes dictated in
 .Xr mdoc 7 .
 .El
 .\" SUBSECTION
-.Ss References 
+.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
 and
@@ -229,20 +223,14 @@ publications, please use the
 block macros.
 .\" SUBSECTION
 .Ss Formatting
-Let the front-ends worry about formatting for you, but if you must think
-about formatting (at times necessary, especially for tagged and columnar
-lists), assume that your output device is a fixed-width terminal window:
-.Bd -literal -offset indent
-\&.Bl \-tag \-width "-o outfile"
-\&.It \&Fl \&Ar outfile
-.Ed
-.Pp
-You may assume that the width calculated by the string literal 
-.Qq Fl o Ar outfile
-will be covered by the \-width argument.
+.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.