wg.8: Rewrite the manual page

[gbe]

Summary

Rewrite the manual page for wg(8) and remove
most of the Linuxism's. Since the manual page itself
is based on roff(7) rewrite it with mdoc(7) macros.

This is a direct commit to contrib and was discussed
with kevans@ before. Its planned to upstream this
manual page once it's landed.

Reported by: lwhsu, gbe
MFC after: 1 week

Test Plan

mandoc output review and 'mandoc -Tlint' checks

[pauamma_gundo.com]

contrib/wireguard-tools/man/wg.8

13–19

.Bq may come handy here.

26

Why not ifconfig for IP addresses?

175

Taste, concision

254–257

Maybe .Lk instead?

[kevans]

Frankly, I'm not comfortable with taking -this- much of a diff without looping in upstream in advance -- the SEE ALSO proposal was reasonable, though. Adding Jason in on this.

Since the mdoc(1) style was that horrible, a nearly complete rewrite was necessary.

IMO this verbiage isn't really warranted in a commit message; it's entirely subjective, and the subject wasn't targeting mdoc(1) in the first place.

[gbe]

In D37404#850550, @kevans wrote:

Frankly, I'm not comfortable with taking -this- much of a diff without looping in upstream in advance -- the SEE ALSO proposal was reasonable, though. Adding Jason in on this.

Since the mdoc(1) style was that horrible, a nearly complete rewrite was necessary.

IMO this verbiage isn't really warranted in a commit message; it's entirely subjective, and the subject wasn't targeting mdoc(1) in the first place.

That wouldn't be not part of the commit message off course. My normal work flow is using 'mandoc -Tlint' to check for errors and since the man page itself was more roff(7) based there where many errors where reported by mandoc.

contrib/wireguard-tools/man/wg.8

254–257

.Lk isn't suitable in an .Rs context.

[gbe]

In D37404#850530, @pauamma wrote:

Would replacing the roff(7) typographic markup with mdoc(7) semantic markup (in a future change if not here) be too much for upstream to take?

The plan was to have at first local modifications and later add a wg-freebsd.8 manual page that could be upstreamed and would be installed as wg.8
via a simple rename.

[pauamma_gundo.com]

In D37404#850703, @gbe wrote:

In D37404#850530, @pauamma wrote:

Would replacing the roff(7) typographic markup with mdoc(7) semantic markup (in a future change if not here) be too much for upstream to take?

The plan was to have at first local modifications and later add a wg-freebsd.8 manual page that could be upstreamed and would be installed as wg.8
via a simple rename.

WFM.

contrib/wireguard-tools/man/wg.8

254–257

I meant instead of .Rs. Or is .Rs required here?

[jason_zx2c4.com]

In D37404#850550, @kevans wrote:

Frankly, I'm not comfortable with taking -this- much of a diff without looping in upstream in advance -- the SEE ALSO proposal was reasonable, though. Adding Jason in on this.

Thanks for adding me in here. (In general, upstream or not, just as an interested party, I appreciate being looped into all the wireguard-related changes. It's obviously interesting for me to follow along.)

Since the mdoc(1) style was that horrible, a nearly complete rewrite was necessary.

IMO this verbiage isn't really warranted in a commit message; it's entirely subjective, and the subject wasn't targeting mdoc(1) in the first place.

Indeed I have no idea what I'm doing with groff or mdoc. When I type man wg on my system, though, it displays exactly how I want it to.

So how about this: split this up into three patches:

1. Don't change any content, but fix the formatting directives to be nicer and more correct. (It should still render the same way though, and with the same text.)
2. Adjust any gramatical or phrasing things you feel are required.
3. Change the Linuxisms into FreeBSDisms.

Then, I'll take (1) and (2) upstream, so that everybody benefits, and then Kyle can take (3) as part of a smaller downstream diff.

Watcha think of that?

contrib/wireguard-tools/man/wg.8

3

Still looks like most of the text is mine, right?

[jason_zx2c4.com]

In D37404#850530, @pauamma wrote:

Would replacing the roff(7) typographic markup with mdoc(7) semantic markup (in a future change if not here) be too much for upstream to take?

Per my last message regarding splitting this up into 3 patches, that sounds like an okay thing to me. At least I think so? Are there any downsides you can think of in doing that? It seems to me like people who care about manpages these days use mdoc rather than roff, so that's what we should be doing, right?

[lwhsu]

In D37404#850921, @jason_zx2c4.com wrote:

So how about this: split this up into three patches:

1. Don't change any content, but fix the formatting directives to be nicer and more correct. (It should still render the same way though, and with the same text.)
2. Adjust any gramatical or phrasing things you feel are required.
3. Change the Linuxisms into FreeBSDisms.

Then, I'll take (1) and (2) upstream, so that everybody benefits, and then Kyle can take (3) as part of a smaller downstream diff.

Watcha think of that?

I think this idea is fine, and I would like to upstream things as much as possible, since that currently what in base is mostly the same as upstream.

Is it possible for us to accommodate both Linux and FreeBSD parts in one wg(8) page? Most parts of the wg(8) are still sharable between platforms. I think we have some ways:

1. Mention everything in the manual page, e.g.,

SEE ALSO

On Linux:  wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8).
On FreeBSD: netstat(1), ifconfig(8), route(8)

