From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 4b98b871 for ; Fri, 14 Jun 2019 07:29:45 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hblKw-0006jM-Tv; Fri, 14 Jun 2019 14:29:44 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hblKw-00063Y-1A; Fri, 14 Jun 2019 14:29:42 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hblKv-0006DB-Ik; Fri, 14 Jun 2019 14:29:41 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 938044b6; Fri, 14 Jun 2019 14:29:41 +0200 (CEST) Date: Fri, 14 Jun 2019 14:29:41 +0200 From: Ingo Schwarze To: discuss@mandoc.bsd.lv Cc: Matthew Singletary Subject: Re: Mandoc for oil Message-ID: <20190614122941.GB25099@athene.usta.de> References: <20190614084313.GA17405@www.stare.cz> <20190614085423.GC17405@www.stare.cz> 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.8.0 (2017-02-23) Hi Matthew, Matthew Singletary wrote on Fri, Jun 14, 2019 at 05:24:23AM -0400: > I was concerned that if I wrote osh.1 in mdoc(7), I would need to > generate another man(7) page for systems that don't support mdoc(7), ie > most linuxes. This is a misconception. If a system provides either mandoc(1) or groff(1) or both, it consequently supports mdoc(7). This includes at least the following systems: * Because they provide groff: - all distributuons of Linux - all versions of MacOS X - Oracle Solaris 11 - DragonFly BSD - Minix 3 * Because they provide mandoc: - FreeBSD, OpenBSD, NetBSD - Alpine Linuy, Void Linux, Termux - all distributions of illumos (e.g. OpenIndiana, SmartOS, ...) The following may or may not work, not sure though: - SUN Solaris 10 and older - AIX - HP-UX Which system are you targetting, specifically, that doesn't support mdoc(7)? > But isn't the point of mandoc -T man to output man(7) from an > mdoc(7) file? Yes, but that is becoming less important as more and more systems include either groff or mandoc, and some both. > Or asking another way; what's the most reasonable (workflow) way to write > a man page in mdoc(7), but make man pages available on systems that don't > support mdoc(7) (ie most linuxes)? If you are using GNU autohell, look at the the sudo(8) build system: https://www.sudo.ws/ Specifically, look for MANTYPE in https://www.sudo.ws/repos/sudo/file/tip/configure.ac and https://www.sudo.ws/repos/sudo/file/tip/doc/Makefile.in Jan Stary wrote on Fri, 14 Jun 2019 10:43:13 +0200: > mandoc(1) is one of the programs that can read and display that > format; the traditional man(1), usually built on top of groff(1), > is another one. Please be a bit more careful with these explanations and distinguish 1. formatters: - Kernighan's device independent troff(1) - Heirloom troff(1) - Plan 9 troff(1) - groff(1) containing GNU troff(1) - mandoc(1) - awf(1) ... and so on 2. viewers: - BSD man(1) - Eaton man(1) - man-1.6 - man-db - FreeBSD man(1) - the man(1) contained in the mandoc toolkit - ... Most viewers can use any formatter (including mandoc(1)), except that the viewer included in the mandoc toolkit is hard-wired to use mandoc(1) and no other formatter. Yes, i'm guilty of blurring the line with the decision to ship mandoc(1) and man(1) as a single executable file - but i stand by that decision because it makes life simpler for users. Jan Stary wrote on Fri, 14 Jun 2019 14:03:48 +0200: > For completeness, note that you can even output ascii manpages > (losing all of the markup force of course) with > mandoc -Tascii page.1 > (or -Tpdf or -Thtml) for target systems that don't even have > a manpage formatter (every unix does, though). True with one exception: even that does *not* lose bold and underline formatting (which is rendered as backspace encodeing, which for example less(1) understands). The difference between -T ascii and -T utf8 is only the character set; neither eliminates formatting. > 4.4BSD was released in 1977. That is very wrong, you are off by 16 years: (pasting extracts from my releases.txt file) May 1975* Version 6 AT&T UNIX Jul 1, 1977* PWB/UNIX 1.0 (v6) Mar 9, 1978* 1BSD (v6) Jan 1979* Version 7 AT&T UNIX May 10, 1979* 2BSD (v6) May 1979* Version 32v AT&T UNIX (v7) Feb 29, 1980* 3BSD (32v) Jun 1980 System III AT&T UNIX (32v) Nov 16, 1980* 4.0BSD Jul 10, 1981* 4.1BSD [June?] May 24, 1982* 4.1a BSD Dec 1982* 4.1c BSD Jan 1983 System V Release 1 AT&T UNIX (4.1) 1983 SunOS 1.0 (4.1) Sep 1983* 4.2BSD 1984 HP-UX 1.0 (System V) Jun 1984 Ultrix-32 (4.2) Feb 1985 Version 8 AT&T UNIX (4.1c + System V Release 2) May 1985 SunOS 2.0 (4.2) Jun 1986* 4.3BSD Sep 1986 Version 9 AT&T UNIX (4.3) 1986 AIX 1 (System V Release 2 + 4.3) 1987 MINIX 1.0 1988 IRIX 3.0 (System V Release 3 + 4.3) Jun 1988* 4.3BSD-Tahoe Oct 18, 1988 System V Release 4.0 AT&T UNIX (4.3) 1989 Version 10 AT&T UNIX Mar 3, 1989* BSD Net/1 [June] Jun 1990* 4.3BSD-Reno Aug 20, 1991* BSD Net/2 [June] Oct 5, 1991 Linux Jan 1992 DEC OSF/1 V1.0 (4.3-Reno) Mar 1992* 386BSD 0.0 (BSD Net/2) Apr 1992 === USL vs. BSDi lawsuit filed === Jun 1992 Solaris 2.0 (System V Release 4) Jul 14, 1992* 386BSD 0.1 Apr 20, 1993* NetBSD 0.8 (386BSD 0.1) Jun 1993* 4.4BSD Nov 1, 1993 FreeBSD 1.0 (386BSD 0.1) Feb 4, 1994 === USL vs. BSDi lawsuit settlement === Apr 22, 1994* 4.4BSD-Lite1 Oct 26, 1994* NetBSD 1.0 (Lite1) Nov 22, 1994 FreeBSD 2.0 (Lite1) 1994 386BSD 1.0 Jun 23, 1995* 4.4BSD-Lite2 Jul 1996* OpenBSD 1.2 (NetBSD 1.0) Stephen Gregoratto wrote on Fri, 14 Jun 2019 19:54:05 +1000: > There is some prior art in this area that you can draw on, > namely sh(1)[1], ksh(1)[2] and csh(1)[3]. Among these, sh(1) is of the best quality because Jason McIntyre wrote it from scratch a few years ago. ksh(1) is also of decent quality because it is quite actively maintained. csh(1) may be slightly rusty. > This is what openssh-portable does with their manpages in their > configure script[4] and Makefile[5]. Portable OpenSSH is not a good example though in so far as it uses the home-grown mdoc2man.awk script rather than mandoc -T man. That script works for the OpenSSH manuals, but it may fail for other valid mdoc(7) input. > I'm not sure when groff did, but I imagine it was at least > a decade ago. Groff supports modern mdoc(7) at least since version 1.05 (March 1992). Note that groff version control history only starts bewteen groff 1.15 (Dec 1999) and groff 1.16 (July 2000). Oh, and groff 1.02 (June 1991) already contained Cynthia's older "Version 2" mdoc(7) macros, which are all but forgotten today. So in a nutshell, groff(1) and mdoc(7) supported each other forever, or more precisely, almost since both exist: both were first released in 1990. It's puzzling people still think they might not like each other, almost thirty years later now... :-) Actually, some years after Cynthia was done with her initial job on mdoc(7) around 1995, Werner Lemberg took over maintenance of the reference implementation of mdoc(7) - as part of groff, starting with groff 1.17 in March 2001. The groff implementation of mdoc(7) remained the reference implementation for at least the first decade of the century. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv