On Tue, 12 May 2020 17:36:15 +0200 Ingo Schwarze <schwa...@usta.de> wrote:
> Hi Matt, > > thanks for doing all this work. Note that i cannot provide feedback > on the code or concepts, and also note that when the code is ready, > a developer can commit it even if there are still issues to sort out > with the documentation. We do value good documentation, but the exact > point in time when it is polished matters little. Thanks for the feedback, I certainly appreciate it. > All the same, i looked through the wg(4) manual page and improved > a few details. Please apply the following patch to what you sent. > > > In addition to my changes, this line must be fixed before commit: > > .\" Copyright? > > Please just use the normal /usr/share/misc/license.template with > the commenting method adjusted from C to roff(7) comments. If you > wrote all the manual page text from scratch, use your own name and > year(s). If it is a derivative work based on the work of others, > retain the original Copyright and license and add your own name and > date(s) if your changes are significant enough. Yes, all me. Will add. > I feel somewhat concerned that you recommend the openssl(1) command > for production use. As far as i understand, the LibreSSL developers > consider openssl(1) as a low-quality program purely intended for > testing purposes that should not be used for production. But that > does not need to be addressed now, it can be improved later. This is news to me, but what we are using it for very simply is calling arc4random_buf, and then base64 encoding. If this isn't appropriate, then perhaps a dedicated utility, or ifconfig integration could work. wg (from wireguard-tools) also fills this functionality, however getting that vs a simple key generator in base would be more work. I'm open to suggestions here. > When providing exactly one example, it isn't ideal that that example > doesn't actually do anything practically useful. Again, that's not > a critical problem and can be improved later. > > > Theo is right that .Ek and .nr nS are slightly awkward in manual > pages, but they are still somewhat widespread in particular in > driver and kernel manuals, so they wouldn't be a serious problem. > However, the whole section containing them is useless in the first > place, so the issue just vanishes with no additional effort. > > > Rationale for my changes: > > * Add the missing $OpenBSD$ tag. > * New sentence, new line. > * Minor macro improvements. > * At a few places, purge phrases that say nothing. > * A few minor wording improvements. > * Delete the DIRECTIVES section: it contains no new information > and ifconfig(8) was already referenced prominently above. > * Use the standard section name DIAGNOSTICS. Thank you again, they're all reasonable, I'll add them in. Matt
