Note: This email is not immediately relevant to Postgres,
although someday it may be.
On 11/06/2012 11:38:07 AM, Andrew Dunstan wrote:
>
> On 11/06/2012 12:09 PM, Karl O. Pinc wrote:
> >>
> >>> Postgresql uses Docbook 4.2 and openjade/dsssl style sheets.
> I don't recall what the arguments against moving to XML/XSL were
> other
>
> than inertia.
As long as we're on the subject of re-vamping the doc toolchain
I'll note what I can recall of what it takes to migrate from
docbook 4 to docbook 5. For no good reason...
(This has nothing to do with what it would take to go
from SGML to XML, or DSSL to XSL.)
The big deal is the introduction of a docbook namespace.
This means changing all the id attributes to xml:id.
It also means adding namespace (xmlns=) to entity
declarations.
The external link entry also changed, I forget the details
but it's an easy fix.
The part I had trouble with was using the system catalogs.
I finally punted and used a SYSTEM entity instead.
I can't say I know what I'm doing but it may be
that the common OS platforms have not yet fully caught
up with Docbook 5. Or then again maybe I'm just
blaming the system for my mistakes. :)
---
The other thing to think about is whether to use
XPath and xmlinclude or not. It's kind of nice
to avoid having to use olink and build link databases,
but you don't get the benefits of being able to
validate individual files either. All in all,
it seems simpler to avoid XPath. The barrier
to entry involved in frobbing documentation
is much lower if you avoid it because
hyperlinking between files involves a whole
new syntax. (olink instead of xref)
Regards,
Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
FWIW. Attached is my link.emacs file.
Makes the hyperlinking to docbook ids much easier.
Load it with M-x, load-file, then position
point after an xml:id (foo) and M-x, link
produces <xref linkend="foo"/>, and
mark is left before the <.
