From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id oARMRAFY021892 for ; Sat, 27 Nov 2010 17:27:12 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1PMTEb-0007KP-G4; Sat, 27 Nov 2010 23:27:09 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1PMTEb-0001oq-Eo; Sat, 27 Nov 2010 23:27:09 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1PMTEb-0004Uw-Dq; Sat, 27 Nov 2010 23:27:09 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1PMTEb-000550-D5; Sat, 27 Nov 2010 23:27:09 +0100 Date: Sat, 27 Nov 2010 23:27:09 +0100 From: Ingo Schwarze To: jmc@openbsd.org Cc: tech@mdocml.bsd.lv Subject: minor mdoc.7 improvements Message-ID: <20101127222709.GE27534@iris.usta.de> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Hi, at some point in the past, i started checking whether the stuff explained in mdoc.samples(7) is also made clear in our own manuals. I didn't get very far at that time, but wrote up a few improvements to mdoc.7 and then forgot about them. Now i ran into them by chance, and even though i'm currently working in a different corner and not planning to return to mdoc.samples(7) right now, i could as well put in what i have, which is: - Use a more rigorous wording when explaining the "callable" and "parsed" properties of mdoc macros. - Instead of the cold and fuzzy statement that .Xo is deprecated, explain in more detail what it can be used for and what can be done instead. - Be more specific about the time of the doc.tmac rewrite. - Explicitly list the limition of the number of arguments in historic groff as a COMPATIBILITY issue. OK? Yours, Ingo Index: mdoc.7 =================================================================== RCS file: /cvs/src/share/man/man7/mdoc.7,v retrieving revision 1.55 diff -u -r1.55 mdoc.7 --- mdoc.7 29 Oct 2010 10:36:08 -0000 1.55 +++ mdoc.7 27 Nov 2010 22:18:45 -0000 @@ -604,20 +604,21 @@ .Pp The .Em Callable -column indicates that the macro may be called subsequent to the initial -line-macro. -If a macro is not callable, then its invocation after the initial line -macro is interpreted as opaque text, such that +column indicates that the macro may also be called by passing its name +as an argument to another macro. +If a macro is not callable but its name appears as an argument +to another macro, it is interpreted as opaque text. +For example, .Sq \&.Fl \&Sh produces .Sq Fl \&Sh . .Pp The .Em Parsed -column indicates whether the macro may be followed by further -(ostensibly callable) macros. -If a macro is not parsed, subsequent macro invocations on the line -will be interpreted as opaque text. +column indicates whether the macro may call other macros by receiving +their names as arguments. +If a macro is not parsed but the name of another macro appears +as an argument, it is interpreted as opaque text. .Pp The .Em Scope @@ -2658,9 +2659,16 @@ 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 beyond the end of the input line. +This macro originally existed to work around the 9-argument limit of troff; +since this limit has been lifted, it is now possible to use +line continuation with a backslash at the end of the line instead. +This macro can also be used to extend the scope of a partial-implicit +block macro beyond the end of its line, but it is almost always +preferable to use the corresponding partial-explicit block macro +instead. .Ss \&Xr Link to another manual .Pq Qq cross-reference . @@ -2714,10 +2722,10 @@ .Pq Qq groff . The term .Qq historic groff -refers to groff versions before the +refers to groff versions before 1.17, +which featured a significant update of the .Pa doc.tmac -file re-write -.Pq somewhere between 1.15 and 1.19 . +file. .Pp Heirloom troff, the other significant troff implementation accepting \-mdoc, is similar to historic groff. @@ -2807,6 +2815,11 @@ .It .Sx \&%C is not implemented. +.It +Historic groff only allows up to eight or nine arguments per macro input +line, depending on the exact situation. +Providing more arguments causes garbled output. +The number of arguments one on input line is not limited with mandoc. .It Historic groff has many un-callable macros. Most of these (excluding some block-level macros) are callable -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv