As those of you following source-changes will have just noticed, I
went ahead and committed the /usr/share/doc reorg without a solution
for the problem of generating PDFs in base. (Instead, as a workaround
it installs .ps.gz.)
The problem with generating PDFs in base is as follows:
- the groff we have has no PDF driver;
- newer groff does have a PDF driver but is gplv3, and worse, the
PDF driver is written in Perl;
- converting .ps output to PDF requires ghostscript;
- using TeX instead is a nonstarter;
- mandoc generates PDF but only handles man pages.
The documents in /usr/share/doc are mostly written with -me or -ms,
which are legacy schemes that don't support semantic markup. I have no
problem with re-setting them one at a time using something more
modern, whatever that is (whether or not it's roff-based), as long as
the end result produces printable output that's reasonably decently
typeset.
For a number of articles the only real incompatibility between them
and -mdoc (which would allow using mandoc) is that -mdoc requires man
page metadata and doesn't support having an author and title. There
are several possible ways to hack around this by hacking mandoc.
However, some of the documents do more elaborate typesetting. So far
it isn't clear what they do, how much of that is really necessary, and
how that intersects with what mandoc can and can't do. (AFAIK we don't
have the really nasty document that only works with ditroff, not even
groff, but even if we did this clearly isn't necessary.)
Teaching mandoc to handle -ms and/or -me is probably a good chunk of
work and not really worthwhile in the long run. Defining an
alternative to -mdoc suitable for articles (that's mostly the same as
-mdoc), teaching mandoc that, and migrating to it is probably a better
course, but still potentially a good chunk of work, and we still might
run into something we can't really handle that way.
Another possibility is to write a PDF driver for the groff we have.
This is still work, but possibly not that much (e.g. maybe one could
rewrite the upstream gplv3 Perl groff driver in Lua...); on the other
hand the artefact it produces is of limited long-term value. And it's
not like groff is doing a super job of typesetting the articles...
and there's long been a desire to kick groff out of base.
The third set of possibilities is to do something completely
different. This is bound to trigger a bikeshed about markup formats,
so it's important to realize that the markup format is not the issue.
Any adequately expressive semantic markup format will serve, and
almost all the possible options are less noxious to edit than legacy
roff. The issue is typesetting; typesetting is hard, and the more
general the typesetting the harder it is. In order to do something
completely different the first question that has to be answered is:
what typesetting engine are we going to use, and can we import it into
base without going crazy?
Another option is to give up on typeset documentation, but I think
that would be a mistake.
--
David A. Holland
dholl...@netbsd.org
