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

[Michael Smith <smith at xml-doc dot org>]

Norman Walsh <ndw@nwalsh.com> writes:

> There's been a fair amount of discussion about how to make DocBook
> more help-friendly. Since we don't seem to be making a lot of progress
> in the absence of a concrete proposal, attached is my first draft of a
> concrete proposal. There, now there's something to throw rocks at. :-)

FWIW, I've also recently put together an online-help customization
layer. I hope it doesn't complicate the discussion to much, but I've
just posted it at my site for anybody that wants to try it out.

  http://www.logopoeia.com/xml/helpset/

> [...]
> I've added three new elements:
> 
>   HelpSet - peer to Set, this is a set of HelpProjects.
>   HelpProject - peer to Book, this is a set of Topics.
>   Topic - an individual topic, recursively allowing sub-topics.

In the one I put together, I went without a peer to Set, and just used
Helpset as a peer to Book and Topic as a peer to Chapter. Here are the
content models I went with for those:

  <!ELEMENT   helpset
                     "((%div.title.content;),
                        helpsetinfo?,
                      ( glossary
                      | %topic.class;
                      | reference
                      | part
                      | %appendix.class;)+)"
  >

  <!ELEMENT   topic
                     "(topicinfo?,
                      (%bookcomponent.title.content;),
                      (%nav.class;)*,
                      (%bookcomponent.content;),
                      (%nav.class;)*)"
  >

The Helpset model I used is the same as Book, minus the navigational
pieces (ToC, LoT, Index), and the Topic model is basically just a
straight copy of the Chapter model.

So here are some comments/questions:

1. Online-help peer to Set. Do we actually need one? What will the
   processing expectations be for it? Do any of the existing help
   systems -- HTML Help, Javahelp, or whatever -- provide any way for
   packaging up sets of HTML Help files?

2. Element names. If we do keep the peer to Set, I don't think we
   should call it Helpset. I think Helpset is what the Javahelp DTD
   uses as its primary wrapper for topics, and I sometimes see the
   word "helpset" used generically to mean "online help file".

   I think Helpproject is good as the name for a set of topics; some
   other possibilities: Helpfile, Helpvolume, Helpset. But I guess
   Helpproject seems best.

3. Content model for the set-of-topics element (Helpproject). Does it
   need to include the navigational components (ToC, LoT, Index)?
   These seem useful only if authors want to manually author ToCs,
   LoTs, and Indexes, instead of leaving it up to the
   stylesheets/helpcompiler to generate them. Does anybody really
   manually author those?

4. Content model for the Topic element. I think I remember Nancy
   Harrison mentioning on the TC list a while back that the content
   model for a help topic should maybe be more like that of a Chapter,
   so that's what I based the Topic content model on in the
   customization layer I wrote.

   It seems like the only real difference between a DocBook Chapter
   and Section is that Chapters can contain Sect1, Simplesect, and
   Refentry, while Sections can't.

   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).














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