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

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.



W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198


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