WireGuard Archive on lore.kernel.org
 help / color / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Jason A. Donenfeld" <Jason@zx2c4.com>
Cc: Stephen Gregoratto <dev@sgregoratto.me>,
	WireGuard mailing list <wireguard@lists.zx2c4.com>,
	discuss@mandoc.bsd.lv
Subject: Re: [PATCH] Fix formatting in wg-quick(8)
Date: Thu, 13 Feb 2020 19:34:19 +0100
Message-ID: <20200213183419.GF75465@athene.usta.de> (raw)
In-Reply-To: <CAHmME9r9fF28_J=D73qZtgfcS6wLtbywEVf9eu_TyZff=0LmhQ@mail.gmail.com>

Hi Jason,

Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 05:31:41PM +0100:
> On Thu, Feb 13, 2020 at 5:50 AM Stephen Gregoratto <dev@sgregoratto.me> wrote:

>> +.TH WG-QUICK 8 "2019-02-13" ZX2C4 "WireGuard"

> It's 2020 now, but what would you think of retaining the original
> date? Or do you usually bump it on every change? I'm not sure what the
> convention is.

The .TH macro is supposed to contain the date of the last change.

If you want to explain when something was first implemented,
you can do that below ".SH HISTORY".

>> +.PP
>> +The following might be used for connecting as a client to a VPN gateway for
>> +tunneling all traffic:
>> +.nf
>> +.sp
>> +.RS 6n

> Never seen these three modifiers. They set spacing somehow?

Not sure what you mean by "modifiers".
.nf and .sp are roff(7) requests, .RS is a man(7) macro,
and 6n is a scaling width.

  https://man.openbsd.org/roff.7#nf
  https://man.openbsd.org/roff.7#sp
  https://man.openbsd.org/man.7#RS_2
  https://man.openbsd.org/roff.7#Scaling_Widths

>>  .SH SEE ALSO
>> -.BR wg (8),
>> +.BR pass (1),
>>  .BR ip (8),
>> -.BR ip-link (8),
>>  .BR ip-address (8),
>> +.BR ip-link (8),
>>  .BR ip-route (8),
>>  .BR ip-rule (8),
>> -.BR resolvconf (8).
>> -
>> +.BR iptables (8),
>> +.BR resolvconf (8),
>> +.BR wg (8)
>>  .SH AUTHOR
>>  .B wg-quick

> You've ordered these alphabetically, but the original ordering was
> chosen deliberately.

Sorting first by section, then alphabetically is done by convention.
For example, see this style guide:

  https://mandoc.bsd.lv/mdoc/style/see_also.html

The reason is that the number of references ought to be small,
so deliberate ordering adds little value, and a fixed ordering
results in a more predictable experience for the reader.

Yours,
  Ingo
_______________________________________________
WireGuard mailing list
WireGuard@lists.zx2c4.com
https://lists.zx2c4.com/mailman/listinfo/wireguard

  reply index

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20200213042900.2ed2sbhglg5uzjq5@BlackBox>
     [not found] ` <20200213044921.8115-1-dev@sgregoratto.me>
2020-02-13 16:31   ` Jason A. Donenfeld
2020-02-13 18:34     ` Ingo Schwarze [this message]
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  3:35       ` Stephen Gregoratto
     [not found]       ` <20200216103252.ewt4agdpmvgpndid@BlackBox>
2020-02-16 15:52         ` Ingo Schwarze

Reply instructions:

You may reply publically 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=20200213183419.GF75465@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=Jason@zx2c4.com \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --cc=wireguard@lists.zx2c4.com \
    /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

WireGuard Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/wireguard/0 wireguard/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 wireguard wireguard/ https://lore.kernel.org/wireguard \
		wireguard@lists.zx2c4.com
	public-inbox-index wireguard

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/com.zx2c4.lists.wireguard


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git