expand the description of .Dt:

- list the possible sections, and what they are
- update list of volume titles
- document that archs can be added to .Dt, and list the possibilities

1 files changed, 55 insertions, 3 deletions

diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7
index 4235957aca8..af801df12ef 100644
--- a/share/man/man7/mdoc.samples.7
+++ b/share/man/man7/mdoc.samples.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mdoc.samples.7,v 1.55 2004/06/30 15:14:18 jmc Exp $
+.\"	$OpenBSD: mdoc.samples.7,v 1.56 2004/06/30 21:10:08 jmc Exp $
 .\"	$NetBSD: mdoc.samples.7,v 1.5 1996/04/03 20:17:34 jtc Exp $
 .\"
 .\" Copyright (c) 1990, 1993
@@ -586,12 +586,49 @@ subject of the man page and must be in
 .Tn CAPITALS
 due to troff
 limitations.
-The section number may be 1,\ ...,\ 9.
+If omitted,
+.Sq UNTITLED
+is used.
+The section number may be a number in the range 1\-9,
+or
+.Sq unass ,
+.Sq draft ,
+or
+.Sq paper .
+The following section numbers are defined:
+.Pp
+.Bl -tag -width "3p " -offset indent -compact
+.It 1
+General commands
+.Pq tools and utilities
+.It 2
+System calls and error numbers
+.It 3
+Libraries
+.It 3p
+.Xr perl 1
+programmer's reference guide
+.It 4
+Device drivers
+.It 5
+File formats
+.It 6
+Games
+.It 7
+Miscellaneous
+.It 8
+System maintenance and operation commands
+.It 9
+Kernel internals
+.El
+.Pp
 The volume title is optional; if specified, it should be one of the following:
 .Pp
-.Bl -column SMM -offset indent -compact
+.Bl -column LOCAL -offset indent -compact
 .It Li AMD	OpenBSD Ancestral Manual Documents
+.It Li IND	OpenBSD Manual Master Index
 .It Li KM	OpenBSD Kernel Manual
+.It Li LOCAL	OpenBSD Local Manual
 .It Li PRM	OpenBSD Programmer's Manual
 .It Li PS1	OpenBSD Programmer's Supplementary Documents
 .It Li SMM	OpenBSD System Manager's Manual
@@ -608,6 +645,21 @@ for section 8;
 for sections 2, 3, 4, and 5;
 .Li KM
 for section 9.
+.Pp
+If the third argument to
+.Ql \&.Dt
+is instead a machine architecture,
+it will be displayed,
+surrounded by parentheses,
+next to the volume title.
+This is useful for pages specific only to a particular architecture.
+The architectures currently defined are:
+.Bd -unfilled -offset indent
+alpha, amd64, amiga, arc, arm32, atari, cats, hp300,
+hppa, i386, luna88k, mac68k, macppc, mvme68k, mvme88k,
+mvmeppc, pc532, pegasos, pmax, sparc, sparc64, sun3,
+tahoe, vax, x68k
+.Ed
 .It Li \&.Os operating_system release#
 The name of the operating system
 should be a common acronym, e.g.,