[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: FW: comments on draft DITA 1.1 Arch Spec.
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]