Re: [dita-comment] Public Comment

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

Responses below marked with  >>

Many of the issues discovered here were
already uncovered by previous reviews - the following additional changes
were required:
language spec:
- shape element: deleted browser-specifics
- entry element: added missing attribute
descriptions

arch spec:
- conditional processing: removed Windows
value from example
- collection-type example, reltable
example, identity attributes: fixed typos

comment-form@oasis-open.org

03/15/2005 11:46 AM

Please respond to
nigel_hopper

To	dita-comment@lists.oasis-open.org
cc
Subject	[dita-comment] Public Comment

Comment from: nigel_hopper@uk.ibm.com

Comments from three reviewers that are unedited, by me.

Reviewer One:

Architectural Specification
- Page 7. Implies that DITA is defined in DTD and Schema. Which of the
two is normative (my choice would be Schema if only because it's more readable
than DTD)?
>>currently the DTD form is normative - will
add explicit wording

- Page 9. "Topic modules". This is commentary
on the DTDs. The spec should either be complete in itself, or the DTD should
be self documenting. Same comment applies to other similar topics in this
document (especially page 35. "Modularization and integration of design").
>>self-documenting dtds is not a goal of the
spec at this time. parts of the language reference are generated from the
dtds, but that approach is inappropriate for the intent of the architectural
spec.
 
- Page 9. "Topic modules". States that tables are based on the
CALS model. But page 141 of the Language Specification document states
that "the DITA table is based on the OASIS Exchange Table model".
Are these the same thing, and if not, which is correct?
>>They are the same thing. The OASIS Exchange
Table Model is a specific adaptation of the CALS model. 

- Page 25. "Flagging logic".  The spec doesn't state the
purpose of flagging (i.e. that it is intended to highlight elements in
the output). Multiple flagging as described works when images are used,
but not when coloured or bold text is used, and there should be a statement
of the rule in that case. 
>>if a flagging process decides to highlight
elements using color, that process will have to figure out how to handle
multiple flags on its own - the spec will not provide guidance for a use
of the attributes that is not intended.

The rule for combined filtering and flagging is not stated correctly: Filtering
is applied first, and if the element is included, then flagging is applied.
>>this comment assumes filtering and flagging
are happening in separate passes. This may be the case, but separate passes
are not a requirement - filtering winning over flagging is required, which
might be accomplished using two passes, as you suggest, or it might be
accomplished using some other method. The method is immaterial, the rule
is correct as stated.

- General comment. There are many references to XHTML and PDF output in
the Language Specification. If DITA is really bound to these output types,
we should say so. I suspect that it is not, in which case all these references
should be less specific. Maybe the spec should characterise them both without
mentioning them by name! 
>>two of the major outputs currently supported are pdf and html.
While DITA is not bound to just these types, we do have existing implementations
of these types and thus expected processing. As we add output types we
can add documentation for expected output. I'm not sure that making the
language less precise would help in its intended purpose, which is to help
implementers of DITA processes.

Language Specification
- General comment. The specification gives considerable detail on all the
elements, but doesn't describe the relationship between them. For example,
what are the containing and contained elements? We shouldn't rely on the
DTD or Schema as the only specification of this sort of detail.
>>Fixed in latest version

- General comment. The elements used in maps should be separated from those
used in topics. In theory, you could use DITA topics without maps and vice
versa.
>>Fixed in latest version

- alt element. This (and several others) refers to things that are deprecated.
We shouldn't deprecate things in draft 1, we should remove them.
>>This was discussed in the Technical Committee.
Although this is the first draft of DITA as a standard, it already has
a large installed base, and it would be inappropriate to ignore existing
users of DITA simply because they adopted it prior to standardization.
Hence the decision to include deprecation for one release instead of simply
rendering all current DITA topics invalid.

- anchor element and elsewhere. "It is currently
supported by Eclipse output only". We shouldn't bind the spec to a
specific output that is supported in a specific implementation.
>>This is a statement about current support
at the time of writing the spec. It does not bind the spec to that implementation,
it reports on status. If PDF or HTMLHelp ever provide runtime integration
of navigation/TOC, we can update the transforms to take advantage - in
the meantime we need to make sure that people are aware of the implications
of using the element.

- author element and elsewhere. "The currently unsupported keyref
attribute ...". If it's not part of the spec but will be in future,
then it should say "reserved for future use" and nothing else.
If it's just that a particular implementation (i.e. IBM's) does not support
it, it should be specified in full. The present wording exposes the spec
to different interpretation by different implementers.
>>True. We will need to provide a full description
of keyref in future releases.

- coords element. "Pixels are recommended ..." and following
note. This is implementation detail which should be removed.
>>This reflects the sometimes dual nature of the language specification,
primarily supporting implementers but secondarily supporting users. 

- draft-comment element. "Note: ..".  This
is placing an obligation on the processing system. There are other obligations
expressed elsewhere. There should be a statement in the Architectural Specification
that makes it clear that while some details are up to the implementation,
there are certain things that processing systems must do.
>>When the word "must" is used it is binding on the processing
system; when wording such as "suggested" or "recommended"
is used, it is not binding on the processing system.

- example element. Remove the comparison with IBMIDDOC.
>>Removed

- fig element. "Sometimes called an 'exhibit' ". Delete this,
as it doesn't add value.
>>Retained, will consider for future version.

- fig element. "A title is placed...". Delete this sentence -
it is redundant.
>>Retained. Not redundant, explains how the optional title is implemented.

- i element. " .. this may vary ...". If
this is a typographic element, italic should mean italic. I understand
why other elements are not  tightly coupled to the presentation, but
this (and b and u) should be.
>>We aren't making this binding on the processing system because
not every system supports italics. For example, when text is used in flyover
help for a link preview, fonts are not available.

- image element. "always include a description
of the image's content in the alt attribute". But when we describe
the alt element we state that the alt attribute is deprecated. In any case,
this is more a direction to the user than a specification.
>>Fixed to refer to alt element. Again, supporting
dual usage: primary implementers, secondary users.

- indextermref element. If this is not currently supported, and might be
deprecated in the future, should it be included at all?
>>Because it might not be deprecated. Depends
on implementation of keyref. Will resolve in future version.

- keyword element. Last paragraph is implementation detail that doesn't
belong in the spec.
>>Implementation details are intended to help implementers in processing
content consistently for a particular output, and to help users understand
the implications of a particular element choice. Retaining.

- li element. The important point is not that output
is displayed with number and alpha in the one case and bullets in the other,
but that the list is presented in a way that indicates that the sequence
is (or is not) important.
>>See implementation details above.

- lines element. Description should be independent
of the description of the pre element.
>>Will consider for future version.

- map element. Delete the description of Eclipse requirement
as it's not part of the DITA spec.
>>See above re implementation details and re
anchor. Retaining.

- mapref element is missing - as this is planned for future and provides
an elegant way of imbedding maps within maps, it should be included.
>>The mapref element is not part of the spec.
A number of elements were proposed to the TC and the decision on whether
to include them has been delayed until post 1.0. The mapref element is
one of them.

- note element. The type attribute says that othertype needs a stylesheet
otherwise the note is ignored. This is not true for the IDWB, so why should
it be the case for other implementations?
>>Typically it's to avoid having translatable
content in an attribute. 

- othermeta element. " .. and have no defined meaning for other possible
outputs such as PDF."  Who knows what PDF might support in the
future, or what future output there might be. 
>>Yep, just making that explicit.

- pre element. ".. and also presents the content in a monospaced type
font (depending on your output formatting processor)". Monospace output
should be mandatory (see my comment for the i element).
>>See previous response.

- related-links element. Processing note 1. This should be for the processor
implementation to decide.
>>current wording is not binding. 

- required-cleanup element. The note is a good example of how the processing
requirements should be expressed. But we need a definition of a DITA processor
in the Architectural specification.
>>that's because this particular requirement
is binding. In a future version it sounds like we need to distinguish normative/non-normative
sections more clearly. Future version may also try to pin down what a DITA
processor is, to speak more clearly to eg editor requirements versus translation
pipeline requirements etc. That work is outside of scope for the current
spec, but would be valuable for future versions.

