[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: A straw proposal for help topics in DocBook
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. :-) Why are we doing this: 1. Because help documentation is less book-like and more topic-oriented than DocBook appears to be. 2. Because there are other motivations for a "topic" wrapper even within book-oriented documentation. 3. As a side benefit, I think this proposal makes it possible to write task-oriented documentation (e.g., in the DITA architecture) independent of the specific help context. (This is just speculation, I haven't done any study on this point.) What's the plan: The overall plan is to allow people to author "Help Sets" using all of the rich technical structure of DocBook without shoe-horning it into the classical print book model. How does it work: 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 addition, Topic is allowed in Chapters at the same level as, for example, Section and Sidebar. Here's a customization layer that implements this proposal (a few PEs should be renamed, this is just a draft proposal). Comments, please. <!ENTITY % local.divcomponent.mix "|topic"> <!ENTITY % docbook PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> %docbook; <!ELEMENT helpset ((%div.title.content;)?, helpsetinfo?, toc?, helpproject+, setindex?)> <!ATTLIST helpset %status.attrib; %common.attrib; %set.role.attrib; %local.set.attrib; > <!ELEMENT helpproject ((%div.title.content;)?, helpprojectinfo?, (toc | glossary | topic)*)> <!ATTLIST helpproject %label.attrib; %status.attrib; %common.attrib; %book.role.attrib; %local.book.attrib; > <!ENTITY % topic.title.content "%sect.title.content;"> <!ENTITY % topic.nav.class "toc|index|glossary %local.nav.class;"> <!ELEMENT topic (topicinfo?, (%topic.title.content;), (%topic.nav.class;)*, (%divcomponent.mix;)+, (%topic.nav.class;)*)> <!ATTLIST topic %label.attrib; %status.attrib; %common.attrib; %section.role.attrib; %local.section.attrib; > <!ELEMENT helpsetinfo ((graphic | mediaobject | legalnotice | modespec | subjectset | keywordset | itermset | %bibliocomponent.mix;)+)> <!ATTLIST helpsetinfo %common.attrib; %sectioninfo.role.attrib; %local.sectioninfo.attrib; > <!ELEMENT helpprojectinfo ((graphic | mediaobject | legalnotice | modespec | subjectset | keywordset | itermset | %bibliocomponent.mix;)+)> <!ATTLIST helpprojectinfo %common.attrib; %sectioninfo.role.attrib; %local.sectioninfo.attrib; > <!ELEMENT topicinfo ((graphic | mediaobject | legalnotice | modespec | subjectset | keywordset | itermset | %bibliocomponent.mix;)+)> <!ATTLIST topicinfo %common.attrib; %sectioninfo.role.attrib; %local.sectioninfo.attrib; > Be seeing you, norm -- Norman Walsh <ndw@nwalsh.com> | If today was a fish, I'd throw it http://www.oasis-open.org/docbook/ | back in. Chair, DocBook Technical Committee |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC