Fw: Comments on OASIS DITA committee draft 1.0

[Michael Priestley <mpriestl@ca.ibm.com>]

Copying the comments into the email
for those who don't have Word - attachment included for those who do. Responses
in the email only, marked with >>:


Comments on the Language Specification
Conditional Content  
Filtering and flagging. We would like
the OASIS DITA Technical Committee, and the standard itself, to encourage
developers of DITA-compliant authoring tools to support the otherprops
attribute in ways that make it easy for writers and editors to manipulate
multiple conditions as if they were separate attributes, and that hide
the syntactic complexity of shoehorning multiple condition/value pairs
into a single attribute. We think this is necessary if writers and editors
are to use the otherprops method effectively and productively.
>>Several authoring tool vendors
have representatives on the DITA TC, so the feedback is going to the right
place. I don't believe the specification can afford to recommend a particular
solution in the authoring tool, however. All the spec can do is speak to
the validity of the source, and recommended processing and output.

Looking beyond 1.0, is there any reasonable
way of adding selection attributes to the spec—either attributes with
a standard definition (e.g. businesspartner), or generic selection attributes
to be used as each implementer sees fit (e.g. select08)?
>>It is definitely on the list
for consideration. Several people have raised this as a high requirement.
 

Variables. We want to define an entity
in a map, and have the definition be inherited by all the topics referenced
in the map. This would enable us to declare entities at the book level
and have those declarations apply to all the content units in the book,
which we had done easily in FrameMaker.
We’re aware of the issues that Don
Day raised in dita-users # 231 regarding using entities. However, we’re
seeking a method that’s more straightforward than conref and that is supported
more robustly in tools. How do you think this can be achieved?  
>>Use of entities is discouraged
in DITA, so I'm not sure how much help the spec can be in this regard.
I will note that conref is directly supported by several authoring tools
these days, so you may want to revisit your decision not to use it. 


Maps  
Path support. Is it possible to specify
a directory path to a topic in a map? We cannot discern this from the draft
specification. 
We see that the specification does say
that “[Topicref’s] href attribute identifies the destination of the cross-reference
link using conventional URL syntax....”  And standard URL syntax
seems to support directory paths using the file protocol, allowing one
to specify any file on a local computer system (see http://www.w3.org/Addressing/URL/uri-spec.html
and http://www.w3.org/Addressing/URL/4_1_File.html).
We see that Chris Wong noted in dita-users
#192 that “The href attribute is by convention a URL or some filesystem
path.”
Can you clarify this in the specification?
If directory paths are supported in href, can the spec state that explicitly?
If they aren’t supported in href, can that be added to the spec?
>>The spec requires that it be
a valid URI, but it's up to the processor to decide what kinds of values
to support. I'd generally think that absolute paths would be something
to avoid, as in HTML - relative URIs are typically more portable. But again,
I think all the spec can say here is what it currently does: must be a
URI.

Database support. In topicref’s href
attribute, we need to specify a topic that resides in an XML database.

>>Seems reasonable, as long as
it's done with URI syntax. Again, more specific syntax will depend on your
implementation, which I don't believe the spec can speak to in more detail
than it already has.

Presentation  
Content models. In Ch. 1, most elements
don’t show a content model—that is, for each element, which elements
can contain it, and which elements it can contain. We think that these
models would make it easier to evaluate and use the specification. We know
that earlier drafts of the DITA Language Reference included this information
(e.g., ditaref-book.chm) and suggest adding them to subsequent iterations
of the specification.
>>Fixed in new version.

Examples.  We think that adding
examples to illustrate the use of all attributes—not just the most commonly
used ones—would make it easier to understand the specification.
>>Adding more examples will definitely
be a priority for future versions. 

Alphabetical order. Ch. 1 generally
presents elements in alphabetical order, but some elements are out of order.
For example, topicref is followed by topichead, which is followed by topicgroup.
>>New version orders elements
by module and category.

Comments on the Architectural Specification
Correction. On page 11, we noted that
the example element at the left margin is missing a closing bracket (>).
>>Good catch - will fix.



Michael Priestley
mpriestl@ca.ibm.com
-

<Mark_Nazimova@ibi.com>

03/15/2005 04:13 PM

To	Don Day/Austin/IBM@IBMUS
cc	<Ghada_Captan@ibi.com>, <Frances_Gambino@iwaysoftware.com>
Subject	Comments on OASIS DITA committee draft 1.0

Dear Don,
 
I've attached comments on the OASIS DITA
Specification committee draft 1.0, from the Information Builders Documentation
Services team.
 
If you have problems accessing the attached
Word file, please let me know.
 
With regards,
Mark Nazimova
Information Architect
(917) 339-6736

DITA Committee Draft Comments.doc