- screen element. The example output in its present form really undersells
the value of this element. I suspect that the screen element may not have
been used to produce it.
>>support for the screen element outside of
IBM's internal processes is spotty. Examples will be updated in future
versions when more complete support is available.

- shape element. Delete the reference to the failings of the various browsers.
>>Will delete.

- shortdesc element. The second sentence is really the crucial point of
shortdesc. The spec should spell out the obligations for DITA processors.
>>Both sentences are equally important. Obligations
for DITA processors are pretty slim here though. They are not required
to provide link previews for example.

- table element. Note on the scale attribute. The reference to "legacy
purposes" isn't appropriate. This attribute should be supported or
deprecated. " .. use the scale attribute judiciously ..." should
be replaced with specific advice.
>>It is supported, it is not deprecated in the formal sense of being
removed next release. The current wording is accurate, and incorporated
per TC direction.

- term element. "In future development of DITA
...". There should be some indication of how this might work, and
any attributes that are needed should be reserved. Otherwise, we will find
that someone implements this in a way that conflicts with the intended
processing.
>>Design work not done in time for this release.

- tm element. "In your company's documents ..". The spec should
describe what the DITA processing is obliged to do with the element.
>>Company-specific rules and implications removed,
softened wording to "may" to allow for variation in use.

- tt element. This is a poor choice of name for this element. Although
the venerable Teletype is worth commemorating, this is not the place to
do it. Use a name which says what it does - I suggest monospace.
>>as with many elements in DITA, existing element
names taken from html. 

- tutorialinfo element. "This information is currently included ...".
Only if the processor elects to do so. 
"It is not for use in tasks that are being used outside of tutorials".
This statement doesn't tally with the concept of reusable topics. A task
doesn't "know" where it is being used. Which means that authors
will have to provide two copies of the topic - one containing the tutorialinfo
elements, and one with the elements excluded.
>>wording updated.

- var element. "It is represented in output in italic font".
This depends upon the output processors, and the user's style rules.
>>future version will make normative/non-normative
more clear.

- outputclass attribute on all elements. Refers to CSS processing. Does
DITA support the use of XSL for stylesheets?
>>DITA uses XSL to produce HTML. On output to html, the outputclass
attribute value is added to the html class value, for use by CSS stylesheets
for the html. Wording has been updated.

- %display-atts; and elsewhere. Refers to the contents of the DTD. But
we state in the Architectural Specification that DITA can be specified
in Schema as well. These topics should specify the attributes independently
of the whether Schema or DTD is used.
>>updated wording

- %display-atts; "In DITA tables, in place of the expanse, ...".
Why use two different attributes to denote the same thing? And I suggest
using meaningful values rather than 1 and 0.
>>value change is to be conformant with oasis exchange table model


Reviewer Two

