Re: DOCBOOK-APPS: Docbook Structuring Problems

[John Storrs <lme@storrs.demon.co.uk>]

I guess I wasn't clear enough so I'll try again. I want to make distributed
declarations of the source files for a Docbook Set containing many Books. The
standard method which Juan describes - entity declarations in the top level
'internal subset' - isn't distributed. It requires all source files in the Set
to be identified in the top level file. In the applications I'm thinking of
this could be 1000s of files. In a large software project, composition would be
defined using nested #includes, distributed makefiles and the like. It would
be unmanageable if all the source files which make up, say, the Linux kernel,
had to be explicitly listed in a top level file. If I have a Set of 100 Books,
I would want the definitions of each Book, or even lower level elements, to be
self-sufficient and complete. Then I could process individual Books, or
different groupings of them, without having to prepare different sets of file
declarations each time. Another problem is content re-use, where different
Books in a Set share some source files. Because IDs have to be unique within a
document, and because sgml doesn't provide variables at document level which
might be used to modify IDs of shared files, sharing doesn't work at all well.
These two issues seem to me to point to the need for something like the C
preprocessor, with #includes, #defines, conditionals etc. But perhaps there is
a solution inside the sgml system. Any guidance? 

John

On Sun, 14 May 2000, I wrote:
> I'm experimenting with Docbook, currently using jade and Norm's stylesheets. My
> interest is enterprise documentation systems, with html and print generation
> from sgml/xml sources. 
> 
> In the sort of application I'm considering source trees may be deep, with
> hundreds or thousands of files. The source subtree for a typical higher level
> component (Book, Article, Chapter etc)  will be some way down the main tree, and
> the right place for a list defining its components will be at the head of this
> subtree. In general there will be multiple uses of some source subtrees in a
> single document, and multiple documents using some subtrees.  Html chunk output
> should be tree structured, with meaningful and stable file names related to
> content.
> 
> I can't currently see how to manage this inside the sgml system:
> As I understand it from 'The Definitive Guide', external general entities
> may be defined only in the DTD or in the single document type declaration. How
> can distributed entity definitions be realised? Perhaps only with a script?
> Can html tree output be achieved with the tools I'm using or other open source
> tools? Norm uses the ID attribute to provide a string for a user-defined html
> filename, but as neither '/' nor / are permitted in IDs this only generates
> a flat file space. Also, defining an ID results in an error if source files are
> re-used.  Can anyone advise?

--
John Storrs, Laboratory for Micro Enterprise
125 Culham 1 Site, Culham, Abingdon OX14 3DA, UK
tel/fax 01865 407085  email lme@storrs.demon.co.uk
www http://www.i-way.co.uk/~storrs