Documentation formats
Increasingly, documentation is in a generic markup format that can be
processed into various output formats either by standard tools or ones
that come with the package.
For example:
* GNU Texinfo can be converted to Info, DVI (and hence rather large
PostScript) and HTML.
* The Linux FAQ comes in plain ASCII, HTML, Info, and PostScript via
Lout.
* The Linux HOWTOs are done in linuxdoc-sgml, which produces ASCII,
HTML, Info and LaTeX (hence DVI and large PostScript).
* My new dpkg manuals will be available in plain ASCII, overstruck
ASCII, HTML and Postscript (via Lout).
* The Perl documentation can be converted to HTML, plain text,
manpage source (hence overstruck text and PostScript) and LaTeX
(hence DVI and large PostScript).
We need to decide which documentation formats we wish to distribute,
and how to manage their display. Obviously we can't distribute all of
the output formats as that will either make packages too large or
produce too many packages.
For some of the formats you can process the data `on the fly' as it is
viewed; for others (at least TeX, Lout and HTML) this is trickier as
the processing or viewing involves dumping the formatted document to a
file, or storing some kind of auxiliary data in files while it's being
processed.
Options for our policy include:
1. Specify one or two particular preferred target formats and
distribute those. Leave the source in the source package. So far
we have done this with documentation in Texinfo - we leave the
.texi files in the source package and distribute only the info
files.
2. Distribute the source only and a converter. This has been done
with manpages, and with the Perl `pod' documentation.
3. Distribute the source and one target format for people who don't
have or want converters.
4. Do something fancy with Lars's documentation viewing stuff. I'm
sure Lars will tell us about this.
My inclination is to go for 4 with 2 or 3, if that makes sense.
Ian.
Reply to: