From: Ingo Schwarze <schwarze@usta.de>
To: discuss@mandoc.bsd.lv
Cc: Matthew Singletary <matt.singletary@gmail.com>
Subject: Re: Mandoc for oil
Date: Fri, 14 Jun 2019 14:29:41 +0200 [thread overview]
Message-ID: <20190614122941.GB25099@athene.usta.de> (raw)
In-Reply-To: <CAAJ-tZK59KremXXW4=RrqnNJwFRuQSzFzxhO+ruucchvp4CECA@mail.gmail.com>
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
next prev parent reply other threads:[~2019-06-14 12:29 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-06-14 8:16 Matthew Singletary
2019-06-14 8:43 ` Jan Stary
2019-06-14 8:54 ` Jan Stary
2019-06-14 9:24 ` Matthew Singletary
2019-06-14 11:40 ` Jan Stary
2019-06-14 12:29 ` Ingo Schwarze [this message]
2019-06-14 13:08 ` Jan Stary
2019-06-14 14:27 ` Jan Stary
2019-06-14 14:54 ` Ingo Schwarze
2019-06-16 2:39 ` Matthew Singletary
2019-06-16 17:08 ` Ingo Schwarze
2019-06-14 9:54 ` Stephen Gregoratto
2019-06-14 12:03 ` Jan Stary
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=20190614122941.GB25099@athene.usta.de \
--to=schwarze@usta.de \
--cc=discuss@mandoc.bsd.lv \
--cc=matt.singletary@gmail.com \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).