Clean up the description of .Dt:

- Volume and arch are both optional and not alternatives.
- Zap verbiage about what's obvious from the synopsis.
- For fixed argument strings, use .Cm, not .Ar.
Using lots of input from jmc@.

Also, state that the list of valid architectures varies by OS.
If a downstream distribution wants to provide a specific list,
maintaining a local patch is the way to go.

1 files changed, 14 insertions, 36 deletions

diff --git a/mdoc.7 b/mdoc.7
index 709b7a9a..cae93cca 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1282,7 +1282,8 @@ Its syntax is as follows:
 .Ar title
 .Oo
 .Ar section
-.Op Ar volume | arch
+.Op Ar volume
+.Op Ar arch
 .Oc
 .Oc
 .Ed
@@ -1363,42 +1364,19 @@ or
 .Ar CON
 .Pq contributed manuals .
 .It Ar arch
-This specifies a specific relevant architecture.
-If
-.Ar volume
-is not provided, it may be used in its place, else it may be used
-subsequent that.
-It, too, is optional.
-It must be one of
-.Ar alpha ,
-.Ar amd64 ,
-.Ar amiga ,
-.Ar arc ,
-.Ar arm ,
-.Ar armish ,
-.Ar aviion ,
-.Ar hp300 ,
-.Ar hppa ,
-.Ar hppa64 ,
-.Ar i386 ,
-.Ar landisk ,
-.Ar loongson ,
-.Ar luna88k ,
-.Ar mac68k ,
-.Ar macppc ,
-.Ar mips64 ,
-.Ar mvme68k ,
-.Ar mvme88k ,
-.Ar mvmeppc ,
-.Ar pmax ,
-.Ar sgi ,
-.Ar socppc ,
-.Ar sparc ,
-.Ar sparc64 ,
-.Ar sun3 ,
-.Ar vax ,
+This specifies the machine architecture a manual page applies to,
+where relevant, for example
+.Cm alpha ,
+.Cm amd64 ,
+.Cm i386 ,
 or
-.Ar zaurus .
+.Cm sparc64 .
+The list of supported architectures varies by operating system.
+For the full list of all architectures recognized by
+.Xr mandoc 1 ,
+see the file
+.Pa arch.in
+in the source distribution.
 .El
 .Pp
 Examples: