DocBook/XML summary
Peter Eisentraut
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/
---------------------------(end of broadcast)---------------------------
TIP 4: Have you searched our list archives?
Joshua D. Drake
> 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/
---------------------------(end of broadcast)---------------------------
TIP 3: Have you checked our extensive FAQ?
Peter Eisentraut
> > - 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/
---------------------------(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
Guillaume LELARGE
> 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/ -->
Peter Eisentraut
> 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/
---------------------------(end of broadcast)---------------------------
TIP 1: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majo...@postgresql.org so that your
message can get through to the mailing list cleanly
Josh Berkus
> > - 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
Joshua D. Drake
> 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/
---------------------------(end of broadcast)---------------------------
TIP 6: explain analyze is your friend
Mario Gonzalez
> 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/