Re: [dita] editorial help: conref.dita

[Eliot Kimber <ekimber@reallysi.com>]

On 7/11/09 11:14 PM, "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote:

> Sounds like you need to have a valid DITA document with a topic DOCTYPE
> declaration in the prolog in order for the processor to recognize the
> target element as valid. Otherwise, you could just point to any
> well-formed XML that happened to contain a DITA element at the target
> location. Maybe it can't locate the target unless the DOM is valid DITA?
>  
> I'm struck by the parenthetical. Should we say to use topicref if you
> want to point to a topic or map?

The root elements of all conforming DITA documents must be a specialization
of map/map, topic/topic, or be the element type "dita". The DITA
specification does not recognize as conforming any other XML documents.

Therefore, while it would be syntactically valid XML to have, e.g.:

<!DOCTYPE p PUBLIC "-//PUBLIC//DOCTYPE Topic//EN" "topic.dtd">
<p>This is a document containing only a DITA paragraph</p>

the DITA spec does not recognize that document as being conforming.

I'm not sure I agree with the reasoning behind the restriction, but I don't
think it's entirely unreasonable and it is definitely the law for DITA 1.x.

Note that DITA does *not* require documents to be governed by DTDs or
schemas. We are clarifying that fact in the 1.2 spec.

One general issue is the ability to recognize DITA content as being DITA
regardless of the use or non-use of a particular DTD or schema--the DTD or
schema public ID, system ID, or schema location is not distinguishing in
DITA because users are allowed, if not expected, to create local shells.

What is distinguishing is the DITAArchVersion attribute, which is in a
DITA-defined namespace. That, plus a @class attribute with a recognized
values (e.g. "- topic/topic ... " or "- map/map ..." is a pretty unambiguous
indication that what you have is a DITA document.

DITAArchVersion is only specified for topic, map, and dita. So the <p>
document above would not have the attribute and therefore would lack the
"this says it's DITA" signal. Because the DITA spec requires conforming DITA
documents to be rooted at topic, map, or dita, that's not a problem. If the
root-element restriction were lifted, all DITA content would need to have
the DITAArchVersion attribute or some similar namespaced component to act as
a signal.

Note that a way to have namespace-qualified module names would solve the
problem, but that must almost certainly wait for DITA 2.

Cheers,

E. 

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>