From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id f99a6262 for ; Thu, 13 Feb 2020 14:34:35 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1j2KFs-0003sL-Vv; Thu, 13 Feb 2020 20:34:34 +0100 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1j2KFr-00002Z-7P; Thu, 13 Feb 2020 20:34:31 +0100 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1j2KFr-0001oZ-04; Thu, 13 Feb 2020 20:34:31 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 643830b4; Thu, 13 Feb 2020 20:34:30 +0100 (CET) Date: Thu, 13 Feb 2020 20:34:30 +0100 From: Ingo Schwarze To: "Jason A. Donenfeld" Cc: Stephen Gregoratto , discuss@mandoc.bsd.lv Subject: Re: [PATCH] Fix formatting in wg-quick(8) Message-ID: <20200213193430.GG75465@athene.usta.de> References: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> <20200213044921.8115-1-dev@sgregoratto.me> <20200213175735.GE75465@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.12.2 (2019-09-21) Hi Jason, Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 07:00:33PM +0100: > One thing I should mention is the work here will lead to BSD > improvements. Both wg.8 and wg-quick.8 are in FreeBSD and OpenBSD > ports trees. We're working on some native kernel stuff for OpenBSD > stuff, so I could imagine at some point in a year from now this making > its way into OpenBSD proper. Oh wow. I wasn't aware of that, but it appears that both Ted Unangst (tedu@) and Jasper Lievisse Adriaanse (jasper@) are interested. And when Tedu says that something is simple, that is high praise. Don't underestimate the difficulty of getting something into the OpenBSD kernel, though. We deleted support for kernel modules many years ago and they won't come back. So, while you might get away with making a kernel module for FreeBSD, for OpenBSD the code quality needs to be sufficient to be included in every kernel for all users, by default. Also, subsystem design and code quality is very strictly audited and enforced in the kernel. So try to coordinate early with kernel developers, to avoid later disappointments and wasted effort by developing in some direction and finding out later that parts of the design require tweaks. Tedu is a good person to ask what to coordinate with whom; if you get people like claudio@ or bluhm@ or dlg@ to help and to review early drafts of code, prospects increase substantially. Neither me nor Jasper work in the kernel. > https://git.zx2c4.com/wireguard-tools/tree/src/man/wg.8 > https://git.zx2c4.com/wireguard-tools/tree/src/man/wg-quick.8 > > At the moment these are our only man pages, but if you guys lay down > some clear consistency with them, I'll ensure that future additions > match your conventions. Don't worry too much about manual pages. While we also require manual pages that are complete, correct, and concise, that will not make your project fail: you will get help with that when needed: ask me when in doubt. It is much harder to get stuff ready for kernel commits than to get the documentation into shape. That said, in OpenBSD, we strongly prefer mdoc(7) manual pages over man(7); though when outside suppliers only provide man(7), that can be imported, too. FreeBSD, NetBSD, DragonFly BSD, and Illumos also prefer mdoc(7) over man(7), though maybe not quite as strongly as OpenBSD. Either way, mdoc(7) is easier to learn and write than man(7), produces output of considerably better quality, and if some of the platforms you want to support require man(7), you can readily generate that from mdoc(7) with mandoc(1). The most prominent platform i'm aware of that doesn't support mdoc(7) is commercial Oracle Solaris; certainly all BSDs, MacOS, and all Linux distros support mdoc(7). I'm not sure about commercial AIX and HP-UX. So you might want to consider maintaining your manual pages in mdoc(7) format right from the start - that's better for all BSDs, no worse for Linux, and you can use automatic conversion for whatever other, more obscure systems you want to support. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv