discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: discuss@mandoc.bsd.lv, Jason@zx2c4.com
Subject: Re: [PATCH] Fix formatting in wg-quick(8)
Date: Thu, 13 Feb 2020 18:57:35 +0100	[thread overview]
Message-ID: <20200213175735.GE75465@athene.usta.de> (raw)
In-Reply-To: <20200213044921.8115-1-dev@sgregoratto.me>

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

  parent reply	other threads:[~2020-02-13 17:57 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <CAHmME9rVyL+QUhks0J8xOpykb6V+5wKadgowc8bndP=Shi5gyA@mail.gmail.com>
2020-02-11 22:59 ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld
2020-02-12  7:02   ` Jan Stary
2020-02-12 15:06     ` Ingo Schwarze
2020-02-12 15:14     ` Jan Stary
2020-02-12 15:25       ` Ingo Schwarze
2020-02-12 21:44   ` Ingo Schwarze
2020-02-13  4:29     ` Stephen Gregoratto
2020-02-13  4:49       ` [PATCH] Fix formatting in wg-quick(8) Stephen Gregoratto
2020-02-13  8:57         ` Raf Czlonka
2020-02-13 16:31         ` Jason A. Donenfeld
2020-02-13 18:34           ` Ingo Schwarze
2020-02-13 17:57         ` Ingo Schwarze [this message]
2020-02-13 18:00           ` Jason A. Donenfeld
2020-02-13 19:34             ` Ingo Schwarze
2020-02-13 19:55               ` Jason A. Donenfeld
2020-02-13 22:28                 ` Ingo Schwarze
2020-02-13 22:38                   ` Jason A. Donenfeld
2020-02-13 22:44                   ` Jan Stary
2020-02-13 23:21                     ` Steffen Nurpmeso
2020-02-14  4:00                   ` Anthony J. Bentley
2020-02-14 11:08                     ` Jason A. Donenfeld
2020-02-14 15:05                       ` Ingo Schwarze
2020-02-14 22:36                       ` Anthony J. Bentley
2020-02-14 18:20                     ` Ingo Schwarze
2020-02-15  0:45         ` [PATCH v2] Rewrite wg-quick.8 in mdoc Stephen Gregoratto
2020-02-15 19:53           ` Jason A. Donenfeld
2020-02-16 10:32             ` Stephen Gregoratto
2020-02-16 15:52               ` Ingo Schwarze
2020-02-13 16:34     ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200213175735.GE75465@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=Jason@zx2c4.com \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: [PATCH] Fix formatting in wg-quick(8)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).