DocBook/XML summary

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: pgsql-docs(at)postgresql(dot)org
Subject: DocBook/XML summary
Date: 2006-07-15 23:15:51
Message-ID: 200607160115.51824.peter_e@gmx.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

People keep asking about whether or when we will move to DocBook XML.
So here is my summary on that issue.

First of all, moving to DocBook XML will not do anything in the way of
improving our output processing abilities. Any tool that you can use
on DocBook SGML can also be used on DocBook XML and vice versa. This
capability has been in use by pgAdmin for producing "HTML Help" pages
for a while, and it works. (At least the fact that you can use tools
either way; I don't know how well the output comes out, but again, that
won't be helped by changing the source format.)

Possible advantages of using XML:

- Future DocBook development will be XML-only (or at least XML-mainly),
so in the (very) long run we will have to switch anyway because the
tools aren't there anymore.

- XML editing tools are more widely available. (Totally unconfirmed
assumption; I'm happy with what I have.)

- Translation tools may work better with XML sources. (Totally
unconfirmed; would need to be in actual use by someone.)

- Could use XInclude for something like including contrib documentation.
(Of course one could continue to use system entities like we do now,
but it's fancier with XInclude.)

- Could use MathML, SVG, and other extensions (but I don't think they
actually work yet).

- When XML support is available in PostgreSQL, you can import the
documentation and do wild things. ;-)

Possible disadvantages of using XML:

- Marked sections don't work anymore; would need to use DocBook-specific
profiling mechanism, which isn't all that elegant.

- More typing: Things like <abc>foo</> and other abbreviations won't
work anymore; all attributes would need to be quoted, etc.

- doc/src/sgml/*.sgml will look silly for filenames.

- Someone would need to do the conversion. I understand that the French
translation team might have patches available.

So that is it. In my mind, there is no clear winner, but if someone has
a concrete need for XML, I don't see a problem with it.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Joshua D. Drake 2006-07-15 23:59:14 Re: DocBook/XML summary
Previous Message Robert Treat 2006-07-15 02:26:00 Re: Maintenance and External Projects (try 2)