[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