Re: [docbook] DocBook SCs

[Dave Pawson <davep@dpawson.co.uk>]

maxwell@umiacs.umd.edu wrote:

>>> I'll also mention that one of the things that bothers me about the
>>> current DocBook is that it seems to be so oriented towards computer
>>> documentation.
>> Which is good, since that is just where it originated!
> 
> Sigh, because that's where it will stay unless it improves!

Which is a perfect match for a majority of users.
Otherwise it wouldn't have reached the usage it has?

'Improves' is a perspective.


> There is obviously a core set of concepts that are generic: book/ article/
> report etc.; sections, paragraphs, itemized or numbered lists, pictures
> etc.  But a concepts like 'hardware', 'classname', (EBNF) 'constraint',
> 'destructorsynopsis', just to take a few that leap off the page--these are
> relevant only to software and/or hardware documentation. 

Which is what Docbook started as. You may not want it, others do.


  I suspect
> there's a large community of people out there who might use DB, but are
> scared off by the need to wade through all this software documentation
> "stuff" in order to find the core concepts. 

Open disagreement here.
   I guess I've used some of the 'software' elements only a couple of 
times in about 10 years of docbook usage. Like you I use it far more
generally.

I have never 'waded through' the documentation for those elements.
I use the documentation to find out what elements I want to use. No 
more.  If you want to create a subset of the documentation, that's
a different proposition to creating a schema that suites your needs
to drive a syntax directed editor.



  As long as it isn't
> modularized to put all that "stuff" somewhere, "all the other docbook
> users" that you refer to are going to stay the same, and most of the
> people who might otherwise use it are going to stay with Microsoft Word or
> Open Office.  IMHO.

Not happened so far it would seem. All I see is a growth in docbook 
usage. Word and ODF users are often looking for something different
to those who approach docbook.



> 
>> I guess we all use docbook for different purposes.
> 
> Exactly my point; you don't want to see the linguistic tags that I use in
> my grammars :-), and I don't want to see most of the software tags that
> you use in your computer documentation, or all the publishers' tags.

If linguistics is your forte, is TEI any better suited as a starting 
point? Chances are you are eventually going to want to add, modify,
remove for your own usage. The all encompassing schema that suites
all of us is a myth.



> 
>> If you're bothered by the high tag count, you could create
>> your own subset, removing those elements you don't want,
>> for your own use.
> 
> As I mentioned in my original posting, this is what I have already done. 
> But that probably makes my core subset different from someone else's core
> subset, 

Which is one reason why docbook is such a good design. We can both use
subsets, and take advantage of the full processing from XML through to
X media. Including the 'tarting up' achieved through XSLT customization.
   I see that as win win.




>while they could (and I believe should) be the same. 

Again I'd disagree. Why do you think that as important?

I have never used <synopsis>. Why should I have it in my schema?


  Everything
> else can and should be this or that module--a module for grammars, a
> module for software documentation, including a way to use some of those
> additional tags in more than one module.  (I use literate programming tags
> in my grammars; I can imagine a software documenter wanting to do the
> same, and our use of those literate programming tags should be the same.)

Yep. Ad nauseum for all the other users of docbook. Why do we need to
all share exactly the same sets/subsets?

The 'modules' you mention may be the same as the subsetting and picking
and choosing I'm talking about when I set up my own schema.

I can't see the end game here (accepting that I doubt all users would
ever share a common schema once they accept they need additions, changes 
etc)



> 
> (BTW, I found Scott Hudson's comments on my earlier posting very helpful,
> and it sounds like he and I are thinking along the same lines--I hope
> Scott doesn't mind my saying that.)






regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk