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

[Ingo Schwarze]

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  
> 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

Re: [PATCH v2] Rewrite wg-quick.8 in mdoc

[Ingo Schwarze]

Hi,

i think Jason should simply commit Anthony's work because that's
what i verified in detail (given that it arrived a day earlier).
There is no point in attempting to merge large patches out of the
tree: that would be tedious and error-prone.

Just let Jason do the commits to his own repo.  Discussing commit
messages and adding signed-off lines is a waste of time.

Once the conversion is committed, people can submit smaller patches
to improve things further.  Those will be much easier to review.

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