Re: DOCBOOK: A straw proposal for help topics in DocBook

[Gershon L Joseph <gershon at mainsoft dot com>]

On Thu, 18 Oct 2001, Michael Smith wrote:

> However we decide to model it, it seems like Refentry needs to be
> allowed in there somewhere.
Agreed.

> And if we do add a recursive topic element to divcomponent.mix, I too
> would be strongly opposed to allowing it to contain other sectioning
> elements.
I agree.

> But if we can set aside for a minute the idea of adding a recursive
> topic element to divcomponent.mix, and discuss just the proposed Help
> hierarchy: Is it reasonable to disallow document authors from using
> Sect1-Sect5, Section, and Simplesect in help content?
>
> What would I do, for example, if I want to use the proposed Help
> hierarchy with existing content that I've already authored (for a book
> or whatever) or gotten from somebody else, and that existing content
> happens to contain Sect1-Sect5, Section, or Simplesect?
We already have this problem when migrating nested <section>s to
<sectx>... Do you think we should have <topicX> and <topic> to allow easy
copy and paste between help and book markup? (Assuming the authoring tool
supports automatic renaming of elements according to context, as Epic
does.)

> Also, does it make sense to model a help topic as a recursive element?
> What I mean is, in most (or maybe all) current online help systems,
> each help "topic" is actually a single HTML page/webpage (though that
> HTML page might of course be multiple physical pages if you were to
> print it out).
>
> So to model it accurately, it seems like the help-topic element
> actually shouldn't be recursive. I think it'd be like making Chapter
> or Article recursive -- just as real chapters can't contain other
> chapters, real help pages can't contain other help pages.
I don't think this is so for large help projects. Many winhelp and
HtmlHelp projects come to mind, e.g. MSDN or WordPerfect 9's online help.
There seems to be no limit to how far down the topic tree you can go. Some
topics contain subtopics only, while other have a topic page and also
subtopic pages. You could argue this is bad design (I tend to agree), but
this is what people do. I have found from bitter experience that sometimes
it's best to do online help this way, if you have different types of
topics, or some high-level topics are simple/short while others are very
detailed and more heirarchy makes it easier to navigate and read. I'd like
the DocBook solution to work for large help projects too.

[...]

Gershon


----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>