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: Re: DOCBOOK: A straw proposal for help topics in DocBook


Norman Walsh <ndw@nwalsh.com> writes:

> / Michael Smith <smith@xml-doc.org> was heard to say:
> 
> |    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).
> 
> Perhaps HelpProjects should allow (topic|refentry)+...

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

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.

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?

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.

So maybe the help-topic model and the topic-added-to-divcomponent.mix
need to be two different elements with different content models. And 
maybe it would also make things more clear if the help-topic element
were named Helppage or Helptopic instead of just Topic.

I recognize that part of the goal behind the idea of a adding a Topic
element is facilitating reuse of content, and that if we were to add
both a recursive-topic-added-to-divcomponent.mix element and a
help-topic element, with two different names (say, Helppage and Topic)
it'd mean that you couldn't just take a bunch of individual Topics,
put a Helproject wrapper around them, and generate online help from
them -- you'd first need to make them into Helppages, or group them
into Helppages.

But then, if you wanted to put together a Book from your Topics, you'd
first need to make them into Chapters, or group them into Chapters --
same if you were using the Website module and wanted to make Webpages
from your Topic content, and same with any other existing DocBook
hierarchy you'd want to put them into.





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC