patch: improve mdoc(7) syntax in arlad.8

[Ingo Schwarze]

Dear colleagues,

the SYNOPSIS of the arlad(8) manual page uses overlapping blocks,
i.e. the sequence .Oo Xo Oc Xc.  This is a conceptual problem because
the blocks do not nest, it is not clear which block is the inner and
which is the outer one.  For example, such constructs cannot be rendered
into languages like SGML or XML, and some formatters error out, e.g.
mandoc(1), see http://mdocml.bsd.lv/.

The arlad(8) manual can be fixed nicely with the patch included below.
This is based on a patch by Jason McIntyre committed to the OpenBSD
tree, and i have tweaked it such that it applies to your current
rev. 1.22 of the file.

Note that, while here, we propose to use the \*(Ba escape sequence
to represent the vertical bar at all places for consistency -
it is already used at some places.

I checked that the patch
 - does not change rendering with groff-1.15
 - does not change rendering with groff-1.20.1
 - allows proper rendering with mandoc-1.9.15

Yours,
  Ingo


--- arlad.8.orig	Wed Feb 24 10:32:59 2010
+++ arlad.8	Wed Feb 24 10:38:49 2010
@@ -41,31 +41,31 @@
 .Sh SYNOPSIS
 .Nm
 .Bk -words
-.Op Fl t | Fl -test
-.Oo Fl c Ar string \*(Ba Xo
-.Fl -conffile= Ns Ar string Oc
-.Xc
-.Oo Fl l Ar string \*(Ba Xo
-.Fl -log= Ns Ar string Oc
-.Xc
+.Op Fl t \*(Ba Fl -test
+.Oo
+.Fl c Ar string \*(Ba Fl -conffile= Ns Ar string
+.Oc
+.Oo
+.Fl l Ar string \*(Ba Fl -log= Ns Ar string
+.Oc
 .Op Fl -debug= Ns Ar string
-.Oo Fl d Ar string \*(Ba Xo
-.Fl -device= Ns Ar string Oc
-.Xc
+.Oo
+.Fl d Ar string \*(Ba Fl -device= Ns Ar string
+.Oc
 .Op Fl -connected-mode= Ns Ar string
-.Op Fl n | Fl -no-fork
-.Oo Fl r Ar string \*(Ba Xo
-.Fl -rxkad-level= Ns Ar string Oc
-.Xc
-.Oo Fl s Ar string \*(Ba Xo
-.Fl -sysname= Ns Ar string Oc
-.Xc
+.Op Fl n \*(Ba Fl -no-fork
+.Oo
+.Fl r Ar string \*(Ba Fl -rxkad-level= Ns Ar string
+.Oc
+.Oo
+.Fl s Ar string \*(Ba Fl -sysname= Ns Ar string
+.Oc
 .Op Fl -root-volume= Ns Ar string
 .Op Fl -port= Ns Ar number
-.Op Fl z | Fl -recover
+.Op Fl z \*(Ba Fl -recover
 .Op Fl -cache-dir= Ns Ar string
 .Op Fl -tracefile= Ns Ar filename
-.Op Fl D | -dynroot
+.Op Fl D \*(Ba -dynroot
 .Op Fl -no-largefile
 .Op Fl -workers= Ns Ar number
 .Op Fl -cpu-usage