From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id ba5a9a38 for ; Thu, 13 Feb 2020 12:57:40 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1j2Ik5-0004kI-Sm; Thu, 13 Feb 2020 18:57:39 +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 1j2Ik3-0005sF-Uh; Thu, 13 Feb 2020 18:57:35 +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 1j2Ik3-0001VO-Ok; Thu, 13 Feb 2020 18:57:35 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 71529035; Thu, 13 Feb 2020 18:57:35 +0100 (CET) Date: Thu, 13 Feb 2020 18:57:35 +0100 From: Ingo Schwarze To: Stephen Gregoratto Cc: discuss@mandoc.bsd.lv, Jason@zx2c4.com Subject: Re: [PATCH] Fix formatting in wg-quick(8) Message-ID: <20200213175735.GE75465@athene.usta.de> References: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> <20200213044921.8115-1-dev@sgregoratto.me> 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: <20200213044921.8115-1-dev@sgregoratto.me> User-Agent: Mutt/1.12.2 (2019-09-21) Hi, Stephen Gregoratto wrote on Thu, Feb 13, 2020 at 03:49:21PM +1100: > I also took the time to "enhance" the rest of the manual by looking > at the output of mandoc's mdoc -> man conversion and adjusting > accordingly. That's a bad idea. Automatically generating high-quality man(7) code is hard, and "mandoc -T man" does not attempt that. All it does is generating code that is portable, but not necessarily good style. > - Wrap all text at 80 chars. > - Put all config examples/code in their blocks Yes. > and eliminate the use of explicit breaks (.br). Using .br is sometimes OK in man(7) code, but abused here. > - Replace all empty lines with explicit paragraph breaks. Yes. > - Simplify synopsis formatting. Command modifiers are now emboldened, > based on output from mandoc's mdoc -> man conversion. > --- > src/man/wg-quick.8 | 394 +++++++++++++++++++++------------------------ > 1 file changed, 186 insertions(+), 208 deletions(-) > > diff --git a/src/man/wg-quick.8 b/src/man/wg-quick.8 > index c38c7d9..215e789 100644 > --- a/src/man/wg-quick.8 > +++ b/src/man/wg-quick.8 > @@ -1,46 +1,35 @@ > -.TH WG-QUICK 8 "2016 January 1" ZX2C4 "WireGuard" > - > +.TH WG-QUICK 8 "2019-02-13" ZX2C4 "WireGuard" Raf already mentioned s/2019/2020/. > .SH NAME > -wg-quick - set up a WireGuard interface simply > - > +\fBwg-quick\fR No, don't do this. If you want it bold, use .B wg-quick > +\- set up a WireGuard interface simply > .SH SYNOPSIS > -.B wg-quick > -[ > -.I up > -| > -.I down > -| > -.I save > -| > -.I strip > -] [ > -.I CONFIG_FILE > -| > -.I INTERFACE > -] > - > +\fBwg-quick\fR > +[\fBup\fR\ |\ \fBdown\fR\ |\ \fBsave\fR\ |\ \fBstrip\fR] > +[\fICONFIG-FILE\fR] > +[\fIINTERFACE\fR] Absolutely not. Make this .B wg-quick .RB [ up | .B down | .B save | .BR strip ] .RI [ config_name | .IR interface ] There should not be whitespace inside brackets. To join words using different fonts, use the font alternating macros. As you said, words that have to be typed verbatim are bold. Argument placeholders are italic, but not all caps. Avoid misleading placeholders like config_file, the argument is merely a name, and you only get the file when appending ".conf". > .SH DESCRIPTION > - Yes. > This is an extremely simple script for easily bringing up a WireGuard interface, > suitable for a few common use cases. > - > -Use \fIup\fP to add and set up an interface, and use \fIdown\fP to tear down and remove > -an interface. Running \fIup\fP adds a WireGuard interface, brings up the interface with the > -supplied IP addresses, sets up mtu and routes, and optionally runs pre/post up scripts. Running \fIdown\fP > -optionally saves the current configuration, removes the WireGuard interface, and optionally > -runs pre/post down scripts. Running \fIsave\fP saves the configuration of an existing > -interface without bringing the interface down. Use \fIstrip\fP to output a configuration file > -with all > -.BR wg-quick (8)-specific > +.PP > +Use \fBup\fP to add and set up an interface, and use \fBdown\fP to tear down and Make this Use .B up to add and set up an interface, and use .B down to tear down and > +remove an interface. Running \fBup\fP adds a WireGuard interface, brings up the New sentence, new line: remove an interface. Running .B up adds a WireGuard interface, brings up the > +interface with the supplied IP addresses, sets up mtu and routes, and optionally > +runs pre/post up scripts. Running \fBdown\fP optionally saves the current I'm not mentioning repeated issues every time. > +configuration, removes the WireGuard interface, and optionally runs pre/post > +down scripts. Running \fBsave\fP saves the configuration of an existing > +interface without bringing the interface down. Use \fBstrip\fP to output a > +configuration file with all > +.BR wg-quick \-specific No, this is a hyphen, not a minus: .BR wg-quick -specific > options removed, suitable for use with > .BR wg (8). > - > +.PP > \fICONFIG_FILE\fP is a configuration file, whose filename is the interface name .I config_name is the name of a configuration. Appending ".conf" yields the name of the configuration file. "Whose" sounds strange to me in this context: a file is not a person. [...] > +.PP > +The following might be used for connecting as a client to a VPN gateway for > +tunneling all traffic: > +.nf > +.sp > +.RS 6n > +[Interface] > +\fBAddress = 10.200.100.8/24\fP Better use .B. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv