From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id c944a2a4 for ; Thu, 13 Feb 2020 17:28:50 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1j2MyV-0000CG-Qu; Thu, 13 Feb 2020 23:28:49 +0100 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1j2MyU-0007um-3b; Thu, 13 Feb 2020 23:28:46 +0100 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1j2MyT-0002P9-Ts; Thu, 13 Feb 2020 23:28:46 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 4db86cd3; Thu, 13 Feb 2020 23:28:45 +0100 (CET) Date: Thu, 13 Feb 2020 23:28:45 +0100 From: Ingo Schwarze To: "Jason A. Donenfeld" Cc: Stephen Gregoratto , discuss@mandoc.bsd.lv Subject: Re: [PATCH] Fix formatting in wg-quick(8) Message-ID: <20200213222845.GA31578@athene.usta.de> References: <20200213042900.2ed2sbhglg5uzjq5@BlackBox> <20200213044921.8115-1-dev@sgregoratto.me> <20200213175735.GE75465@athene.usta.de> <20200213193430.GG75465@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.12.2 (2019-09-21) 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