[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: New wrapper between procedure and step?
I think it could be very useful for official DocBook to have a new intermediate wrapper for sets of steps -- perhaps called <stepset> or <stepgroup> -- between the <procedure> and <step> elements, like this: procedure | |_title | |_para* | |_stepset+ | |__step+ The difference between a <stepset> and <procedure> would be that <stepset> could *only* contain <step> elements as its immediate children -- no <title>, no <para> or anything else. That is, its declaration in the DTD would simply be: <!ELEMENT stepset step+> I have a couple of reasons for thinking <stepset> might be useful: 1. Enables more granular reuse of steps among different documents. For example, my group creates admin guides as well as courseware. For any given procedure in the courseware, the set of steps are identical to the set of steps in the admin guide, *BUT* the set of steps are often labeled with a different <title> element in each book, and usually have a different introductory paragraph. Having a <stepset> wrapper makes it possible for us to store and reuse _just_ the sets of steps -- without the <title> or <para> material specific to the particular context of an admin guide versus a training manual. 2. <stepset> maps more closely to <ol> in HTML Stylesheet transforms expose deficiences in the HTML model for ordered lists. That is, there's some ambiguity in the way the following should map to HTML: <procedure>... <title>... <para>... <step>... The wrapper for ordered lists in HTML is <ol>. When the above is transformed to HTML, what should the <ol> contain (if anything) in addition to the steps themselves -- the <title> contents, the <para> contents, both <title> and <para>, or none? With a <stepset> there's no ambiguity -- it maps one-to-one directly to <ol>. Of course, I could make a DocBook customization to restrict authors from putting <title>, <para>, etc. within <procedure>: <!ELEMENT procedure step+> That basically makes <procedure> become <stepset>. But the downside of that is of course that I lose a means to enforce a predictable way for titles to be associated with procedures, or to more easily search for procedures based on titles. For example, I can now do a query for "procedures that contains titles which have the following words", and still could if I used (A) below: A B -------------- ------------- <procedure>... <section>... <title>... <title>... <para>... <para>... <stepset>... <procedure>... <step>... <step>.... In (B), which is how I'd need to do it if I restricted <procedure> to only containing <step> elements, <procedure> and <title> are of course just siblings, children of <section> (or whatever), so I'd have to instead query for "sections that contain (1) titles with the following words and (2) procedures as siblings of those titles." The other issue with adding an element of course is that if you make it required, it's not backward-compatible -- that is, older document instances lacking <stepset> won't validate against the revised DTD. So I guess <stepset> could be made optional, although I wouldn't want any of the document authors in my group to leave it out. Anyway, I'd be interested in discussing this "just steps" wrapper with anyone interested. Anybody agree, disagree, ...? --Mike Smith -- Michael Smith mailto:smith@xml-doc.org XML-Doc http://www.xml-doc.org/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC