Re: DOCBOOK-APPS: Docbook Structuring Problems

[Bob Stayton <bobs at sco dot COM>]

> From: "Juan R. Migoya" <jmigoya@ingeteam.es>
> 
> I may be wrong, but for what I've seen you need something more than SGML
> to carry out your task.

I agree.
You will need a processing framework outside of
SGML to handle your needs.  My experience has shown that
SGML and XML are not designed for assembling modular
content files into larger documents, despite the external
parsed entity mechanism.  There was some discussion on the
docbook list in February about this.

For example, when you create a modular file you want to put
a DOCTYPE declaration at the top so you can validate it.
If you now include that modular file as an external parsed
entity in a larger master file that has its own DOCTYPE
declaration at the top, parsers will complain about the
extra DOCTYPE declaration inserted with the modular file.
Since SGML is quite adept at ignoring subsequent
declarations of the same element or parameter entity in the
DTD (a feature that the modular Docbook DTD makes extensive
use of), it wouldn't have been hard for the spec to ignore
subsequent DOCTYPE declarations in the document instance.
But it doesn't.

If you include DOCTYPEs in your modular files, you need
a program to assemble modules and strip them out.
If you leave out the DOCTYPE declarations in your modular
files, you have to temporarily insert it to validate the
module.

I remember hearing about "entity managers" years ago
as the solution to modular content.  There are some commercial
products (I think Arbortext Epic for one) that make this
easier, at a price.  There are even SGML object databases
that will handle fragments and assemble instances
from the database.  

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bobs@sco.com

> From: "Juan R. Migoya" <jmigoya@ingeteam.es>
> 
> I may be wrong, but for what I've seen you need something more than SGML
> to carry out your task.
> The example I sen't in my previous post was created by a Perl program. In
> fact, what I do is to write a text file (something like a catalog) with the
> "parts" (in this case "functions") I want in my final document. Then, the Perl
> program generate that file and I run Jade over it.
> I am in a similar situation than John: There are several people developing software
> and hardware and I must document those developings. I must keep several databases
> in a server to keep track of new H/S products or new releases. I think that I
> can't make it just with SGML, so I use the databases and small Perl programs
> to acomplish those task. To be honest, I'm in the beginning but with good prospects
> (too optimist?).
> If somebody have more experience about this item, I (we) would appreciate any tip.
> 
> Thanks and regards,
> 
> John Storrs wrote:
> > 
> > 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
> 
> -- 
> 
> ************************************************************************
> Juan R. Migoya
> Ingelectric-Team, S.A.
> Area de Aparatos y Equipos
> Tel. 94 403 98 30
> Fax. 94 403 96 80