Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

Jason A. Donenfeld wrote on Fri, Feb 14, 2020 at 12:08:32PM +0100:

> Thanks for doing this. Looks like a step in the right direction.
> 
> A quick look indicates some weird changes, though:
> - The ... in the command summary

You mean, in the SYNOPSIS?

> is now underlined

Yes, that's the usual convention.  It is a placeholder, so it should
be set with .Ar and consequently in italics.

> and inside the [ ],

Yes, that's the usual convention, and it also makes sense logically.
If you don't provide even a single option, you cannot possibly provide
more than one option.

> which seems different from other man pages on my machine.

It looks like you copied unusual or low-quality examples.

> - You got rid of the specifically bolded lines in some of the wg-quick
> examples. As stated elsewhere in this thread, those are intentional.

Restored.

I don't think bold font is needed in example blocks that would become
bold as a whole: that would look rather heavy, and no distinction
needs to be made there.  Then again, your call.

> - One of the wg-quick examples doesn't have a trailing new line,
> making it look awkward with the next paragraph.

.Pp inserted

> - You now put quotes around referenced commands instead of underlines.
> Is that normal?

You mean, as in this description:

  PrivateKey
    A base64 private key generated by 'wg genkey'.
    Required.

It should probably just be

  A base64 private key generated by
  .Ic genkey .

But i think Anthony did not want to change the wording.  He could have
gone for

  A base64 private key generated by
  .Nm
  .Ic genkey .

which would be most logical, but he chose to treat it as an in-line
example command instead, which is commonly marked up with .Ql.

Using italics here would clearly be wrong.  This is not a placeholder
for something else.

> - IP addresses are now quoted instead of underlined. Is that normal?
> It certainly sticks out less.

I'm not aware of any established convention for IP adresses.  The reason
probably is that specific IP addresses rarely appear in manual
pages.  Usually, manual pages contain placeholders for IP addresses
to be filled in by users.

When it's a fixed string like 0.0.0.0/0 or ::/0, it could be marked
up with .Cm.  Using .Ql as Anthony chose to feels acceptable, too.

You could maybe argue an IP address is a bit like a file and use .Pa,
but it wouldn't be my first choice.  If you want fixed IPs to stick
out, bold would seem more natural than italics, so i'd prefer .Cm
over .Pa.

> - You got rid of the <carrots> for sub command arguments. Is that
> correct?

Yes.

> Other commands seem to use the <carrots>.

It is a bad habit seen in a few manual pages, but not very widespread
and certainly not recommended.

The mdoc(7) manual page specifically advises against it:

  https://man.openbsd.org/mdoc.7#Aq_2

  "Never wrap Ar in Aq."

> - The indented example commands are no longer "blue", which seems odd.

I don't understand what you mean by "blue".

> - While some things are now quoted that were previously underlined,
> other things that were emboldened are now quoted. What's up here?

Standard markup, see mdoc(7):

  Ql line
    In-line literal display.  This can be used for complete command
    invocations and for multi-word code examples when an indented
    display is not desired.

For example, that applies to:

  <(echo PRIVATEKEYSTRING)
  wg genkey
  (hidden)
  resolvconf -a tun.INTERFACE -m 0 -x

For stuff like

  off
  0x
  0.0.0.0/0
  ::/0

i might use .Cm, but that's really a minor detail.

Italics are certainly overused in the manual pages you now have in git.

> Did you change any wording at all?

I don't think Anthony changed any wording, at least i don't see any
wording changes.  He even stuck to the existing punctuation.

> It's quite important to me that the
> actual words don't change at all without an explicit patch for that so
> it can be reviewed. In other words, I don't want wording changes
> sneaking in with the typesetting rewrite.
> 
> Again, thanks a lot for working on this. I really appreciate it.

I suggest that you apply the minor corrections appended below to
what Anthony sent and commit the result.  After that, having the
main conversion out of the way, further refinement can be done with
individual patches.

Yours,
  Ingo


--- wg.bentley.8.orig	Fri Feb 14 14:28:31 2020
+++ wg.bentley.8	Fri Feb 14 14:54:38 2020
@@ -79,7 +79,7 @@
 Sets configuration values for the specified
 .Ar interface .
 Multiple
-Ar peer Ns s
+.Ar peer Ns s
 may be specified, and if the
 .Cm remove
 argument is given for a peer, that peer is removed, not configured.
@@ -202,7 +202,7 @@
 section may be specified.
 .Pp
 The
-.Ar Interface
+.Ic Interface
 section may contain the following fields:
 .Bl -tag -width Ds
 .It Ic PrivateKey
--- wg-quick.bentley.8.orig	Fri Feb 14 14:28:57 2020
+++ wg-quick.bentley.8	Fri Feb 14 15:38:28 2020
@@ -161,8 +161,10 @@
 for connecting as a client to a VPN gateway for tunneling all traffic:
 .Bd -literal -offset Ds
 [Interface]
+.Bf Sy
 Address = 10.200.100.8/24
 DNS = 10.200.100.1
+.Ef
 PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
 
 [Peer]
@@ -226,9 +228,11 @@
 the following is a more complicated example involving multiple peers:
 .Bd -literal -offset Ds
 [Interface]
+.Bf Sy
 Address = 10.192.122.1/24
 Address = 10.10.0.1/16
 SaveConfig = true
+.Ef
 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
 ListenPort = 51820
 
@@ -267,14 +271,17 @@
 Address = 10.192.122.1/24
 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
 ListenPort = 51820
+.Bf Sy
 Table = 1234
 PostUp = ip rule add ipproto tcp dport 22 table 1234
 PreDown = ip rule delete ipproto tcp dport 22 table 1234
+.Ef
 
 [Peer]
 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
 AllowedIPs = 0.0.0.0/0
 .Ed
+.Pp
 These configuration files may be placed in any directory,
 putting the desired interface name in the filename:
 .Pp
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv