Page MenuHomeFreeBSD

wg.8: Rewrite the manual page
AcceptedPublic

Authored by gbe on Wed, Nov 16, 9:47 AM.

Details

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

Diff Detail

Repository
rG FreeBSD src repository
Lint
No Lint Coverage
Unit
No Test Coverage
Build Status
Buildable 48377
Build 45263: arc lint + arc unit

Event Timeline

gbe requested review of this revision.Wed, Nov 16, 9:47 AM
gbe retitled this revision from wg.8: Rework the manual page to wg.8: Rewrite the manual page.Wed, Nov 16, 9:48 AM

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?

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?

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 marked an inline comment as done.Thu, Nov 17, 12:56 PM

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 marked an inline comment as done.

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.

In D37404#850703, @gbe 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?

This revision is now accepted and ready to land.Thu, Nov 17, 7:09 PM

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?

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?

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)
  1. 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),
  1. 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.

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)
  1. 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),
  1. 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 wireguard@lists.zx2c4.com:

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