Re: DOCBOOK: A straw proposal for help topics in DocBook

[martin dot gautier at myrnham dot co dot uk]

>>|    So it looks like if we use a Section-like (instead of Chapter-like)
>>|    content model for Topic, it'll mean that Topics can contain only
>>|    recursive Sections, not numbered ones (Sect1-Sect5), and that
>>|    Topics can't contain Refentrys at all (or Simplesect).

>>I am strongly opposed to allowing Topics to contain any form of
>>sectioning element. They are not part of the sectioning hierarchy,
>>that's one of the main motivations for creating them (IMHO).

There's some logic there but it would certainly be useful to support some 
sort of sort of container(s) within <topic> to allow us to seperate out 
the topic content. For example, a topic on "How to start your car" might 
contain a discussion on what the engine is, why it needs to be running and 
what equipment is required to start the car (the keys), this discussion 
might be followed by a procedure listing the steps taken to start the car 
(put the keys in, gearshift in neutral, turn the key etc.). The 
<procedure> element exists but not a <discussion> type element. I 
currently use the following syntax for such documentation:

<chapter>
  <title>How to Drive</title>
  <section id="1000" role="topic">
      <title>Start to start your car</title>
      <section role="discussion">
          <title/>
          <para>you use your keys to switch on the engine to make your car 
go</para>
      </section>
      <procedure>
          <step><para>put your keys in the ignition</para></step>
          <step><para>check the gearshift is in neutral</para></step>
          <step><para>turn the key</para></step>
      </procedure>
  </section>
  <section id="1001" role="topic">
  ...
  ...
  </section>
</chapter>

Mart
____________________________________________________
Martin Gautier
Technology Consultant
Myrnham Associates
Ph: 0709 2234 228
Fax: 0702 0967 322
email: martin.gautier@myrnham.co.uk
Web: http://www.myrnham.co.uk/



----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>