This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: A straw proposal for help topics in DocBook
>
>| 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?
>
>It is necessary to build them by hand sometimes. And even when it
isn't,
>there are systems that use an empty element (<toc/> or
<index/>) to
>identify where the auto-generated content should go.
We have had to hand-craft TOCs here, though not LOTs or Indices, so I'd
vote for making the element(s) available.
>
>| 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).
>
>I am strongly opposed to allowing Topics to contain any form of
>sectioning element. They are not part of the sectioning
hierarchy,
>that's one of the main motivations for creating them (IMHO).
I, on the other hand, am concerned with not allowing sections in the mix,
since that removes a transparent way to reuse data between print and
online delivery.
>
>Perhaps HelpProjects should allow (topic|refentry)+...
>
That's probably a good way to deal with refentry, but doesn't address my
concerns with reuse of data and sections.
I also think we need some navigation elements that facilitate the
building of online help and the kinds of online hierarchies or webs that
online help requires. One piece of this is probably bi-directional
links. Another might be 'onlineseealso' and/or 'relatedtopics'
elements that consist only of one or more links/xrefs.
Nancy
________________________
Nancy (Paisner) Harrison
Rational Software
Lexington MA
nancyh@rational.com