Thread: DocBook upgrade
Briefly after we open the floodgates for 7.2+1 I would like to upgrade our documentation sources to use DocBook 4.1. There are three reasons for it: - Some better markup for cases that currently look really ugly. - The available stylesheets tend to not handle 3.1 correctly in some cases. - We can start exploring XML/XSL-based toolchains. DocBook XML doesn't exist for versions prior to 4.0. The change will effectively amount to changing the version number at the very top of the top-level files (book-decl.sgml and postgres.sgml), and possibly fixing some markup that has been deprecated. At that time, your processing tools will start complaining that they can't resolve the public identifier for "-//OASIS//DTD DocBook V4.1//EN" or some such. Basically, what you need to do is install the V4.1 DTD in the same way that 3.1 was installed. Instructions for this are contained in our documentation. I'll be happy to assist if you can't get it to work. -- Peter Eisentraut peter_e@gmx.net
> Briefly after we open the floodgates for 7.2+1 I would like to upgrade our
> documentation sources to use DocBook 4.1. There are three reasons for it:
Great! Do you have an opinion on the rest of the toolchain and
possibilities for XML? afaict SGML/DSSSL is still smoother than XML (and
quite possibly more capable), but I haven't tried the XML tools yet...
- Thomas
Let me know what you need me to install ... On Fri, 18 Jan 2002, Peter Eisentraut wrote: > Briefly after we open the floodgates for 7.2+1 I would like to upgrade our > documentation sources to use DocBook 4.1. There are three reasons for it: > > - Some better markup for cases that currently look really ugly. > > - The available stylesheets tend to not handle 3.1 correctly in some > cases. > > - We can start exploring XML/XSL-based toolchains. DocBook XML doesn't > exist for versions prior to 4.0. > > The change will effectively amount to changing the version number at the > very top of the top-level files (book-decl.sgml and postgres.sgml), and > possibly fixing some markup that has been deprecated. > > At that time, your processing tools will start complaining that they can't > resolve the public identifier for "-//OASIS//DTD DocBook V4.1//EN" or some > such. Basically, what you need to do is install the V4.1 DTD in the same > way that 3.1 was installed. Instructions for this are contained in our > documentation. I'll be happy to assist if you can't get it to work. > > -- > Peter Eisentraut peter_e@gmx.net > > > ---------------------------(end of broadcast)--------------------------- > TIP 3: if posting/reading through Usenet, please send an appropriate > subscribe-nomail command to majordomo@postgresql.org so that your > message can get through to the mailing list cleanly >
On Sat, Jan 19, 2002 at 03:51:31AM +0000, Thomas Lockhart wrote: > > Great! Do you have an opinion on the rest of the toolchain and > possibilities for XML? afaict SGML/DSSSL is still smoother than XML (and > quite possibly more capable), but I haven't tried the XML tools yet... I'd be interested in hearing your experiences with XML. So far I've only had trouble working with Docbook XML. -Roberto -- +----| http://fslc.usu.edu/ USU Free Software & GNU/Linux Club |------+ Roberto Mello - Computer Science, USU - http://www.brasileiro.net/ http://www.sdl.usu.edu/ - Space Dynamics Lab, Developer Bill Gates made $6.3 Billion selling us MS-DOS?
Thomas Lockhart writes: > Great! Do you have an opinion on the rest of the toolchain and > possibilities for XML? afaict SGML/DSSSL is still smoother than XML (and > quite possibly more capable), but I haven't tried the XML tools yet... The XSL toolchains aren't really any good yet, to be blunt, but as long as they're still under development we can have a say and part in where the development goes, but the only way to do that is actually using them. -- Peter Eisentraut peter_e@gmx.net
I once wrote: > Briefly after we open the floodgates for 7.2+1 I would like to upgrade our > documentation sources to use DocBook 4.1. Just so you know what the status on this is: As it turns out, DocBook 4.1 (and 4.0) has some overly restrictive changes to the content model of some elements (read: "what tags can I put in what other tags"), and the PostgreSQL documentation is affected by some of these cases. Part of these changes will be reverted in the DocBook 4.2 release, which went beta the other day and will be released in a month. Add to that some time to wait for packages to appear and some general gratuitous hestitation, we might be at least 6 to 8 weeks away from this move; maybe it won't even be in this cycle. -- Peter Eisentraut peter_e@gmx.net
Peter Eisentraut wrote: > I once wrote: > > > Briefly after we open the floodgates for 7.2+1 I would like to upgrade our > > documentation sources to use DocBook 4.1. > > Just so you know what the status on this is: > > As it turns out, DocBook 4.1 (and 4.0) has some overly restrictive > changes to the content model of some elements (read: "what tags can I put > in what other tags"), and the PostgreSQL documentation is affected by some > of these cases. Part of these changes will be reverted in the DocBook 4.2 > release, which went beta the other day and will be released in a month. > Add to that some time to wait for packages to appear and some general > gratuitous hestitation, we might be at least 6 to 8 weeks away from this > move; maybe it won't even be in this cycle. From your description, I was thinking 6-8 months. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000 + If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania 19026