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 oAS0MmIv023505 for ; Sat, 27 Nov 2010 19:22:49 -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 1PMV2U-0008JO-OY; Sun, 28 Nov 2010 01:22:46 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1PMV2U-0007DV-NR; Sun, 28 Nov 2010 01:22:46 +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 1PMV2U-0006kn-Mg; Sun, 28 Nov 2010 01:22:46 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1PMV2U-0002xk-Lf; Sun, 28 Nov 2010 01:22:46 +0100 Date: Sun, 28 Nov 2010 01:22:46 +0100 From: Ingo Schwarze To: Jason McIntyre Cc: tech@mdocml.bsd.lv Subject: Re: minor mdoc.7 improvements Message-ID: <20101128002246.GF27534@iris.usta.de> References: <20101127222709.GE27534@iris.usta.de> <20101127224144.GB27550@kerhand.co.uk> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20101127224144.GB27550@kerhand.co.uk> User-Agent: Mutt/1.5.21 (2010-09-15) Hi Jason, Jason McIntyre wrote on Sat, Nov 27, 2010 at 10:41:20PM +0000: > On Sat, Nov 27, 2010 at 11:27:09PM +0100, Ingo Schwarze wrote: [...] >> @@ -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. > i'm not sure that this always concerned the It macro. i know there's a > fair bit of abuse of Xo/Xc, but i think there were examples where it was > used outside It correctly. Yes, there are examples where it can be used correctly outside It: Specifically, to extend partial-explicit block macros. I *did* check which kinds of macros can be extended by Xo. Here is the complete list of all mdoc macro classes: 1. full-explicit block macros (Bd, Bf, Bk, Bl) None of these is parsed, so It cannot be used. 2. full-implicit block macros Nd, Sh and Ss are not parsed. Abusing Xo to extend SYNOPSIS Nm would be completely insane. So It is the only relevant one in this class, and if Xo extends It, it extends the It header. 3. partial-explicit block macros (like Ac, Bc, ...) These can't be extended, they are already multi-line capable all by themselves. Actually, Xo itself belongs to this class, and that's exactly why it can extend other macros. 4. partial-implicit block macros (like Aq, Bq, ...) These can correctly be extended, as i say in the proposed text. But it makes very little sense because these replacements are always better: Aq -> Ao Bq -> Bo Brq -> Bro Dq -> Do Op -> Oo Pq -> Po Qq -> Qo Sq -> So Only the following remain: - D1, Dl and Vt Extending these with Xo would be insane (not sure whether it even works). - Ql That's probably the only one where there is no alternative to using Xo to extend it. But Ql is so obscure in the first place that discussing it explicitly is hardly warranted. 5. in-line macros (like Ar, Em, Fl, ...) These don't form blocks at all, hence can't be extended with Xo. And that's it. So i really think the proposed wording is exact. > anyway, since it can be used with other > macros, maybe just clearer to say "extend the header of a macro". No, that's wrong. With Aq, Bq, Brq, Dq, Op, Pq, Ql, Qq and Sq, Xo extends the body of the macro, not the header. These macros don't even have headers, hence Kristaps calls them "partial". It is the only macro where the header can be extended. >> +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. > i wonder whether we should prefer this then in situations where it is > easier to read if Xo/Xc is used? like we have lots of examples like: > > .It Xo > .Ar reallylongargumentname1 reallylongargumentname2 > .Ar reallylongargumentname3 > .Xc > > maybe, as we come across them, we should prefer the backslash? .It reallylongargumentname1 reallylongargumentname2 \ reallylongargumentname3 body starts here Does that look better? Maybe it's a matter of taste. There are instances of really ugly Xo, but the .It Xo solution in its standard form as shown above is quite readable. Thus, i tend to continue using it, it is also more portable - though the latter is a weak argument, we prefer readability to portability when it comes to other details, so our manuals aren't completely portable to ancient troff, anyway. Still, why reduce portability where it provides little to no gain in readability? That's why i only said "possible ... to use instead". I certainly won't blame anybody writing readable code involving backslashes to extend lines, but i don't dislike clean use of It Xo either. Should we express a clear preference? [...] >> @@ -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. > i think "one on" -> "on one". Thanks, i fixed that in my tree. Yours, Ingo -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv