Re: Mandoc for oil

[Jan Stary <hans@stare.cz>]

> Jan's reply has all the details you need for the above. But lets suppose
> you wanted to install manpages in the right format.  One solution would
> be to convert the mdoc(7) sources to man(7) - using mandoc -Tman foo.1 -
> when creating a release tarball. Then, in your configure script you can
> check if there is a manpage formatter available that can read mdoc.
> If true, install the mdoc sources, else install the man sources.

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

> This is what openssh-portable does with their manpages in their
> configure script[4] and Makefile[5]. In your case, you would probably
> just check for mandoc "$(command -v mandoc)" or if {g,n}roff -mdoc
> doesn't throw an error.

Looking at that Makefile, it does

	$(AWK) -f $(srcdir)/mdoc2man.awk

i.e. it translates the mdoc(7) page to a man(7) page with an awk script,
not with mandoc(1). Arguably, awk is everywhere while mandoc isn't;
generally, the output of such script is far from good.
(However, looking at it's output on MacOS's ls.1 as an example,
it passes mandoc -Tlint except STYLE).

> Honestly though, mdoc support is pretty widespread. mandoc and groff are
> the two major manpage formatters used in modern systems today, and both
> fully support rendering mdoc documents.  I'm not sure when groff did,
> but I imagine it was at least a decade ago.

HISTORY
	The mdoc language first appeared as a troff macro package in 4.4BSD.
	It was later significantly updated by Werner Lemberg and Ruslan
	Ermilov in groff-1.17.  The standalone implementation that is part
	of the mandoc(1) utility written by Kristaps Dzonsons appeared in
	OpenBSD 4.6.

4.4BSD was released in 1977.

 
	Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv