Re: minor mdoc.7 improvements

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

> my point is that your description of Xo talks only in terms of using
> it for the It macro, but it can be used with many others.

OK, so lets try again.
Explaining it the other way round needs a bit more verbosity,
but i think it is worth spending the space because .Xo is
notoriously a source of confusion.

Yours,
  Ingo


Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.56
diff -u -r1.56 mdoc.7
--- mdoc.7	28 Nov 2010 15:45:26 -0000	1.56
+++ mdoc.7	28 Nov 2010 17:31:52 -0000
@@ -2659,9 +2659,60 @@
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xo
-Open an extension scope.
-This macro originally existed to extend the 9-argument limit of troff;
-since this limit has been lifted, the macro has been deprecated.
+Extend the header of an
+.Sx \&It
+macro or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .
+.Pp
+Regarding partial-implicit block macros, this has never been very useful
+because it is almost always better to use the corresponding
+partial-explicit block macro when many, long or complex arguments
+are required.
+For example, rewrite awkward code like
+.Bd -literal -offset indent
+\&.Op Fl s Ar modifier Xo
+\&.Op Fl R Ar id
+\&.Xc
+.Ed
+.Pp
+to the clear and fully portable form
+.Bd -literal -offset indent
+\&.Oo
+\&.Fl s Ar modifier
+\&.Op Fl R Ar id
+\&.Oc
+.Ed
+.Pp
+Thus, the only sensible use for
+.Sx \&Xo
+has been in
+.Sx \&It
+lines, for example:
+.Bd -literal -offset indent
+\&.It Xo
+\&.No if Ar list ;
+\&.No then Ar list ;
+\&.Oo elif Ar list ;
+\&.No then Ar list ; Oc
+\&.No ...
+\&.Oo else Ar list ; Oc
+\&.No fi
+\&.Xc
+.Ed
+.Pp
+Since the 9-argument limit has been lifted, it is now possible to use 
+line continuation with a backslash at the end of the line instead;
+but remeber that such code is not portable to historic
+.Nm
+implementations:
+.Bd -literal -offset indent
+\&.It if Ar list ; No then Ar list ; \e
+    Oo elif Ar list ; No then Ar list ; Oc No ... \e
+    Oo else Ar list ; Oc No fi
+.Ed
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv