DITA Review Results
Results of public review of DITA Technical Committee Specification
Committee Draft
comments on language referencehttp://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200503/msg00007.html
Table 1. Language Specification comments| Issue |
Resolution |
|---|
| Various editorial changes to Language Specification: anchor:
- rewrite id descrip (currently using descrip for other ids)
- provide contrast with conref on a map element
area
- delete ref to imagemap - will be covered by standard links
author
- in href description, change "typically" to "for example"
b
- change "tag" to "element"
category:
- rewrite example (currently showing empty category element with use of select-atts)
choicetable:
- delete substeps from example (obscures choicetable, and also most steps would not include both)
chrow:
- delete extra lines from example
conbody:
- create new example. current example talks about sgml entities, which is likely to cause confusion since dita deprecates entity use
concept (or topic, and then refer to topic):
- correct conref attribute description - filename without id points to first topic; file name with id points to specific topic
- change id description to say "target for href and conref atts" rather than listing linking elements
- ditaarchversion: chg dtd to architecture
- delete <example> section in the example - it doesn't actually contain an example.
coords
- delete ref to imagemap (can get there indirectly via contained by links)
copyryear
- in year descrip, delete citation - YYYY as format is self-explanatory
dl
- say "presented flush left" rather than "is"
- update formatting in example to start new elemens on new line
draft-comment
- delete exclamation mark, turn note into normal paragraph
dt
- shorten example and fix typo (extention)
example
- remove reference to IBMIDDOC
- delete example, since it's primarily talking about things other than examples.
featnum
- change document to topic
groupchoice
- fix spacing in example
image
- main desc, change ref to alt attribute to alt element (alt attribute deprecated)
- alt attribute, deprecate and recommend alt element
- longdescref, add syntax example
imagemap
- change "examples" to singular
indexterm
- make description specific to indexterm (not keyword as well)
- update keyref description to describe intended use (adds current indexterm under referenced target)
indextermref
- delete note (none of the indexing is supported under the current public processing, and the functionality of indextermref is not in fact equivalent to keyref on indexterm - may be equiv to conref)
- do we want to say this is deprecated in favour of indexterm with conref?
keyword
- make description specific to keyword (delete indexterm discussion)
link
- remove reference to sort orders (no attributes for determining sort keys)
- expand href description to cover full syntax (same file, first in different file, specific in different file)
- change format description to say allowable values "include" rather than "are"
- chg format description from saying "mapref" to "ditamap" as a value
- chg format description final bullet to be a suggestion rather than a rule
- chg scope description to use bullets
- chg query description to remove references to topicref
- chg example to use linkgroup rather than linklist (the current example shows the kind of structure that is currently generated from linkgroup)
linkinfo
- chg example to set collection-type="sequence" and give a more descriptive title
linklist
- chg description to remove ambiguity (currently reads as if linkpool is used by the processor as a sorting mechanism)
- collection-type: remove list of allowable values, which is duplicated in the data type column
- duplicates: defaults to yes for linklist. update descrip and value fields
- format and scope as per link
- delete example, which currently shows manual tags for what gets generated for free
linkpool
- clarify descrip - links are sorted together if they aren't in a linklist
- clarify descrip per linklist
- collection-type per linklist
- duplicates: defaults to no for linkpool, can't be changed. update descrip.
- mapkeyref: chg refs to linklist to linkpool
- example: delete collection-type, delete linktext from example
lq
- delete future dita considerations
- href: delete "see keyref" reference, delete example which is wrong
- type: doc as-is, but add to issues for 1.1 - use of type is inconsistent with linking elsewhere
- reftitle: doc as-is, but should allow text in an element instead for translation purposes. consider making a specialized xref element inside lq instead of atts on the elem itself
map
- update descrip to make clear that it can organize other resources besides topics, using tables/hierarchies/groups
- correct caps on att name "Title"
- clarify description of Eclipse behavior (title always required for eclipse output, used as toc label)
- id: chg "is only used" to "may be used"
- anchorref: clarify - used for runtime integration only
- ditaarchversion: version of architecture, not dtd
menucascade
- delete "or to show any choice..."
- chg "may show" to "shows" (the output processor must provide the connecting chars)
msgblock
- example: add closing tag
navref
- contrast with conref for build-time integration, per anchor above
- example: delete the topicref
navtitle
- delete "or needs stated..."
option
- make clear it's only in use by syntax diagrams
- delete example
othermeta
- name: correct descrip (shd be name of the metadata property)
- translate-content: doc as-is, but add to issues for 1.1 - why not just @translate?
param
- name: shd be name of the parameter
- id: shd be id of the parameter
- doc as-is, but why no conref?
- value-type: add bullets
parml
- chg "computer parameters" to "command or interface parameters"
parmname
- chg example to show env as a param of config, rather than an object operated on by config
pd
- update example to use synph rather than codeblock, and use standard format for output and input
ph
- delete "future"
- say "create semantic markup" rather than "apply specific processing"
plentry
- same as for pd
pre
- add warning to use more semantic elems when avail (eg codeblock)
prereq
- clarify processing of prereq links, or link to explanation in "related-links"
prophead
- delete "more about this element"
- example: delete plural, delete extraneous " in headings, add source
propdeschd, proptypehd, propvaluehd
- say same as stentry rather than property
refbody
- example: remove doctype, <?xml
reference
- same as refbody
- chg atts per concept
refsyn
- same as refbody
related-links
- processing notes: chg "pdf output ignores" to "typically ignores" and add note that it may include child links to create chapter summaries
- processing notes: get rid of italics on att names
- format, scope: chg per link
relcell, relrow, relcolspec, reltable
- example: consolidate in reltable only, add description of links added for output
repsep
- make clear it only applies within syntaxdiagram
resourceid
- in last sentence of descrip, chg "or" to "and"
- remove italics from att names
- id: correct descrip - shd be "a value used by an app to identify the topic"
- appname: correct descrip - shd be "the app that requires the id"
- example: switch id and appname values, make the appname "dbaccess"
screen
- example: correct formatting
sep
- make clear it's part of syntaxdiagram
shape
- example: delete extraneous first line, delete ref to imagemap
simpletable
- delete "DITA insight" label, turn content into normal paragraph,
sl
- define as simple list, describe output per descrip in sli
source
- href: correct descrip and examples
state
name: correct to "the name of the property whose state is being described"
value: the state of the property identified by name
steps-unordered
- delete "for example" since forms typically do have a tab sequence
strow
- delete "like a row..." since it is a row
substeps
- example: delete "Note:" text since typically that would be provided by a note element if needed
sup
- delete "for example.. uicontrol" - example works for bold but not others
synblk
- example: fix formatting
synnoteref
- chg "elsewhere in the topic" to "elsewhere in the document"
- href: current descrip is wrong, need confirmation of correct syntax.
- example: shd show correct syntax, needs confirmation
synph
- example: fix formatting
table
- where it mentions expanse in the descrip, spell out as "the expanse attribute available on other dita elements"
- fix ref to display-atts - doesn't use expanse, uses pgwide
task
- chg atts per concept
term
- chg "represent" to "may have or require"
tfoot
- valign: chg "table entry (cell)" to "table footer (tfoot)"
title
- chg document to topic, rewrite as necessary
titlealts
- add that when titlealts absent, title gets used for everything
- example: swap values of title and navtitle (navtitle typically shorter)
tm
- delete first sentence of "Remember", change remainder into normal para, chg "must be" to "may be"
- tmclass: delete ibmisms
topic
- chg id, other atts per concept
topicmeta
- chg "topic's children" to "topic's children within the map"
topicref
- chg "designates" to "identifies"
- make clear topicrefs can point to other resources besides topics
- id: currently wrong, chg to talk about eg conref use
- href: rewrite, provide examples
- query: chg "topicref" to "the target"
- conref: add descrip
- scope: att and descrip are missing, shd probably be in topicref-atts
- copy-to: recommend providing title and shortdesc for copies using topicmeta
topichead
- navtitle is required
- update other atts per topicref
topicgroup
- update atts per topicref
tt
- in descrip, use appropriate example, eg codeph rather than uicontrol
tutorialinfo
- ok to use outside of tutorials, but processor should suppress outside of tutorials (not currently doing so, but that's a bug, not according to spec)
uicontrol
- chg "represents" to "identifies text that is the name of"
- clarify for example to describe cascade of menu choices
varname
- delete "possibly within a message or API...". we do not have markup for environment variable names, using varname would be inappropriate
wintitle
- chg "represents" to "identifies text that is the title of a window" etc.
xref
- add descrip of desc usage (shd be turned into flyover help, like desc for link)
- rewrite to provide enumeration of potential scopes and formats
- chg descrip of href to say "provides the location of the target"
- clarify warning against using xref, also mention map-based linking
- href: rewrite to provide appropriate list of href syntaxes
- type: chg "allowed values are" to "possible values include"
- delete "other" as type value
- chg note for href to talk about what other values can be used for, and when override processing will be required
- update format per previous edits
- update examples to use .dita for consistency (makes it clear when the target is actually dita)
%global-atts
- xmlns shdn't be here
%id-atts
- conref: update examples - delete last one, add elementid to second one
- consolidate descrip before atts
- delete "not all these capabilities.."
%rel-atts
- type: ensure type list is appropriate wherever referenced, update per xref or link as appropriate
- role: getting rid of deprecated values shd be priority for 1.1
- scope shd probably be part of this list
%select-atts
- importance: delete property att info - it is not used for conditional processing. also delete listed values, since dup of data type cell
- status: delete list of values, and property att info, same reasons as importance
- status: add list of allowed values to data type cell
- delete "not all these capabilities..."
%topicref-atts
- collection-type: delete value list from descrip field
- type: list is wrong, create appropriate list for topicref
- format: update per link
- linking: chg "topic" to "topic's current location in the map"
- chunk: add descrip
%topicref-atts-no-toc
- update per topicref-atts
appendix
- delete appendix; is either forecasting future functionality, or duplicating content in arch spec or in other specs
|
Made changes |
| Reorganize by module |
Reorganized, including additional categories within
topic, eg related links elements, table elements etc. |
| eliminate attribute lists when duplicate of ancestor,
and just link to ancestor |
Did not eliminate; instead ensured existing attribute
list format was implemented consistently |
| when same example used for whole branch of elements,
include example at root element level only, link there from others |
Applied change to major example groupings such as table
and parml, but not to every example |
| when examples show both source and output, shd be standard
for which comes first (I'll suggest source) |
Reworked examples to always show source first |
| link to atts when common rather than repeating |
Factored out common descriptions for class, outputclass,
and xml:space |
typos in committee draftshttp://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200503/msg00002.html
Table 6. Language Specification| Issue |
Resolution |
|---|
| typo in title: committee draft missing t in committee |
fixed typo |
| table description missing pgwide, char, charoff attribute
descriptions |
added descriptions |
Table 7. Architectural Specification| Issue |
Resolution |
|---|
| typo in title: committee draft missing t in committee |
fixed typo |
multiple review commentshttp://lists.oasis-open.org/archives/dita-comment/200503/msg00003.html
http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200503/msg00091.html
Table 10. Architectural
Specification| Issue |
Resolution |
|---|
| - 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. |
| 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. |
| 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 distinguishable, 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. |
| 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. |
Table 11. Language Specification| Issue |
Resolution |
|---|
| 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. |
| 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 |
| 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. |
| 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 |
| 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 Suggest that "or |
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 |
collected commentshttp://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200503/msg00094.html
Table 12. Architectural Specification| Issue |
Resolution |
|---|
| Correction. On page 11, we noted that the example element
at the left margin is missing a closing bracket (>). |
Good catch - will fix. |
Table 13. Language Specification| Issue |
Resolution |
|---|
| 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. |
| 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. |
| |
|
|