2. If there are more and more difference, Let's split the manual pages into platform independent and platform dependent parts, i.e.: wg(8), wg-linux(8), wg-freebsd(8),

3. If 2) looks scary or inconvenient to the users (seems so), we can have a simple pre-procressor to process 1) and accept platform as a parameter to generate the final file we want.

I think at this stage, 1) should be sufficient and let's try to avoid going to 2) and 3) in the future.

[jason_zx2c4.com]

In D37404#852492, @lwhsu wrote:

I think this idea is fine, and I would like to upstream things as much as possible, since that currently what in base is mostly the same as upstream.

Is it possible for us to accommodate both Linux and FreeBSD parts in one wg(8) page? Most parts of the wg(8) are still sharable between platforms. I think we have some ways:

1. Mention everything in the manual page, e.g.,

SEE ALSO

On Linux:  wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8).
On FreeBSD: netstat(1), ifconfig(8), route(8)

2. If there are more and more difference, Let's split the manual pages into platform independent and platform dependent parts, i.e.: wg(8), wg-linux(8), wg-freebsd(8),

3. If 2) looks scary or inconvenient to the users (seems so), we can have a simple pre-procressor to process 1) and accept platform as a parameter to generate the final file we want.

I think at this stage, 1) should be sufficient and let's try to avoid going to 2) and 3) in the future.

Yea maybe your (1) will be fine. But let me go back to my original proposal, using the original numbering.

Three separate patches posted in a series to [e-mail]:

1. Don't change any content, but fix the formatting directives to be nicer and more correct. (It should still render the same way though, and with the same text.)
2. Adjust any gramatical or phrasing things you feel are required.
3. Change the Linuxisms into FreeBSDisms.

We can examine each one of these steps separately. So if you do 1 and 2 there in two separate patches, I can look at those and apply them. Next, if you send 3 as a final patch, then maybe it'll be small enough that it's easy to just have both as you suggested.

(By the way, if you embark on my step 1 above, could you also update the wg-quick man page to be mdoc'd?)

[carlavilla]

@gbe do you need some help to move this forward :)?

[gbe]

• Address comments

[gbe]

In D37404#902651, @carlavilla wrote:

@gbe do you need some help to move this forward :)?

Do you know a good mdoc replacement for the roff macros "\fI $String \fP"?

Otherwise I would think, that this differential is in a good shape now and the preferred steps to get this upstreamed should be easy.

The only thing I would like to improve is the SYNOPSIS section. Use proper options and so on.

[des]

In D37404#905422, @gbe wrote:

Do you know a good mdoc replacement for the roff macros "\fI $String \fP"?

I would suggest Cm, Ar, Fa, or Va, depending on the context.

[gbe]

In D37404#910366, @des wrote:

In D37404#905422, @gbe wrote:

Do you know a good mdoc replacement for the roff macros "\fI $String \fP"?

I would suggest Cm, Ar, Fa, or Va, depending on the context.

Thanks for the suggestion, I update the differential in the next couple of days.

[bcr]

@gbe: Did you have time to work on this yet? Let me know if you need some help finishing this.

[gbe]

In D37404#924194, @bcr wrote:

@gbe: Did you have time to work on this yet? Let me know if you need some help finishing this.

If you have some time it would be great if you could finish this up. I am currently haven't that much free time to work on the rewrite.

I would think that most of the work would be replacing \fI and \fP macros with proper mdoc macros.

