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 23:28:45 +0100	[thread overview]
Message-ID: <20200213222845.GA31578@athene.usta.de> (raw)
In-Reply-To: <CAHmME9pLMaX=SFJGL9Z+VMmydSKjanGyQyKO+x_1WHa2C0qdxQ@mail.gmail.com>

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

  reply	other threads:[~2020-02-13 22:28 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
2020-02-13 22:28                 ` Ingo Schwarze [this message]
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=20200213222845.GA31578@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).