From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id e3066f31 for ; Fri, 3 Mar 2017 18:19:04 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1cjwTV-0002rj-OL; Sat, 04 Mar 2017 00:19:03 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1cjwTT-00063B-Ew; Sat, 04 Mar 2017 00:18:59 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1cjwTT-0008BU-AU; Sat, 04 Mar 2017 00:18:59 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id c0a9d1ed; Sat, 4 Mar 2017 00:18:59 +0100 (CET) Date: Sat, 4 Mar 2017 00:18:59 +0100 From: Ingo Schwarze To: Warren Block Cc: discuss@mdocml.bsd.lv Subject: Re: Formatting of .Xo and .Xc Message-ID: <20170303231859.GH70091@athene.usta.de> References: X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.6.2 (2016-07-01) Hi Warren, Warren Block wrote on Fri, Mar 03, 2017 at 11:23:22AM -0700: > FreeBSD's syslogd.8 man page was recently edited. One rendered portion > looks like this: > > The allowed_peer option may be any of the following: > > ipaddr[/masklen][:service] > ipaddr[/prefixlen][:service] Accept datagrams from ipaddr, > ipaddr can be specified as an > IPv4 address or as an IPv6 > address enclosed with ![" and > > > Ideally, the two options for IP address would render vertically aligned with > the description, like this: > > ipaddr[/masklen][:service] Accept datagrams from ipaddr, > ipaddr[/prefixlen][:service] ipaddr can be specified as an > > Is that even possible? Strictly speaking, the mdoc(7) syntax for tagged lists allows exactly one head and exactly one body per list item. Here, you have two heads for one body. It has become conventional though to simulate logical list items with more than one head by using one physical item per head and leaving all the physical bodies empty except the last one, as follows: preceding text .Pp .Bl -tag -width Ds -compact .It first head .It second head body .Pp .It third head another body .El .Pp following text Nothing is wrong with the above. It is reasonably portable and works well enough with all output modes, and there isn't any better way to get something similar. > The source for that section: > > The > .Ar allowed_peer > option may be any of the following: > .Bl -tag -width "ipaddr[/prefixlen][:service]XX" > .It Xo > .Sm off > .Ar ipaddr > .Op / Ar masklen > .Op \&: Ar service > .Pp That is a terrible idea. Using .Pp inside an .It head is highly non-portable. By chance, it happens to work as you want with mandoc, but that surprises me, and future work could easily break it. Groff renders utter garbage: ipaddr[/masklen][:service] Accept[datagramsn][:service] > .Ar ipaddr > .Op / Ar prefixlen > .Op \&: Ar service > .Sm on > .Xc > Accept datagrams from > .Ar ipaddr , > .Ar ipaddr > can be specified as an IPv4 address or as an IPv6 > > Full source at > https://svnweb.freebsd.org/base/head/usr.sbin/syslogd/syslogd.8?view=co There is no support for having multiple heads for one body and vertically aligning the body with the first head. Of course, you can force it as follows: .Bl -tag -width "ipaddr[/prefixlen][:service]XX" -compact .It Ar ipaddr Ns Oo Pf / Ar masklen Oc Ns Op Pf : Ar service Accept datagrams from .Ar ipaddr , .It Ar ipaddr Ns Oo Pf / Ar prefixlen Oc Ns Op Pf : Ar service .Ar ipaddr can be specified as an IPv4 address or as an IPv6 address... .El While that works for -Tascii and -Tutf8 output, i recommend against it because it may look wrong in other output modes - after all, the markup does not represent the logical structure. Arguably, having the body align with the last line (as it happens with the conventional method shown at the top) is even better than what you ask for. Aligning the body with the first head may result in ambiguity if the first line of the body happens to be a complete sentence; then people may think that the first head belongs to that sentence and that the second head belongs to the rest of the body. That ambiguity cannot occur if the body aligns with the last head, because it is clear that the description of none of the heads can be empty. Besides, i would say that the -width value is excessive in the code extract from syslogd(8). Having the text in a narrow column at the extreme right looks ugly and makes it hard to read. If heads are very wide, it is usually nicer and more readable to simply use -width Ds . Finally, .Xo has nothing to do with it. The .Xo enclosure is merely one way to provide long .It head content; there are other ways for doing that. What matters here is the .It, not the .Xo. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv