[DOCS] DocBook/XML summary
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 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/ ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] DocBook/XML summary
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. Well sgml tools is probably a long way from dying as you note with (very) ;) - XML editing tools are more widely available. (Totally unconfirmed assumption; I'm happy with what I have.) Most XML tools I have ran into also support SGML. - Translation tools may work better with XML sources. (Totally unconfirmed; would need to be in actual use by someone.) Do you mean language translation or transformation (as in pdf?). - Could use MathML, SVG, and other extensions (but I don't think they actually work yet). SVG is really nice. I don't know much about MathML. - When XML support is available in PostgreSQL, you can import the documentation and do wild things. ;-) Actually that could be fairly interesting from a \h point of view from psql. 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. I don't know what is meant by this. - More typing: Things like foo and other abbreviations won't work anymore; all attributes would need to be quoted, etc. That is true, but we also get better interoperability, like going from xml->doc - doc/src/sgml/*.sgml will look silly for filenames. Well that is an easy fix with a one line shell script and some sed within the docs ;) - Someone would need to do the conversion. I understand that the French translation team might have patches available. This is actually fairly easy to do. We did it with our book in half a day. The postgresql docs are about 2 times the size of our book IIRC. 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. The one thing that I am still unaware of is a good print quality output for Docbook XML. Now to be honest I haven't checked in some time but one of our primary goals *needs* to be to efficiently convert to PDF. Sincerely, Joshua D. Drake -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] DocBook/XML summary
Joshua D. Drake wrote: > > - Translation tools may work better with XML sources. (Totally > > unconfirmed; would need to be in actual use by someone.) > > Do you mean language translation or transformation (as in pdf?). Language translation > > - More typing: Things like foo and other abbreviations > > won't work anymore; all attributes would need to be quoted, etc. > > That is true, but we also get better interoperability, like going > from xml->doc How so? > The one thing that I am still unaware of is a good print quality > output for Docbook XML. Now to be honest I haven't checked in some > time but one of our primary goals *needs* to be to efficiently > convert to PDF. You haven't read the second paragraph of my mail. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
