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

[Ingo Schwarze <schwarze@usta.de>]

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