OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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