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 mandoc.bsd.lv (OpenSMTPD) with ESMTP id 1de529f6 for ; Fri, 14 Feb 2020 10:05:43 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] 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 1j2cX6-0004Fw-6k; Fri, 14 Feb 2020 16:05:42 +0100 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1j2cX3-0005Ki-Nh; Fri, 14 Feb 2020 16:05:29 +0100 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1j2cWt-0006yf-LH; Fri, 14 Feb 2020 16:05:19 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id cbad9a53; Fri, 14 Feb 2020 16:05:13 +0100 (CET) Date: Fri, 14 Feb 2020 16:05:13 +0100 From: Ingo Schwarze To: "Jason A. Donenfeld" Cc: anthony@anjbe.name, discuss@mandoc.bsd.lv Subject: Re: [PATCH] Fix formatting in wg-quick(8) Message-ID: <20200214150513.GB92189@athene.usta.de> References: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> <20200213044921.8115-1-dev@sgregoratto.me> <20200213175735.GE75465@athene.usta.de> <20200213193430.GG75465@athene.usta.de> <20200213222845.GA31578@athene.usta.de> <26710-1581652819.729791@VYCU.Vgnw.Vr5M> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.12.2 (2019-09-21) 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 for sub command arguments. Is that > correct? Yes. > Other commands seem to use the . 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