One small detail I noticed - in the architecture specification on pages
24 and 25 (the processed version of p24's example) there's the phrase

<li platform="Windows">Do a special thing for Windows</li>

I don't see a trademark attribution of any kind. Is this a potential concern?
I don't know if MS have any involvement with the OASIS group, but I might
suggest substituting "Linux" as more suitable in this context.
>>Will update

Also, I notice that there's no explanation of why the name "Darwin
Information Typing Architecture" was chosen. I think it is worth adding
some explanation of this (invented if necessary... do we have an IBM site
in Darwin, Aus.?).

It is not correct to assume that associating something with Darwinism (which
is the default if no explanation is given) will have the effect for all
readers of increasing its approval rating or conveying the meanings of
"scientific, clever", especially in the USA. My feeling, based
on both my personal standpoint and my reading around this issue, is that
this association has the potential to make some readers uncomfortable,
or to make some readers interpret it as a statement of positioning or worldview.
I think to help avoid any association with what is a known issue of controversy,
an explicit explanation should be given of why this name was chosen.

>>Will consider adding explanation of name in
future release. For what it's worth, the use is directly related to Darwin's
theory of evolution and its logical match with our use of specialization
and inheritance. 

Reviewer Three

I believe the 'purity' of DITA is not as clear as it should or could be.
The use of <b> and <i> elements is clearly indicating the style
that the content should be displayed as rather than perhaps using <strong>
and <emphasis>. The committee has the opportunity to correct this
in release 1 of the specification. While it might be seen that there is
little semantic difference between <b> and <strong>, the temptation
could be that as there is a precedent, other elements of a similar ilk
could be introduced to the specification.

>>The choice of typographically named elements
was deliberate, and part of the overall strategy of modularization and
specialization. IE, if you don't like typographic elements, get rid of
the module, and provide more semantically specific elements. I personally
don't see that <em> and <strong> are semantically distinguisable,
whereas <i> and <b> are quite clear.


Attributes should not contain 'free text'. For example the navtitle attribute
on the <topicref> element. The function of an attribute is to help
define the quality or characteristic of the object. The navtitle in this
case is an object in its own right and should become an element that is
nested in the topicref element. Having attributes that contain free text
places severe limitations and maintenance issues on the information in
those attributes. For example, a product name would have to be manually
maintained rather than being handled as a conref'd keyword.

>>You can use linktext as a fall back in this
case. Future versions of DITA will look at translatable text in attributes
in general.


Inability to nest <keywords>. This is just an unnecessary limitation
on this element. Using the keyword element with an id and conrefing to
it is effectively the methodology for handling text entities. While there
are work arounds for not being able to nest them, there is a maintenance
overhead that is introduced and is unnecessary. For example:

Where you are looking to create compound elements to handle such things
as product name and version or product name and platform or some other
variation, you will need to use individual keyword definitions for each
variation. For example you will not be able to the following:

<p><keyword id="pname">DITA Product</keyword></p>
<p><keyword id="pname11x"><keyword conref="common.dita#common/pname"></keyword>
1.1</keyword></p>
<p><keyword id="instdir">C:\Program Files\IBM\<keyword
conref="common.dita#common/pname11x"></keyword></keyword></p>

The first keyword element is valid, but the second and third are not as
you cannot nest a keyword element within another. Although this is possible
with <ph> elements, you cannot insert <ph> elements in all
the locations that you will need to place a conref to the source data.
The following approach can be used but means that each 'entity' would need
updating in the case of a name change:

<p><keyword id="pname">DITA Product</keyword></p>
<p><keyword id="pname11x">DITA Product 1.1</keyword></p>
<p><keyword id="instdir">C:\Program Files\IBM\DITA
Product</keyword></p>

>>This proposal was reviewed by the TC and a
decision deferred to a future version of DITA

Currently the prereq elements come first followed by the context elements
in Task topics. This would mean that you are reading what the prerequisites
of the task are, before you actually have read and understood in what context
you are actually performing the task. Reversing the order of these elements
(or perhaps allowing them in either order to get around the issue of those
topics already written as such) would mean that you would read and (hopefully!)
understand the context of the task at hand before looking at anything you
might need to do.

>>You are ignoring the shortdesc. The title
and shortdesc should provide enough information prior to prereqs to allow
the user to make a decision about whether to proceed. context is for additional
information they need to know before starting the task.

Architectural Specification
- Page 15 of the DITA Architectural Specification. Chapter 3. Figure 1
and Figure 2 both have in the comments A linking to A1, A2, A3 as children,
but unless I am mistaken, A3 does not appear in either of the examples.
In the second example it looks as though "(no links to B as previous)"
needs to be the third line against A2 as it is for A1.
>>removed A3; second example is correct, no
previous link to B would be generated in any case since A1 is actually
the previous topic


- Page 16 as above. navtitle should ++NOT++ be an attribute. It should
be an element in its own right as it is in the topic.

>>will be considered for future version, see
above.

- Page 17 as above. In the example of a simple relationship table, in the
relrow, the second and third cells are missing an opening relcell element.
>>Fixed.

- Page 20 as above. In the Identity attribute section, first bullet point,
3rd paragraph, 3rd line. There is a space missing between the web address
and URIs. (Actually between the '.' at the end of the address and URIs).
>>Fixed.

- Page 21 as above. In the Content reference attribute section, please
re-write paragraphs 3 and 4 (starting More formally... and If the referenced....)
in to something understandable.  You have made it sound far more complex
than it actually is. I have users avoiding using it, because it has been
made to sound complex and yet is one of the easiest approaches to use in
relation to reuse.

>>This is not primarily a users document, it
is primarily an implementers document. The architectural spec even more
so than the language spec. I have not made it sound more complex than it
actually is for implementers. Ask an implementer if you don't believe me.

- page 24 as above. In the section Using metadata attributes. Is it right
to refer to these attributes as metadata attributes? Are they not just
'attributes'? Same questions as for Processing metadata attributes.
>>Need to distinguish these attributes from others. I believe product,
platform, audience and otherprops all have equivalent element structures
in the metadata structure of the prolog, which makes calling them metadata
attributes defensible.


- general. Better information and examples of relationship tables should
be provided.
>>Added more explanation to language spec, may be further enhanced
in future versions.

Language Specification
- b element. Should not be in DITA. Should be a <strong> element.
>>See above.

- boolean. If it is deprecated, remove it. This is a first release. If
people are using it, then they will have to adapt to it going at some point,
so why not make it the first proper release of the spec etc.?
>>See above.

- general comment. Try not to split example 'code' over a page. Example
chdesc on page 9. The example is split on the opposite side of the same
piece of paper! Would make it easier to read. 
>>Will consider in future version - unfortunately
not yet much support for keep-together style instructions to the print
formatter.

- colspec. The colspec example on page 21 seems to have lost some of its
formatting
>>Fixed

- created. Why is the date an attribute? Not sure it makes sense. Applies
to revised element as well.
>>To allow better data-typing in schemas.

- entry. I believe that the entry element would benefit from an id and
conref attribute
>>Attributes are there, failure in docs. Will add.

- i element. Should not be in DITA. Should be an <emphasis>
element.
>>See above.

- keyword. The explanation of this could be better. My understanding is
that something identified as keyword only has the semantic attachment that
the author wishes to give it. The current write up seems to indicate it
is more than this. I would resist the temptation to use the examples in
there such as name of a command or parameter as these should have (command
does) elements in their own right. It implies that it might need to be
in an enumerated list. The use of keyword was expanded to allow it to be
used as a text entity replacement. The description gives me an indication
that it has more semantic value than we have been lead to believe and this
would then lead me to question its use as a text entity replacement. Of
all the descriptions this one might need the most work to ensure that it
does not have too much information (or too little) that takes it away from
my understanding of its intended use. I've just checked with one of our
US DITA tooling experts and he agrees !
 that my understanding that it only has the semantic meaning the author
wishes it to have is his as well. In fact, if used as a text entity, it
can effectively have no semantic meaning and is just the mechanism for
working with common information.
Suggest that "or<indexterm." is removed from the third paragraph
as it is unnecessary and makes it clearer that only a keyword element in
a keywords element will appear in metadata.

>>Updated description.

- keyword. Should be able to nest itself.

>>Proposal considered by TC, decision deferred
to future version.

- ph. Says "is used to organise content for reuse...".
This is not the best element for this as it cannot be nested in a number
of places reusable information is required. My understanding is that this
is the keyword element. Perhaps that should be updated to reflect this
comment?

>>Both elements are appropriate for reuse, in
different contexts. Description of keyword updated to reflect this.

- propdeschd, proptypehd, propvaluehd. As this is probably written in DITA
and as the information is probably common, put the relevant information
in each section and save people having to turn the page to look at the
attributes for property. You could even set up and id and conref for the
relevant information. :-)

>>Updated. For what it's worth all the attribute
descriptions are happening via conref anyway.

- repsep. No example code.
>>Will address in future version.

- shortdesc. Description needs enhancing so that it states where the shortdesc
information appears. i.e. hoverhelp, start of a topic, short description
with the topic title as a link.
>>Will address in future version. 

- sub, sup elements. Bit like i and b elements. Should they be there or
emphasis and strong versions of sub and sup?
>>See above.

- tt. Should be something else. Very legacy! :-)
>See above.

- u. as fro b, i, sub and sup.
>See above


Michael Priestley
mpriestl@ca.ibm.com