OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: DOCBOOK: Re: listitem

> > I think I've just run into exactly the same problem: I have a
> > <variablelist>, but I want to be able to nest more structure
> > inside the <listitem>, for each entry!  Here's an sample of the
> > information I'd like to be able to provide about each variable:
> > * descriptive name
> > * type
> > * units
> > * description
> > * usage predicates (conditions which must or must not be true for
> >   it to be used)
> > * valid values (may be a range, value, or list of ranges
> >   and/or values)
> > * dependencies of field values on things like values or ranges of
> >   values of other fields and system state
>You might try using nested variablelists.
>Inside each of your main listitems, use a variable
>list for this structured information.

Well, I have a couple of problems with this approach.  First of all, it gets 
even further from the proper semantics to describe what I'm actually trying 
to do (though I could deal with that, though hopefully it'd only be a 
stop-gap measure).  More importantly (in the short-term) it doesn't even 
appear to be nested, at all, in the DSSSL print style-sheets (version 1.74b 
- the latest).

Anyhow, I believe I've discovered at least one hole in the version of 
DocBook I'm presently using (4.1.2; I'm referring to TDG v2.0.2, as a 

First of all, I feel one needs to be able to nest structural elements in 
<listitem>.  I'd certainly like to hear other points of view, on the matter, 
but I just think it's imperative to be able to partition a <listitem> into a 
finer-grained structure.

Secondly, I'm surprised there's no sort of an element with a title on the 
same line (see my <namedproperty> block element example, in my previous 
message).  I mean, I can't believe you wouldn't want to be able to generate 
something like the following:

	name:		Foobius Baricus
	sex:		N/A
	species:	computer program
	manifestation:	fictitious
	age:		14 months
	job:		opensource software tester
	annual income:	$0

Sure, you could create tags for each of those fields, then add a wrapper 
element or two, augment the stylesheets to synthesize this sort of output, 
and there you go!  HOWEVER, if DocBook is ever to scale to meet the basic 
needs of a substantial portion of the various technical and scientific 
documentation sub-domains, it must provide comprehensive semantics to 
describe all the various sorts of document and publication constructs, as a 
fall-back for cases where semantics specific to the problem-domain aren't 
available.  While I'm aware that this may elicit an adverse reaction among 
some of you, I see it as vastly preferable to the outright ABUSE of existing 
problem-domain oriented semantics, on the basis of their structural and 
presentational qualities (which is how I regard the use of <variablelist> to 
provide structure within a <listitem> element).

In fact, my opinion is that there should be a layer *between* problem-domain 
specific semantics and XSL-FO, which would be comprised exclusively of 
constructs relating to document structure.  Then, an organization, company, 
standards body, etc. that wants to use DocBook as the basis for their 
documentation has two avenues they could pursue.  If they are fairly 
unambitious, they can seek to augment the structural vocabulary with some of 
their own extensions.  If they want to promote or enforce more rigid 
semantics that deal exclusively with their problem-domain, and/or if they 
want close control over the structure and content of their output documents, 
they can add a layer on top of the document structure semantics (using XSLT, 
to do the translation into XML DocBook, for example).  Furthermore, there 
would be a fairly smooth transition path from the former to the latter.

As it happens, I'm in the process of doing the former, however I'm 
generating external parsed XML DocBook entities.  So, it's a little like the 
latter, in that it's partially layered on top of DocBook.  I'd hoped to take 
advantage of DocBook stylesheets to do most of the formatting work, for me.  
I also wanted to be able to use the core DocBook semantics in portions of 
the documents that are written by hand (these parts contain the actual 
references to the external entities, giving the author the ability to change 
their order and use, within the document, as well as provide additional 

>Bob Stayton

I do appreciate your reply, though I've decided to get entirely away from 
using <variablelist> (for this purpose), at this point.  I'm just using a 
bunch of <refsect> elements.  It doesn't work as well as I'd like, but it 
gets the information into the document in a somewhat useable format.

>Publications Architect

Ah, now that sounds like a company that takes technical documentation 
seriously.  I wish my employer would.  We're long past the point where it 
would be more cost-effective to manage and structure our documentation like 
a software project, but they don't get it.  (So, I hope to show them how 
it's done.)

Matthew Gruenke
(company name withheld to protect the clueless.  Now, whether that applies 
more to the remaining employees, or the investors, is left as an exercise to 
the reader.  ;-)

Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC