Re: [groff] mdoc equivalent for man's .TQ?

[Ingo Schwarze]

Hi Guillem,

Guillem Jover wrote on Mon, Jul 15, 2019 at 01:14:37PM +0200:
> On Sat, 2019-07-13 at 23:46:23 +0200, Ingo Schwarze wrote:
>> Guillem Jover wrote on Sat, Jul 13, 2019 at 08:15:18PM +0200:

>>> I've got some man pages using the man package, which I've been
>>> converting to mdoc.

>> I'm curious, which ones?

> The man pages for the Debian GNU inetutils package, as upstream only
> provides texinfo documents, and even switched from the original BSD man
> pages (from where the code originated) to stub and unhelpful man pages
> generated from --help output, a change which I reverted.
> 
> The conversion for the last remaining ones is here:
> 
>   
> <https://git.hadrons.org/cgit/debian/pkgs/inetutils.git/commit/?id=6323b846cfc7b511c9911c4dc21aebb7f86d36f5>

Nice.  The conversions look good as far as they go.  :-)

Of course, these manual pages can still be improved in very large
numbers of respects, but you clearly made quite some progress
already.

See below for a patch to the specific pages you pointed to in the
above commit:

 * Never, ever put any macros inside .Nd;
   that tends to confuse some makewhatis(8)/apropos(1) suites.

 * Never, ever put
     .Op Ar option ...
   into any SYNOPSIS.
   The whole point of the SYNOPSIS is to concisely show a complete
   overview of all the options.  So the above line totally defeats
   the only purpose the SYNOPSIS has.

 * In the SYNOPSIS, first list options taking no arguments,
   then options taking arguments, both alphabetically.
   Do not show aliases in the SYNOPSIS, they are not needed
   for a concise overview, show only the shortest versions.

 * Use names for option arguments that are as expressive as
   possible, while still being short.  That makes the SYNOPSIS
   much more helpful.  Avoid re-using the same argument name
   for multiple options if you can, to help reduce the potential
   for confusion.

 * Never, ever use the non-standard section name
     .Sh OPTIONS
   Listing what some people occasionally put into OPTIONS
   is exactly the main purpose of the DESCRIPTION.
   The standard sentence to introduce the options is:
     The options are as follows:

 * Simply show --ttl and --hoplimit on a single line,
   just like for all the other options that have longer aliases.

 * Drop the obsolete .Tn and .Li macros.

 * Fix the grammar in a few cases, and polish some wordings.

I refrained from processing ifconfig.1 because from the existing
manual page, it is quite unclear to me how the program is supposed
to work, and i didn't want to study the source code right now.

Also, in ping.1, the options in the DESCRIPTION should be ordered
alphabetically by their short versions (cdfilnpqrsTvw).  I didn't
do that in the patch below because it would make the patch unreadable.

> I've considered switching others where I'm upstream, such as dpkg,

Nice.

> although I've found annoyances like this (or dates not being settable
> in ISO 8601 format,

In general, please do use the "Month Day, Year" date format because
that is what is most widely used and most readable.  That said, if
you absolutely want to use a non-standard format in some pages,
we should probably fix the groff_mdoc(7) macros to work with any
date string; in mandoc(1), that already works.

For the time being, you could use this very ugly workarond such
that your custom date not only works with mandoc, but also with
the somewhat weird implementation of .Dd in groff:

  .Dd "" my_custom_date ""

But i only recommend that for a limited time, to ease the transition
if we decide to fix .Dd in groff.

> or po4a giving translators too much confusing markup),

Right, po4a is a problematic tool.
It would probably take some work to fix it.

> that have put me off. (My current thinking has been to switch
> from man to perl POD for those, and even though POD is less semantically
> rich than mdoc, it does not have the above mentioned problems, and
> seems like an incremental "improvement" from man markup.)

Yes, it certainly is.  When you can't use mdoc(7) for some reason,
perlpod(1) is the second best source format i'm aware of because
pod2man(1) output is of acceptable quality and the pod2man(1)
program is very stable and reliable.

