some more docbook help
Hi Gang
I can sense that I'm _really_ close to getting docbook working, but
not quite there yet. I'm hoping somebody can tell me where I'm
screwing up !
I'm on a Red Hat Linux 7.3 system. Although I do have openjade
installed I was finding it difficult to figure out where to point
stylesheets to postgres, so instead I decided to build openjade (and
so OpenSP) from source and configure it _exactly_ as described in
doc-toolsets.html and doc-build.html in the pgsql-7.3 docs.
Although a motley mix of sgml stuff was initially installed in
/usr/share/sgml, I created a /usr/local/share/sgml directory and
pointed it to openjade while building openjade as follows:
$ ./configure --enable-default-catalog=/usr/local/share/sgml/catalog
Subsequently I followed all instructions in doc-toolsets.html for the
other packages.
I set DOCBOOKSTYLE to /usr/local/share/sgml before running configure
for postgres ..
I saw an old usenet message (exchange with Bruce Momjian) which
suggests that the SGML_CATALOG_FILES env. variable must be set to:
export SGML_CATALOG_FILES=/somewhere/docbook31/docbook.cat
I set DOCBOOKINDEX to be /usr/bin/collateindex.pl
Now finally I go to the doc/src/sgml directory and try:
gmake admin.html > new.out 2> new.err
This however results in a make error.
The output file is:
/usr/bin/perl /usr/bin/collateindex.pl -f -g -t 'Index' -i 'bookindex' -o bookindex.sgml HTML.index
/usr/bin/perl /usr/bin/collateindex.pl -f -g -t 'Index' -i 'setindex' -x -o setindex.sgml HTML.index
openjade -D . -D ./ref -c /usr/local/share/sgml/catalog -d stylesheet.dsl -i output-html -t sgml book-decl.sgml admin.sgml
The error file however starts off with:
Processing HTML.index...
0 entries loaded...
0 entries ignored...
Done.
Processing HTML.index...
0 entries loaded...
0 entries ignored...
Done.
openjade:/usr/local/share/sgml/docbook31/docbook.cat:63:79:E: end of entity in comment
openjade:/usr/local/share/sgml/docbook31/docbook.cat:62:20:E: cannot find "data"; tried "/usr/local/share/sgml/docbook31/data", "./data", "./ref/data"
openjade:/usr/local/share/sgml/docbook31/docbook.cat:63:79:E: end of entity in comment
openjade:/usr/local/share/sgml/docbook31/docbook.cat:62:20:E: cannot find "data"; tried "/usr/local/share/sgml/docbook31/data", "./data", "./ref/data"
openjade:book-decl.sgml:1:55:W: cannot generate system identifier for public text "-//OASIS//DTD DocBook V3.1//EN"
openjade:book-decl.sgml:11:0:E: reference to entity "BOOK" for which no system identifier could be generated
openjade:book-decl.sgml:1:0: entity was defined here
openjade:book-decl.sgml:11:0:E: DTD did not contain element declaration for document type name
openjade:admin.sgml:5:9:E: there is no attribute "ID"
openjade:admin.sgml:5:16:E: element "BOOK" undefined
openjade:admin.sgml:9:7:E: element "TITLE" undefined
....
<snip whole bunch of similar errors>
....
openjade:/usr/local/share/sgml/docbook31/docbook.cat:62:20:E: cannot find "data"; tried "/usr/local/share/sgml/docbook31/data", "./data", "./ref/data"
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON86'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'ROWE87'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON87a'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON87b'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON90a'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON89'
openjade:/usr/local/share/sgml/docbook-dsssl-1.77/html/dblink.dsl:203:1:E: XRef LinkEnd to missing ID 'STON90b'
gmake: *** [admin.html] Error 1
Does anybody have any suggestions ? Am I doing something horribly
wrong ?
Many thanks !
--
Sailesh
http://www.cs.berkeley.edu/~sailesh
Phew .. after some more struggling with docbook I think I finally
managed to get it working. Posting here to help other folks googling
through usenet archives.
My problem was that I had DOCBOOKSTYLE set to /usr/local/share/sgml -
the directory which contained the "catalog" file. However, inspite of
this environment variable, configure insisted on setting DOCBOOKSTYLE
to /usr/local/share/sgml/docbook31
I finally fixed it by creating a file
/usr/local/share/sgml/docbook31/catalog as:
CATALOG "../dsssl/catalog"
CATALOG "docbook.cat"
CATALOG "../docbook-dsssl-1.77/catalog"
This works fine thankfully.
Now I have another question - and this is probably incredibly stupid.
I want to generate the PostgreSQL documentation with some extra
add-ons (DDL and DML we have added for streaming data and continuous
long-running queries). I would like the add-ons to show in some
changed fashion - say perhaps in bright red to show that this is new,
not-yet-very-well-tested (:-) functionality specific to our system
(TelegraphCQ) and not part of the base PostgreSQL features.
How would I go about doing something like this in SGML ?
I understand the whole process of SGML documentation as separating
content from presentation. So I imagine I should surround our new
stuff with some kind of tag, that when used with an HTML (or other)
stylesheet generates appropriately changed documentation.
I hope I am on the right track ! Could somebody help me please ?
Many thanks !
--
Sailesh
http://www.cs.berkeley.edu/~sailesh