This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: listitem
- From: "Matt G." <matt_g_ at hotmail dot com>
- To: bobs at caldera dot com
- Cc: docbook at lists dot oasis-open dot org
- Date: Mon, 03 Dec 2001 07:24:24 +0000
- Subject: DOCBOOK: Re: listitem
- Bcc:
> > 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
reference).
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
context).
>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