Re: DOCBOOK-APPS: authoritative source for SGML ISO character entitydefinitions?

[Daniel Veillard <veillard@redhat.com>]

On Wed, Jan 16, 2002 at 09:10:00AM +0000, Matt G. wrote:
> >   Then please don't complain about the complexity of the setup on
> >the application list.
> 
> I didn't.  I have been *responding* to people who were complaining about the 
> complexity of setup.  If I did, then I must be suffering from a short-term 
> memory lapse, so I'd appreciate it if you could direct me to a specific 
> example.

  Oops, apologies. I got confused by the thread, I'm sorry !

> However, now that we're on the subject, I think everyone would agree that 
> DocBook deployment is harder than it needs to be.  Part of the problem is 

  Okay, let's refocuse on this part. We have this very problem at the moment
in the Gnome project. We expect to have all the documentation based on
DocBook XML in the next release. One way to avoid problems is to simply
ship the whole set of DTDs/stylesheets/tools as part of our infrastructure
like KDE does. This leads to serious duplication of resources but simplifies
the setup. The other option is to expect parts to be already in place and
checking for them. And this is tricky, for example we can test the presence
of DTD and catalogs aby asking the catalog tool to resolve the DTD Public
or system ID and check the result and it's availability. But this doesn't
help the setup itself, and it's difficult to do complete tests.

  So even when you have a precise idea of what tool chain you plan to
use it is hard to make sure everything is in place, and if not to ensure
an easy setup guide the user in an Os/Distribution agnostic way.

> things like outdated/incomplete documentation that's included with core 
> tools, like OpenJade.  Packaging can shield most people from this, but it 
> really is only a band-aid solution, rather than solving the problem at its 
> source.

  The problem is that DocBook processing is based on complex sequences.
Each step can have limitations/errors which may not be easilly detected,
and only a broken result is perceptible. Maybe the best the community can
do is to try to gather a list of known good toolchains and their limitations
with a high level descriptions. Even with perfect documentation, assuming
that it's documented that "foo-1.2.4" doesn't handle property "bar" of XSL-FO
this doesn't necessary help the end-user trying to understand why the
resulting layout in the printed documentation is broken, and learn about
ways to avoid the problem in the result. I think that's where this
community have knowledge which is not present elsewhere (at least not
in the tool documentation).
  Compiling a list of known working processing chains, and their associate
limitations in terms of results would be really useful to the actual users
of DocBook. Having listeed to this list for some time now, I think a large
part of the traffic is really about this. I'm not 100% sure that the mailing
list archives are really the best way for people to find the right solution,
especially since tools evolves and solutions from 6 months ago may not be the
right way to do things now. IMHO it would be helpful to people outside this
list, and also reduce some of the traffic. It could also help tools developpers
know what are the current limitations which are really annoying to the
end-users. I don't know what would be the best way to build/maintain such
a list. I just have the feeling that the knowledge is here but not available
in a digested form.
  
Daniel

-- 
Daniel Veillard      | Red Hat Network https://rhn.redhat.com/
veillard@redhat.com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/