>>> But I've been struggling to find an equivalent for the .TQ macro
>>> in mdoc, in the docs (groff and BSDs), and via search engines.
>>> 
>>> Is there anything at all within mdoc which I'm missing? How do BSDs
>>> handle things like:
>>> 
>>>   ,---
>>>   .TP
>>>   .BR \-o ", " \-\-option
>>>   .TQ
>>>   .BR \-a ", " \-\-alias
>>>   Do whatever.

>> \&... this is the end of the preceding text.
>> .Pp
>> .Bl -tag -width Ds -compact
>> .It Fl o , -option
>> .It Fl a , -alias
>> Do whatever.
>> .Pp
>> .It Fl n , -next
>> Next list entry.
>> .El
>> .Pp
>> And here the running text continues ...
>> 
>>   https://man.openbsd.org/mdoc.7#Bl_2   # end of the second paragraph

> Thanks, although I don't think this is entirely equivalent. :) The nice
> thing about .TQ is that it gives you compact for the continued entries,
> but not for the rest, so it's visually clear which ones go together.
> 
> Just listing them w/o -commpat (which is what I went with for now) seems
> ugly/confusing to me,

Yes, that is somewhat ugly and mildly confusing, though not too bad.

> as it's not clear at first sight that these are
> related, and using -compact for the whole list is not visually appealing
> for this specific case

I'm not sure i follow what the problem is.  You can simply insert
the .Pp macros you want and get exactly the vertical spacing you want.

Not saying -compact lets lists insert spacing everywhere, as a
convenient default.  Saying -compact gives you full control to
insert the desired spacing yourself.

> (I've used -compact in other cases where it
> looked appropriate, such as
> <https://cgit.freedesktop.org/libbsd/tree/man/libbsd.7#n93>).

Sure, that is a reasonable use case for -compact, though i think using
  .Bd -unfilled
would be simpler and cleaner for that particular display.

>> Btw., note that .Bl -compact is portable, whereas .TQ is a GNU
>> extension: the -compact flag has been around since the early 1990ies,
>> whereas groff only supports .TQ since 2007.
>> 
>>   https://man.openbsd.org/4.4BSD-Lite2/man7/mdoc.samples.7#tag

> Right, although I'm not too fused about these (it being a GNU
> extension, and it's age) for the cases where I use .TQ.

Admittedly, for software that is mostly intended to be used on Linux
and BSD, using .TQ is maybe acceptable, even though it might cause
issues on more exotic systems (like e.g. HP-UX? - not sure; even
Solaris 11 is likely to work with .TQ nowadays, though Solaris
version before 11 did not, iirc).

> So, I take there's no direct equivalent then? :)

There is, .Bl -compact combined with .Pp as needed.

> I guess I could file a request somewhere,

That would be with me, on <address@hidden>...  ;-)

Then again, i think we need *very* good reasons for introducing
new syntax - making the user interface larger needs justification,
and i don't quite see that yet for this particular request.

> but I'm assuming something like this would need
> to be coordinated among the various implementations?

While the mdoc(7) language is not standardized, the groff and mandoc
implementations are the de-facto standard, and i take great care
to make sure those two stay in sync.  Heirloom usually follows
these two and if i remember correctly, its mdoc implementation
is somewhat historic and may have some problems anyway, even though
Carsten Kunze did fix some issues if i remember correctly.

So in general, when changing the mdoc language, building consensus
on <address@hidden> and changing groff and mandoc is all that is
needed.

Yours,
  Ingo


diff --git a/debian/local/man/dnsdomainname.1 b/debian/local/man/dnsdomainname.1
index 5db6be7..56885ad 100644
--- a/debian/local/man/dnsdomainname.1
+++ b/debian/local/man/dnsdomainname.1
@@ -11,17 +11,19 @@
 .Nd show DNS domain name
 .Sh SYNOPSIS
 .Nm dnsdomainname
-.Op Ar option ...
 .Sh DESCRIPTION
