===================================================================
RCS file: /cvs/mandoc/Attic/manuals.7,v
retrieving revision 1.5
retrieving revision 1.8
diff -u -p -r1.5 -r1.8
--- mandoc/Attic/manuals.7	2009/03/22 19:01:11	1.5
+++ mandoc/Attic/manuals.7	2009/03/23 09:42:43	1.8
@@ -1,4 +1,22 @@
-.Dd $Mdocdate: March 22 2009 $
+.\" $Id: manuals.7,v 1.8 2009/03/23 09:42:43 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 23 2009 $
 .Dt manuals 7
 .Os
 .\" SECTION
@@ -29,6 +47,8 @@ format or directory structure or device driver, it nee
 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!
@@ -72,7 +92,8 @@ 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
@@ -142,7 +163,12 @@ or, if not available,
 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 23 2009 $
+.Pp
+If using version control, the first line in your manual should be a
+comment with the 
+.Li $Id: manuals.7,v 1.8 2009/03/23 09:42:43 kristaps Exp $
+rcs tag.
 .\" SUBSECTION
 .Ss Viewing
 mdoc documents may be paged to your terminal with traditional 
@@ -181,6 +207,10 @@ output:
 \&.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 +240,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 .
+.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.
+.\" SUBSECTION
 .Ss References 
 Other components may be referenced with the
 .Sq \&Xr
@@ -229,20 +270,12 @@ 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.
+different from a component manual.