Re: Formatting of .Xo and .Xc

[Ingo Schwarze <schwarze@usta.de>]

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