[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 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC