FW: comments on draft DITA 1.1 Arch Spec.

["Grosso, Paul" <pgrosso@ptc.com>]

Attached as PDF is an annotatd copy of the architectural spec.

Below are some more general comments. 

paul
________________________________

From: Ogden, Jeff 
Sent: Tuesday, 2006 October 03 09:07
Subject: comments on draft DITA 1.1 Arch Spec.

Attached is a PDF file with notes and comments on the 
draft DITA 1.1 Architectural Specification.

In general I think this draft is pretty good.  I do think 
that the specification needs some fairly major reorganization 
to make it easier to use and to give it a better flow.  This 
is particularly true of the current chapter 3 which toward the 
middle becomes sort of a grab bag for lots of things and as a 
result becomes hard to follow.  I made some suggestions about 
this in the pdf file.  I didn't say this in the PDF file, but 
I think that the spec. document would benefit if the sections 
were numbered.

I haven't gotten very far on reviewing the draft DITA 1.1 
Language Reference.  I'll include a few comments here:

There needs to be some more information on abstract and multiple 
shortdesc within abstract, how multiple shortdesc should be treated 
in terms of presentation and overrides.

In the bookmap description it talks about the title attribute, 
but the title attribute isn't allowed with bookmap.

The bookmap description needs to say more about the use or 
non-use of the optional href attribute on elements such as 
toc and other booklist items. Right now it just isn't clear 
when a toc or other lists are automatically generated and 
when they aren't.

There is information that is currently only available in the 
DITA Arch. Spec. which should really be added to the DITA 
Language Spec.  Specifically:  

i)   Which attributes are specializable (only props and base)?

ii)  Which attributes inherit a default value from an ancestor?

iii) Which attributes have implied default values that are
     not given in the DTD or schema, but which are never-the-less
     part of the DITA Standard?

iv)  Which attributes have a default value that is not given
     in the DTD or schema, but which is implied by the processing
     application or stylesheets and is not specified as part of
     the DITA Standard?

The Default Value column in the various attribute descriptions 
could hold this information. Right now it is largely a waste of 
space and usually just repeats #IMPLIED.

The Required? Column in the attribute descriptions is confusing.  
Is this required by the DTD?  Are there cases where something is 
required by the DITA Standard, but not required by the DTD?  href 
on image for example? Since so few attributes are required, it might 
make sense to eliminate this column and simply say that no attribute 
is required unless it says that it is in the Description column.  Or 
they could add an asterisk or the word (required) in parens to the 
Name column.

The description of scale on the image element is incorrect.  Rather
than only specific values allowed (50, 60, 70, ...), this got changed 
to an MNTOKEN.

Some additional explanation of the height and width attributes on 
image is needed.  We now allow units to be specified.  This is 
text Paul Grosso provided long ago.

The longdescref attribute on image could be a little more specific 
or at least refer to the related xml standards upon which this is based.

This version is better, but in places the DITA Language Spec. 
is still confused about if it is documenting the DITA Standard 
or documenting the current implementation in the DITA Open Toolkit 
or both. I think it should only document the DITA Standard.  

If it must include information on the implementation in the DITA 
Open Toolkit, it needs to be very clear when it is doing that.  
In particular see: refcols attribute on the properties, choicetable, 
and simpletable elements, the note for indextermref, the component 
element description, duplicates attribute on the linklists and 
linkpool elements, the chunk attribute on various elements, the 
anchor and navref element descriptions and map ref attribute on 
navref, the lockmeta attribute on the topicmeta and bookmeta 
elements, and %select-atts; description for importance.

The description of the href attribute on topicref hasn't been 
updated to cover the case of an href to a ditabase without an ID.

dita1.1ArchSpec26Sep2006-jco.pdf