Re: Document Formats


Sandy Harris (sandy@storm.ca)
Wed, 12 Jan 2000 21:14:17 -0500


Guylhem Aznar wrote:

> Once we agree on a documentation format, no doubt we will
> improve/recode the tools.

Methinks it is pointless to attempt to "agree on a documentation
format" if by that you mean an authoring format. Certainly there
is a lot of documentation out there in various formats, and you
can make a case for using several input formats:

man:
The programmers on my project (FreeS/WAN) can write man pages easily,
using tools and templates they are familar with. Those can be delivered
to users on almost any Linux system easily. As the doc person on the
project, I've done scripts to also deliver them in HTML, linked from
my docs, but I wouldn't dream of trying to make the programmers switch
formats or tools.

Texinfo:
Widely used, offers some search features not readily available for
other formats, and also has a contingent of programmers who are
happy with the tools and shouldn't be forced to learn something new.
If I knew more about it, I might see other benefits.

Linuxdoc, Debian, ...:
Usable, simpler than DocBook, familar to some, ...

SGML DocBook:
Widely advocated, the current target for important projects like LDP
and OSWG if I've understood their posts right. Partly developed by
O'Reilly; should suit publisher's needs.

XML DocBook:
Where I think we should aim, perhaps the wave of the future?

So I don't think we should be trying to agree on an input format. If
a consensus arises as tools evolve and experience accumulates, fine.
If particular projects want to limit themselves to a single format --
DocBook for OSWG, Texinfo for GNU, ... -- that's fine too.

In the meanwhile, the interesting question is:

Given all these input formats, how do we deliver documentation in a
single searchable well-indexed output format?



This archive was generated by hypermail 2.0b3 on Wed Jan 12 2000 - 21:14:31 EST