[gbe]

• Finish conversation to mdoc

[des]

contrib/wireguard-tools/man/wg.8

284

I think it would be more fair to say that it was “written by Jason A. Donenfeld and Gordon Bergling” since most of the text is still Jason's.

[gbe]

• Correct the AUTHORS section

[gbe]

@des I have corrected the AUTHORS section.

[jason_zx2c4.com]

What ever happened to submitting this upstream in parts, as I described above in my first comment?

Three separate patches posted in a series to [e-mail]:

1. Don't change any content, but fix the formatting directives to be nicer and more correct. (It should still render the same way though, and with the same text.)
2. Adjust any gramatical or phrasing things you feel are required.
3. Change the Linuxisms into FreeBSDisms.

[gbe]

In D37404#1006048, @jason_zx2c4.com wrote:

What ever happened to submitting this upstream in parts, as I described above in my first comment?

Three separate patches posted in a series to [e-mail]:

1. Don't change any content, but fix the formatting directives to be nicer and more correct. (It should still render the same way though, and with the same text.)
2. Adjust any gramatical or phrasing things you feel are required.
3. Change the Linuxisms into FreeBSDisms.

These separation will happen when I submit it to the wireguard mailing list. I just didn't want to do this work in Phabricator since this more FreeBSD-specific. For upstreaming the changes I just take a local copy of the wg.8 page and put the Linux commands back in. That are just a few places. And the rest like you descripted. I hope that makes it more clear, why this differential holds the conversation to mode and FreeBSD specific updates.

[des]

contrib/wireguard-tools/man/wg.8

13

15

17

29

32

45

everything until .Brc on a single line, keeping in mind to remove the leading . on macros when they are not at the beginning of the line.

46

Angle brackets are superfluous, .Ar already implies that “interface” is a placeholder for a user-provided value.

47

Use .Ar for an argument name (placeholder for a user-provided value), .Li for a literal like all or interfaces. Or possibly .Dq Li since .Ar and .Li look the same on a terminal.

48

49

50

51

See above re. .Ar vs .Li.

63

79–81

82

86

See above, everything until the actual text begins must be on a single line.

108

161

“INI” is not an argument, so .Ar is improper. I would expand to “the Windows INI file format”.

162

163

“Interface” is not an argument. I'm unsure what would be best here, but perhaps .Li?

171

not an argument

176

PrivateKey is not a command, I believe .Va would be more appropriate here.

178

again, not an argument.

256

[gbe]

• First round addressing comments from @des

[gbe]

First round addressing comments...

[des]

Not seeing much progress here, you fixed a few of the issues I raised but you have to fix the entire page, not just the examples I picked.

contrib/wireguard-tools/man/wg.8

45

Again, everything from .It until .Oc needs to be on a single line. Otherwise mandoc considers everything from .Bro on as part of the first paragraph of the item description instead of part of the item heading. If you don't like long lines you can use \ to break a single logical line into multiple physical ones, just like in a shell script.

66

Please remove _all_ the angle brackets, not just the ones in the heading.

72

83

etc.

86

Not done

87

Not done

259

[gbe]

In D37404#1010767, @des wrote:

Not seeing much progress here, you fixed a few of the issues I raised but you have to fix the entire page, not just the examples I picked.

I am currently working on an update for this differential and provide an updated diff today evening or tomorrow morning. The problem are mostly the nested brackets [], which are hard to read from the source level, so I am forced to compare and diff the output manually.

[gbe]

• Markup enhancements

[gbe]

Markup improvements

[gbe]

@des I am not sure how to handle the angle brackets. To remove them is the easy part, but that would change the output of what is currently upstream.

@jason_zx2c4.com would you be fine with the removal?

[jason_zx2c4.com]

In D37404#1012430, @gbe wrote:

@des I am not sure how to handle the angle brackets. To remove them is the easy part, but that would change the output of what is currently upstream.

@jason_zx2c4.com would you be fine with the removal?

I'm fine adhering to the most conventional and most clear ways of representing the information. If angle brackets are a weird deranged thing I invented and most man pages have a better more widely adopted convention, then the better thing is appealing. (And should be sync'd with the wg-quick man page too.)

However, in reviewing this later on the list, it'd be nice if syntax and contentful changes would be in different patches.

[gbe]

• Remove all angle brackets