discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: "Jason A. Donenfeld" <Jason@zx2c4.com>
To: Ingo Schwarze <schwarze@usta.de>
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:55:10 +0100	[thread overview]
Message-ID: <CAHmME9pLMaX=SFJGL9Z+VMmydSKjanGyQyKO+x_1WHa2C0qdxQ@mail.gmail.com> (raw)
In-Reply-To: <20200213193430.GG75465@athene.usta.de>

Hi Ingo,

On Thu, Feb 13, 2020 at 8:34 PM Ingo Schwarze <schwarze@usta.de> wrote:
> 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.

Yea, we're not half-assing this, and we'll reach out to the right
people at the right time and start showing up to conferences and stuff
to suss out the finer points. The Linux module took 4 years to get in.
We've learned some lessons. I think things will go well with OpenBSD.
I'll start sending emails when I have coherent things to say. For now,
though, the stuff in ports works fine.


> 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.

Yes, well aware that development is the focus. No need for lessons
here. We're taking that extremely seriously, have worked hard for the
last 4 years at it, and intend to continue to do so with OpenBSD.

However, I do care about the finer details, and one of these is
documentation. Every time I open up my hand-crafted man page files, I
want to close them, because the markup is such an eyesore. Any help at
cleaning this up would be most welcome.


> 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.

Interesting I hadn't ever considered this because I didn't know about
it. I can open mdoc files with the man utility? Right now I appreciate
that installation of man pages just requires copying a file. I'd like
to retain this quality for as long as possible, but with the caveat
that the actual markup of that file should be nice and maintainable.
For that reason, I really appreciate what Stephen has begun here, and
I hope that miniproject continues through til completion.

Jason
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2020-02-13 19:55 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
2020-02-13 19:55               ` Jason A. Donenfeld [this message]
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='CAHmME9pLMaX=SFJGL9Z+VMmydSKjanGyQyKO+x_1WHa2C0qdxQ@mail.gmail.com' \
    --to=jason@zx2c4.com \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --cc=schwarze@usta.de \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).