-Show domain part of the system's fully qualified host name.
+Show the domain part of the system's fully qualified host name.
 .Pp
 The tool uses
 .Xr gethostname 2
 to get the host name of the system and
 .Xr getaddrinfo 2
 to resolve it into a canonical name.
-The part after the first period ('.') of the canonical name is shown.
-.Sh OPTIONS
+The part after the first period
+.Pq Sq \&.
+of the canonical name is shown.
+.Pp
+The options are as follows:
 .Bl -tag -width Ds
 .It Fl ? , -help
 Give this help list.
diff --git a/debian/local/man/hostname.1 b/debian/local/man/hostname.1
index 7023609..8be47b4 100644
--- a/debian/local/man/hostname.1
+++ b/debian/local/man/hostname.1
@@ -8,17 +8,21 @@
 .Os "GNU Network Utilities"
 .Sh NAME
 .Nm hostname
-.Nd show or set system host name
+.Nd show or set the system host name
 .Sh SYNOPSIS
 .Nm hostname
-.Op Ar option ...
+.Op Fl adfisy
+.Op Fl F Ar file
 .Op Ar name
 .Sh DESCRIPTION
-Show or set the system's host name.
-.Sh OPTIONS
+Set the system's host name, or show it if
+.Ar name
+is not specified.
+.Pp
+The options are as follows:
 .Bl -tag -width Ds
 .It Fl a , -aliases
-Alias names.
+Also show aliases for the host name.
 .It Fl d , -domain
 DNS domain name.
 .It Fl f , -fqdn , -long
@@ -27,7 +31,7 @@ DNS host name or FQDN.
 Set host name or NIS domain name from
 .Ar file .
 .It Fl i , -ip-addresses
-Addresses for the host name.
+Instead of the host name, show the corresponding IP addresses.
 .It Fl s , -short
 Short host name.
 .It Fl y , -yp , -nis
diff --git a/debian/local/man/ping6.1 b/debian/local/man/ping6.1
index 0c6f359..2bc2a4f 100644
--- a/debian/local/man/ping6.1
+++ b/debian/local/man/ping6.1
@@ -8,58 +8,62 @@
 .Os "GNU Network Utilities"
 .Sh NAME
 .Nm ping6
-.Nd send
-.Tn ICMP6 ECHO_REQUEST
-packets to network hosts
+.Nd send ICMP6 ECHO_REQUEST packets to network hosts
 .Sh SYNOPSIS
 .Nm ping6
-.Op Ar option ...
+.Op Fl dfnqrv
+.Op Fl c Ar total
+.Op Fl i Ar pause
+.Op Fl l Ar initial
+.Op Fl p Ar pattern
+.Op Fl s Ar octets
+.Op Fl T Ar class
+.Op Fl w Ar end
+.Op Fl -ttl Ar limit
 .Ar host ...
 .Sh DESCRIPTION
-Send
-.Tn ICMP6 ECHO_REQUEST
-packets to network hosts.
-.Sh OPTIONS
+Send ICMP6 ECHO_REQUEST packets to network hosts
+and report the replies received.
+.Pp
+The options are as follows:
 .Bl -tag -width Ds
-.It Fl c , -count Ar number
-Stop after sending
-.Ar number
-packets.
-.It Fl i , -interval Ar number
-Wait
-.Ar number
+.It Fl c , -count Ar total
+Stop after sending the
+.Ar total
+number of packets.
+.It Fl i , -interval Ar pause
+Wait for
+.Ar pause
 seconds between sending each packet.
-.It Fl w , -timeout Ar n
+.It Fl w , -timeout Ar end
 Stop after
-.Ar n
+.Ar end
 seconds.
 .It Fl n , -numeric
 Do not resolve host addresses.
-.It Fl -hoplimit Ar n
-.It Fl -ttl Ar n
-Specify
-.Ar n
-as hop-limit.
+.It Fl -ttl , -hoplimit Ar limit
+Set that maximum allowed number of hops to
+.Ar limit .
 .It Fl r , -ignore-routing
 Send directly to a host on an attached network.
