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 <groff@gnu.org>... ;-) 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 <groff@gnu.org> 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
