Switching PostgreSQL documentation from SGML to XML

From PostgreSQL wiki

(Difference between revisions)
Jump to: navigation, search
(Created page with "For about the last 10 years, there have been occasional discussions about switching the PostgreSQL documentation from SGML to XML (whatever that might mean). Here are some point…")

Revision as of 18:46, 5 April 2011

For about the last 10 years, there have been occasional discussions about switching the PostgreSQL documentation from SGML to XML (whatever that might mean). Here are some points to consider.

Technical points

There is a distinction between changing the source format from SGML to XML versus switching the tool chain from DSSSL to XSLT. Even though DSSSL is typically associated with SGML and XSLT with XML, in fact all combinations work more or less equally well.

Arguments on SGML vs XML

  • DocBook 5, the next major version, will no longer publish an SGML DTD. But DocBook 5 has been in the works for years and it might be many more years until it is the standard version and all previous versions have disappeared.
  • SGML is easier to edit than XML, because of tag minimization and some other simplifications.
  • SGML supports conditional sections (used to build the INSTALL file, for example). That needs a different solution for XML.
  • There might be more editing tools that support XML, but this needs to be substantiated.
  • Translation teams are using XML.
  • We'd probably want to rename *.sgml -> *.xml. Easier now with Git, but needs some planning.

Arguments on DSSSL vs XSLT

  • The DSSSL tools have been unmaintained for years.
  • Small question marks on FOP (XSLT to PDF tool): Is it maintained, is there a stable version (as opposed to endless development pre-releases), can it run on an entirely free Java installation?
  • The customizations that we have done to the DSSSL stylesheets would have to be ported to XSLT. This work could start already.
  • The XSLT build is currently a lot slower than the DSSSL build.
  • XSLT might offer more flexibility such as partial builds.
  • There are probably more tools that work with XSLT in various ways.
Personal tools