Обсуждение: 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