Re: doc source format -- rationale
On Wed, Dec 13, 2006 at 09:50:42PM +0000, W. Borgert wrote:
> On Wed, Dec 13, 2006 at 02:20:28PM -0500, John Gabriele wrote:
> > The policy draft mentions Texinfo (among some other formats) :
> > http://www.us.debian.org/doc/manuals/ddp-policy/ch-manuals.en.html#s3.1
> > and notes DebianDoc's shortcomings which include not being able to
> > include images or tables. Since Texinfo can do these things, and since
> > it's been the GNU standard doc format for some time now, I'm just
> > curious to hear what the rationale was for going with DebianDoc.
>
> I'm not sure about the history, as this was before my time as a
> DD. Maybe LinuxDoc was taken, but changed for the purposes of
> Debian. Most projects I'm aware of (e.g. Fedora, FreeBSD, GNOME,
> KDE, Linux, PostgreSQL, SVN, S.u.S.E.) switched to DocBook XML
> meanwhile and we should do the same. Not only is it the de-facto
> standard, there are a lot of tools dealing with XML and creating
> HTML, PDF, text, info, nroff, JavaHelp, MS-Help etc. from
> DocBook. There are even "WYSIWYG" style editors (e.g. XXE,
> unfortunately non-free), if someone prefers that. Images and
> tables are supported, UTF-8 and multilanguage text are no
> problem in the source, but are not understood by all backends.
> I already transferred the devref to DocBook, but aba did not yet
> switch to my version. There are rumours, that he has some other
> small task to do :-)
Yes. XML is the way to go for the future.
I have been lazy updating Debian Reference (SGML).
I agree XML gives nice and simple source format for document which will
be converted to several formats.
But at the same time, wiki is nice tool to write such documents.
I am using wiki now but once I finish it someday, I will convert them in
XML form for package. wiki.debian.org is slow so I use local site as
editor and mirror results there.
http://wiki.debian.org/DebianReference
Cheers,
Osamu
Reply to: