discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
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

  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).