Re: DOCBOOK: On the size of DocBook...

[ed nixon <ed dot nixon at lynnparkplace dot org>]

Paul Grosso wrote:
> At 15:36 2002 09 05 -0400, ed nixon wrote:
> > Paul Grosso wrote:
> > > <snip/>
> A big problem for me is that I still have not seen a satisfactory
> explanation of the user requirement(s) that is(are) driving this
> discussion.
You are right, of course. I think the people who read this list 
regularly become aculturated to the "atmosphere" of an exchange. For 
example, the implicit, assumed goal that I saw immerging is two-fold:
1. significantly accelerate the learning curve of new and inexperienced 
users of the DocBook schema
2. further reduce the support overhead of this and the APPS list 
significantly for a certain class of question by simplifying and/or 
compartmentalizing. I detected that in the wind over the past months; I 
assume there are others who have developed the same impression. Perhaps not.

> <snip/>
> What user requirements do "bolting or unbolting components
> of a per application basis" address?
Are there significant and identifiable "genres" of DocBook application? 
For example, is there a significant delimitable difference between the 
markup required for software versus hardware documentation? Are there 
other types of publication that lend themselves to a segmentation 
exercise of some sort?

I'm by no means as up on the DTD as I should be so I can empathize with 
the reader who, for example, can't figure out the rationale of the 
modularization stucture of DocBook and, therefore, doesn't really know 
where to begin when it comes to cutting out the chaff or adding some 
special stuff. Is it purely, abstractly structural -- block elements, 
inline elements, etc.? Or is it based on some sort of other semantic 
categorization?

Another aspect: I'm vaguely aware that DocBook will validate at a 
significant number of levels and for a significant number of publication 
components, but how or why this happens is not clear to me. Pulling them 
all together is another question. Would refactoring the modules 
facilitate my understanding? I don't know.

For people up to their arm pits on a daily basis with DocBook these 
musings probably sound ignorant. They are. But those people, I submit, 
are a small minority, certainly a small minority of the potential user 
base. Others, like myself, have to *look* for opportunities to use 
DocBook, in the midst of a whole range of other demands, tools and 
approaches to getting something down on paper or up on the web.

> Personally, I see three disadvantages of that:
>
> 1.  someone has to do the bolting for a given application;
> 2.  the tools have to support bolting/unbolting;
> 3.  as soon as you bolt together one setup, someone is
>     going to want/use/expect a tag you didn't bolt in.
Yes. And that's what I meant by the difficult challenge of what to do, 
how and when. But the DocBook direction has always been toward 
customization. Is there an easier way, or a more generic way of doing it?

> Or, put in terms of user requirements, I see your suggestion
> accrues negative rather than positive points in the corresponding
> three (plus) user requirement areas:
>
> 1.  I can use the off-the-shelf DocBook application with no extra work.
Could you please list them for me? I gather Epic makes the claim and 
there are one, perhaps two of the under $100 editors. Are there a 
significant number of others? Using current, XML versions of DocBook? I 
use XMetaL and it is, unfortunately, a fair amount of work just getting 
something into the editing area that looks half-decent. Getting to a 
really smooth and robust editing environment for a MSWord convert is a 
tremendous amount of work.

> 2.  I can find lots of tools that handle my application with little or
>     no configuration.
Lots? Same as above?

> 3.  I can expect all of DocBook to be available; I can use TDG as a
>     reference with no surprises; 
All of DocBook and the "general, newbee, somewhat doubtful about this 
new markup and controlled editing thing" freezes in his tracks, 
confounded by a wealth of (to him) meaningless choice.

No surprises? This is clearly not the case, Paul, otherwise there would 
be significantly less traffic on this list. Every day there are 
surprises and inconsistencies because it is all a living, breathing, 
evolving system.

Perhaps what's needed is some sort of map of the terrain that outlines 
some recommended ways of getting up the curve on the DTD and on the 
stylesheets and then...

Cheers.             ...edN