[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: A straw proposal for help topics in DocBook
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).
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC