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 <[EMAIL PROTECTED]> | If today was a fish, I'd throw it
http://www.oasis-open.org/docbook/ | back in.
Chair, DocBook Technical Committee |
----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>
