discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Jason A. Donenfeld" <Jason@zx2c4.com>
Cc: Stephen Gregoratto <dev@sgregoratto.me>, discuss@mandoc.bsd.lv
Subject: Re: [PATCH] Fix formatting in wg-quick(8)
Date: Thu, 13 Feb 2020 20:34:30 +0100	[thread overview]
Message-ID: <20200213193430.GG75465@athene.usta.de> (raw)
In-Reply-To: <CAHmME9pyOx_Dc1QyKi_Z2ZMN4QMiENLAiuha5V8=SS4SxO0Ajw@mail.gmail.com>

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

  reply	other threads:[~2020-02-13 19:34 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <CAHmME9rVyL+QUhks0J8xOpykb6V+5wKadgowc8bndP=Shi5gyA@mail.gmail.com>
2020-02-11 22:59 ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld
2020-02-12  7:02   ` Jan Stary
2020-02-12 15:06     ` Ingo Schwarze
2020-02-12 15:14     ` Jan Stary
2020-02-12 15:25       ` Ingo Schwarze
2020-02-12 21:44   ` Ingo Schwarze
2020-02-13  4:29     ` Stephen Gregoratto
2020-02-13  4:49       ` [PATCH] Fix formatting in wg-quick(8) Stephen Gregoratto
2020-02-13  8:57         ` Raf Czlonka
2020-02-13 16:31         ` Jason A. Donenfeld
2020-02-13 18:34           ` Ingo Schwarze
2020-02-13 17:57         ` Ingo Schwarze
2020-02-13 18:00           ` Jason A. Donenfeld
2020-02-13 19:34             ` Ingo Schwarze [this message]
2020-02-13 19:55               ` Jason A. Donenfeld
2020-02-13 22:28                 ` Ingo Schwarze
2020-02-13 22:38                   ` Jason A. Donenfeld
2020-02-13 22:44                   ` Jan Stary
2020-02-13 23:21                     ` Steffen Nurpmeso
2020-02-14  4:00                   ` Anthony J. Bentley
2020-02-14 11:08                     ` Jason A. Donenfeld
2020-02-14 15:05                       ` Ingo Schwarze
2020-02-14 22:36                       ` Anthony J. Bentley
2020-02-14 18:20                     ` Ingo Schwarze
2020-02-15  0:45         ` [PATCH v2] Rewrite wg-quick.8 in mdoc Stephen Gregoratto
2020-02-15 19:53           ` Jason A. Donenfeld
2020-02-16 10:32             ` Stephen Gregoratto
2020-02-16 15:52               ` Ingo Schwarze
2020-02-13 16:34     ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200213193430.GG75465@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=Jason@zx2c4.com \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: [PATCH] Fix formatting in wg-quick(8)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).