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

Well yes Erik, I can see that.

It makes sense that reference topic types might require a richer assortment of nesting structures that mimic the well-defined hierarchical arrangement of their subject matter.

Perhaps one could merely deprecate nesting tasks inside tasks, or concepts inside concepts.

As I recall, minimalist topic orientation was invented to move away from the highly nested, lengthily belabored discursive structures that reference material often requires.

On the other hand, I personally might have no objection to a topic that was only a title, with no elaboration, if we considered doing that to remove the inconsistencies with maps Eliot has pointed out.

Sometimes the title really does say it all.


Erik Hennum wrote:

Hi, Dana:

The API Reference and Java API Reference specializations are in fact available on the Open Toolkit site, but you're not at fault for missing them. You have to go to the "Plug-ins: specializations" section and click on the link for "View older releases from the Plug-ins: specializations package" The current web UI only accomodates 3 plugins, but I understand that can be changed (which is pretty important for the plugin contributors). The Java API depends on the API Reference specialization, by the way.

Anyway, regarding the substance -- there was a fit with existing practice: a JavaDoc description of a method typically stands alone as a highly linked target. In the implementation, the method descriptions were quite convenient to model as topics (the same basic structure applies to both class and method descriptions). Supplementing the API relationships with map-based management of related links (and, one hopes, DITA 1.2 implicit linking based on mentions of keywords and terms) are other good reasons.

But, while method descriptions seem a good fit for topics, they wouldn't work as well as _separate_ topics in the sense of separate files assembled by a map -- largely because the subject matter (a Java class) has a single nesting structure that's a stable unit.

Hoping that's useful,

Erik Hennum

Dana Spradley <dana.spradley@oracle.com> wrote on 01/02/2007 02:45:56 PM:
> Are these specializations available for download from IBM? I don't
> see them in the toolkit.
> If I may inquire, what prompted the decision to use nested topics,
> instead of nested sections, in programming class topics to handle
> methods of that class?
> As you indicate, they don't really make sense as separate topics.

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