Skip site navigation (1) Skip section navigation (2)

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 (view raw or flat)
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

pgsql-docs by date

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

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group