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


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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

Subject: Re: [dita] What Is A Topic

Personally, I'd like to see the definition of topic beefed up and kept in the standard, rather than watered down and demoted to a best practice merely.

One of DITA's prime distinctions is being a topic-oriented DTD, as opposed to, say, DocBook. Remove that, and you muddy its distinctiveness.

On the other hand, I agree with Eliot that inconsistencies have developed between nested topics and maps.

Perhaps nested topics should be deprecated, and maps promoted as the preferred means to collect hierarchies of topics.

If particular organizations still want to use DITA against the grain - well, there are always ways to accomplish that.

Happy New Year!


W. Eliot Kimber wrote:
Michael Priestley wrote:

On the issue of title-only topics in particular I wanted to add a few things:

- a small topic may legitimately need only a title and short description - our own glossentry specialization comes to mind. Some forms of context-sensitive help are also likely to be very short, and with the addition of abstract, easily accomodated without the <body> element.

Hmmm--I'll have to think about this more.

- a topic may start small and grow over time into a whole branch of topics. The container topic may be no more than a title and child links (or just a title, with child links managed via a map). But the container topic is still important as a link destination, because it still answers the question it originally answered when it was just a leaf-node topic.  People who link to the topic shouldn't be forced to recode or break their links just because the topic has changed from leaf node to container node. In terms of its subject, it's still the same topic.

This suggests to me that a different structure is needed rather than trying to have topic do double duty as both a coherent direct container of content and as simply a titled container.

For example, I'm starting to think that it would make sense to allow topichead wherever topic is currently allowed (possibly with a bit of augmentation). This works well in maps so why not allow it in topics as well? [But then would what it mean to have a document whose root element is topichead--not sure and I can imagine that Michael would immediately object to the possibility, which probably he should.]

On the other hand, I could easily accept Michael's more flexible concept of topic if we, as he suggests, add some discussion of how these two different uses of topic are intended to be used and what would likely constitute abuse of them.

Clarifying question: When you say:

"The container topic may be no more than a title and child links"

Do you mean using links from the related-links section with a semantic of "child"?

I ask because topic does not allow topicref where it allows nested topics (I originally expected them to be allowed) so I'm assuming that related links is the intended way to create explicit hierarchical relationships from within a topic to other topics. But then that raises the issue of there being three distinct ways to do it (with a map using topicrefs, with links, and with nested topics)--which approach do you choose when?

This question is somewhat driven by a question related to "what is a topic" which is "when do I use a map to express a unit of re-use (composed of a set of topics that don't have any real individual meaning) and when do I use a topic with nested topics?"

That is, the implication of Michael's reasoning for having title-only topics that then just point to other topics is that they serve as a consistently-available link target, which is definitely good. But given that I could do the same thing with a map and topichead, which *should* I do?

If I say "use maps for all collecting of topics" then it leads to the conclusion that there is a very real sense in which the map and the equivalent title-only topic are serving exactly the same rhetorical and practical purpose, which then suggests that either there's a need for a different kind of map that is really a specialization of topic or something.

But I do keep coming back to the possibility that the distinction between maps and bodyless topics is very slight and that perhaps it would make sense to unify them by allowing topic to allow topichead and topicref where it currently allows nested topics.

I also think that Michael's use case of a topic evolving from being a singular chunk of information to the root of a tree of related topics is a compelling one--it seems not only likely but inevitable.

However, I'm not convinced that the right solution is simply keeping the original topic around as a navigation target--given an appropriate indirection mechanism (and corrected addressing scheme) you could just as easily replace the original topic with a map (I can't do that today because the *syntax and semantics* for addressing maps and topics is different even though they probably shouldn't be).

That is, maybe there are really two distinct types of maps: maps that define entire units of delivery and maps that define units of re-use that are functionally equivalent to topics with tested topics and/or topics with child links to other topics.

To my mind, it certainly seems intuitive to use maps for all organizing of topics and it makes sense from a consistency of tools and work practice, but it doesn't, at the moment, seem to fit as well as it could or should with the current markup design. Thus my quandary.

So I think there's definitely room for refinement in our collective understanding in how to best address these issues of representation of collections of topics that form coherent (and necessary) hierarchies in order to convey a single "true" topic.



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