-.It Fl T , -tos Ar n
-Set traffic class to
-.Ar n .
+.It Fl T , -tos Ar class
+Set the traffic
+.Ar class .
 .It Fl f , -flood
 Flood ping (root only).
-.It Fl l , -preload Ar number
-Send
-.Ar number
-packets as fast as possible before falling into normal mode
+.It Fl l , -preload Ar initial
+Send an
+.Ar initial
+number of packets as fast as possible before falling into normal mode
 of behavior (root only).
 .It Fl p , -pattern Ar pattern
-Fill ICMP6 packet with the given
+Fill ICMP6 packets with the given
 .Ar pattern
 (hex).
-.It Fl s , -size Ar number
-Send
-.Ar number
-data octets.
+.It Fl s , -size Ar octets
+Send the number of data
+.Ar octets
+in each packet.
 .It Fl v , -verbose
 Verbose output.
 .It Fl q , -quiet
@@ -76,4 +80,4 @@ Give a short usage message.
 Print program version.
 .El
 .Pp
-Options marked with (root only) are available only to superuser.
+Options marked with (root only) are available only to the superuser.
diff --git a/debian/local/man/traceroute.1 b/debian/local/man/traceroute.1
index bb21c8d..46194c3 100644
--- a/debian/local/man/traceroute.1
+++ b/debian/local/man/traceroute.1
@@ -11,47 +11,59 @@
 .Nd trace the route to a host
 .Sh SYNOPSIS
 .Nm traceroute
-.Op Ar option ...
+.Op Fl I
+.Op Fl f Ar start
+.Op Fl g Ar gates
+.Op Fl m Ar end
+.Op Fl M Cm icmp Ns | Ns Cm udp
+.Op Fl p Ar port
+.Op Fl q Ar num
+.Op Fl t Ar class
+.Op Fl w Ar timeout
+.Op Fl -resolve-hostnames
 .Ar host
 .Sh DESCRIPTION
-Print the route packets trace to network
+Print the route packets take to another network
 .Ar host .
-.Sh OPTIONS
+.Pp
+The options are as follows:
 .Bl -tag -width Ds
-.It Fl f , -first-hop Ns = Ns Ar num
-Set initial hop distance, that is the time-to-live.
+.It Fl f , -first-hop Ns = Ns Ar start
+Set the initial hop distance, that is the time-to-live.
 .It Fl g , -gateways Ns = Ns Ar gates
 List of gateways for loose source routing.
 .It Fl I , -icmp
 Use ICMP ECHO as probe.
-.It Fl m , -max-hop Ns = Ns Ar num
-Set maximal hop count (default is
-.Li 64 ) .
+.It Fl m , -max-hop Ns = Ns Ar end
+Set the maximal hop count.
+The default is 64.
+A
 .It Fl M , -type Ns = Ns Ar method
-Use
+Use the
 .Ar method
-(\fBicmp\fP or \fBudp\fP) for traceroute operations,
-defaulting to \fBudp\fP.
+.Cm ( icmp
+or the default
+.Cm udp )
+for traceroute operations.
 .It Fl p , -port Ns = Ns Ar port
-Use destination
-.Ar port
-port (default is
-.Li 33434 ) .
+Use the destination
+.Ar port .
+The default is 33434.
 .It Fl q , -tries Ns = Ns Ar num
 Send
 .Ar num
-probe packets per hop (default is
-.Li 3 ) .
+probe packets per hop.
+The default is 3.
 .It Fl -resolve-hostnames
 Resolve hostnames.
-.It Fl t , -tos Ns = Ns Ar num
-Set type of service (TOS) to
-.Ar num .
-.It Fl w , -wait Ns = Ns Ar num
+.It Fl t , -tos Ns = Ns Ar class
+Set the type of service (TOS) to
+.Ar class .
+.It Fl w , -wait Ns = Ns Ar timeout
 Wait
-.Ar num
-seconds for response (default is
-.Li 3 ) .
+.Ar timeout
+seconds for responses.
+The default is 3.
 .It Fl ? , -help
 Give this help list.
 .It Fl -usage