Re: [dita] What if the root element of a database was <topic> instead of

Why? What use cases are supported by a non-topic topic wrapper, that can’t be supported by a normal topic wrapping other topics?

Chris

From: Eliot Kimber <ekimber@contrext.com>
Date: Tuesday, April 3, 2018 at 10:52 AM
To: Chris Nitchie <chris.nitchie@oberontech.com>, "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: Re: [dita] What if the root element of a database was <topic> instead of <dita>?

For this to work we would have to definite it in a way that is analogous to <topicgroup>: A topic that *does not itself contribute* to the narrative content of the publication that includes it. In particular, any title on the element is ignored for normal output in exactly the same way that titles of submaps are ignored in normal output. Its semantic is only as a container of other topics that are normally used by direct reference to them, rather than by reference to the topic container. Normal metadata propagation rules would apply.

But given that definition, I can’t find any problem with the suggestion—I’ve never liked the <dita> element.

Cheers,

Eliot Kimber

http://contrext.com

From: <dita@lists.oasis-open.org> on behalf of Chris Nitchie <chris.nitchie@oberontech.com>
Date: Monday, April 2, 2018 at 7:08 PM
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: [dita] What if the root element of a database was <topic> instead of <dita>?

I don’t (yet) mean for this to be a stage 1 proposal; more of a trial balloon to see how much fire it takes. Call it a Stage 0.

The <dita> element is a special case, and special cases are bad. It’s not a topic; it’s a wrapper for topics. Its inclusion in the standard means it must be accounted for, in the rules we define for topic processing and in the interaction between a map and the resources it references. And I’m really hard-pressed to find any benefit to it over and above the use of a simple <topic> wrapper that isn’t compensated for by not having to account for it.

The rules for composite doctype shells would be exactly the same, except that you wouldn’t need to take the extra step of providing a definition for <dita>
Each topic in such a document would still be individually addressable.
It would mandate a title for a ditabase document (as opposed to prohibiting it)
And – this is the big one – it would behave as a normal topic in all processing contexts and not need any special-case rules.

Today, in DITA 1.3 (and 1.2, and 1.1), if you have a ditabase document, like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
<topic id="topic">
<title>Topic</title>
</topic>
<concept id="concept">
<title>Concept</title>
</concept>
<task id="task">
<title>Task</title>
</task>
<reference id="reference">
<title>Reference</title>
</reference>
</dita>

You can open it up in a text editor and rewrite it like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="root">
<title>This is a DITABase Document</title>
<topic id="topic">
<title>Topic</title>
</topic>
<concept id="concept">
<title>Concept</title>
</concept>
<task id="task">
<title>Task</title>
</task>
<reference id="reference">
<title>Reference</title>
</reference>
</topic>

This document is entirely valid, its constituent topics can still be addressed independently, and it has the benefit of behaving exactly like any other topic when referenced without a fragment identifier. It is no longer a special case where processing is concerned.

It’s entirely possible that there are use-cases for <dita> with which I’m simply unfamiliar. But in one of the e-mails on the list today related to Robert’s chunking proposal there was an aside about special handling for ditabases and it got me thinking about this. It feels like a good change for DITA 2.0 – simplifies the architecture, simple migration – but again, I may be missing something.

Chris

dita message