Re: [PATCH] Fix formatting in wg-quick(8)

[Ingo Schwarze <schwarze@usta.de>]

Hi Jason,

Jason A. Donenfeld wrote on Thu, Feb 13, 2020 at 08:55:10PM +0100:

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

That sounds great all around.

> However, I do care about the finer details, and one of these is
> documentation.

That's good, too.  OpenBSD cares about detail, and it cares about
documentation.

> Every time I open up my hand-crafted man page files, I
> want to close them, because the markup is such an eyesore.

Yes, man(7) source code tends to not be very pretty even when
well-written.

> Interesting I hadn't ever considered this because I didn't know about
> it. I can open mdoc files with the man utility?

I assume you mean "read" when you say "open"; to open them for
editing, you would instead use any text editor you like, for example
vi(1) or emacs(1).

On any BSD, any Linux, on Illumos, and on commercial Oracle Solaris 11:
yes, any installation of man(1) you might have will display mdoc(7)
just fine.  On most BSDs, man(1) will use mandoc(1) for formatting.
On most Linuxes, man(1) will use groff(1) by default for formatting,
but groff(1) has been supporting mdoc(7) for about three decades
now.

If you use MacOS, it will work, too, but there might be occasional
formatting problems.  In general, code quality in MacOS tends to
limp along behind FreeBSD, often being outdated by roughly a decade
even in the newest MacOS releases.  But you can easily fix that by
installing an up-to-date groff or mandoc.

If you use commercial Oracle Solaris 10 or older, you need to install
a better man(1) or teach it to use groff.  For AIX and HP-UX, i
don't really know, but if there are issues, installing a modern
groff or mandoc will almost certainly cure them, too.

> Right now I appreciate that installation of man pages just requires
> copying a file.

Absolutely.  That's exactly the same with mdoc(7) as with man(7),
except with the system man(1) on systems like Solaris 10 and maybe
AIX and HP-UX.

> I'd like to retain this quality for as long as possible,

Indeed, i see no reason not to.  OpenBSD, FreeBSD, NetBSD, and
Illumos do just that all the time with all their manual pages.

> but with the caveat that the actual markup of that file should be
> nice and maintainable.

I guess mdoc(7) would fit that bill.

You see this in the editor:
  https://cvsweb.bsd.lv/mandoc/mdoc.7?rev=HEAD

And you see this in man(1):
  https://man.openbsd.org/mdoc.7

> For that reason, I really appreciate what Stephen has begun here, and
> I hope that miniproject continues through til completion.

Do you want somebody to have a go at converting your two files
to mdoc(7)?

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv