This is the mail archive of the
mailing list for the DocBook project.
- From: Norman Walsh <ndw at nwalsh dot com>
- To: docbook at lists dot oasis-open dot org
- Date: Mon, 03 Dec 2001 06:34:32 -0500
- Subject: DOCBOOK: Re: listitem
- References: <F211Wtyi67EKRuYDlrj00022821@hotmail.com>
/ "Matt G." <email@example.com> was heard to say:
| >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).
What are the semantics of your data?
| 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).
Using what backend?
| 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.
There's a great long list of structural elements than you can put
inside a list item. Section isn't one of them because it would make a
complete mockery of the document hierarchy.
| 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).
"Title on the same line" is a presentational, not a semantic or
| I mean, I can't believe you wouldn't want to be
| able to generate something like the following:
| name: Foobius Baricus
I use variablelists for this and a stylesheet that presents them the
way I want. I recently added some PI support to the XSL HTML
stylesheets to do this, I'll probably put those in the FO stylesheets
eventually as well.
I suppose you could use a table as well, if you wanted to.
| 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
"DocBook is an XML/SGML vocabulary particularly well suited to books
and papers about computer hardware and software (though it is by no
means limited to these applications)."
The target domain of DocBook is computer software and hardware
documentation. It happens to be suitable for a very wide range of
other sorts of documentation, but the technical committee has
historically been reluctant to add new markup specifically for
features outside the scope of its present domain (DocBook is quite
large enough :-).
| 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).
If your data is nested lists, then nested lists is a perfectly
reasonable way to mark them up. If you think your data is something
other than nested lists, you haven't made it clear what you think it
| 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
Given my experience with the way authors write, it's generally
impractical to separate document structure entirely from lower-level
Yes, authors can be *trained* to write this way, but it's not the
natural way that we're all taught to write from about the second
| 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.
Uh huh. Been there, done that. Do it often, in fact. Although I think
I tend to do it from the "other end" so to speak. Usually, I have some
very specific set of data that doesn't fit nicely into my
documentation markup, but I want to use it in my documentation. So I
write an XSLT stylesheet to convert it into the documentation markup I
want. Then with makefiles, I can edit the data and rebuild the
documentation entirely painlessly.
| 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).
Sounds like a fine plan to me.
Be seeing you,
Norman Walsh <firstname.lastname@example.org> | There has never been a perfect
http://www.oasis-open.org/docbook/ | government, because men have
Chair, DocBook Technical Committee | passions; and if they did not have
| passions, there would be no need
| for government.--Voltaire