Thread: 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 <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/
> 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 <abc>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/
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 <abc>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/
Peter Eisentraut a écrit : > 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 > Honestly, I don't need this to translate. I'm perfectly ok with sgml files (even if my source files are XML one). I think it's easier to write XML files. I also thinks it's easier to customize output with XML tools (DSSSL is really hard to understand, xslt is way more simple). But that's only *my* opinion. Regards. -- Guillaume. <!-- http://abs.traduc.org/ http://lfs.traduc.org/ http://traduc.postgresqlfr.org/ -->
Guillaume LELARGE wrote: > I also thinks it's easier to > customize output with XML tools (DSSSL is really hard to understand, > xslt is way more simple). But that's only *my* opinion. You also have not read the second paragraph of my mail. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter, Josh, > > - 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. Like which? I've been completely unable to find any tools more sophisticated than Emacs+SGML that support SGML adequately to work on the PostgreSQL docs, while there are literally dozens of XML editors ... including some GUI editors ... which support DocBook XML. I have yet to see *any* tool for SGML which does more than validate tags. The goal of DocBook XML would be to attract new Doc contributors (like *me*) by allowing them to use tools which to not require them to spend more time tagging their text than writing it. -- Josh Berkus PostgreSQL @ Sun San Francisco
Josh Berkus wrote:
> Peter, Josh,
>
>>> - 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.
>
> Like which? I've been completely unable to find any tools more sophisticated
> than Emacs+SGML that support SGML adequately to work on the PostgreSQL docs,
> while there are literally dozens of XML editors ... including some GUI
> editors ... which support DocBook XML.
Bluefish, Kate, Wordperfect. Wordperfect is likely the best Docbook
editor I have ever seen.
>
> I have yet to see *any* tool for SGML which does more than validate tags. The
> goal of DocBook XML would be to attract new Doc contributors (like *me*) by
> allowing them to use tools which to not require them to spend more time
> tagging their text than writing it.
I admit that I might have a different need then most people, as I am way
more familiar with docbook then I ever cared to be. I can just use Joe ;)
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/
On 15/07/06, Peter Eisentraut <peter_e@gmx.net> wrote: > 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 > That's true. I've been working a bit in "Language translation", with Alvaro's help I'm writing a webapps for translate strings. In others words, to use the POT way in a webapps (l10n.postgresql.cl) And then, build the entire HTML manuals from .po -> DocbookXML -> HTML, I'm working as fast as I can. Sadly I haven't got a Postgres full time work :-) -- http://www.advogato.org/person/mgonzalez/