From: Ingo Schwarze <firstname.lastname@example.org> To: "Jason A. Donenfeld" <Jason@zx2c4.com> Cc: Stephen Gregoratto <email@example.com>, firstname.lastname@example.org 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 email@example.com
next prev parent 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 \ --firstname.lastname@example.org \ --cc=Jason@zx2c4.com \ --email@example.com \ --firstname.lastname@example.org \ --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).