OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: comments on spec - summary of responses

Michael Priestley


Title: DITA Review Results

DITA Review Results

Results of public review of DITA Technical Committee Specification Committee Draft

comments on language reference

Table 1. Language Specification comments
Issue Resolution
Various editorial changes to Language Specification:

- rewrite id descrip (currently using descrip for other ids)
- provide contrast with conref on a map element

- delete ref to imagemap - will be covered by standard links

- in href description, change "typically" to "for example"

- change "tag" to "element"

- rewrite example (currently showing empty category element with use of select-atts)

- delete substeps from example (obscures choicetable, and also most steps would not include both)

- delete extra lines from example

- 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.

- delete ref to imagemap (can get there indirectly via contained by links)

- in year descrip, delete citation - YYYY as format is self-explanatory

- say "presented flush left" rather than "is"
- update formatting in example to start new elemens on new line

- delete exclamation mark, turn note into normal paragraph

- shorten example and fix typo (extention)

- remove reference to IBMIDDOC
- delete example, since it's primarily talking about things other than examples.

- change document to topic

- fix spacing in example

- main desc, change ref to alt attribute to alt element (alt attribute deprecated)
- alt attribute, deprecate and recommend alt element
- longdescref, add syntax example

- change "examples" to singular

- make description specific to indexterm (not keyword as well)
- update keyref description to describe intended use (adds current indexterm under referenced target)

- 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?

- make description specific to keyword (delete indexterm discussion)

- 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)

- chg example to set collection-type="sequence" and give a more descriptive title

- 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

- 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

- 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

- 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

- delete "or to show any choice..."
- chg "may show" to "shows" (the output processor must provide the connecting chars)

- example: add closing tag

- contrast with conref for build-time integration, per anchor above
- example: delete the topicref

- delete "or needs stated..."

- make clear it's only in use by syntax diagrams
- delete example

- 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?

- 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

- chg "computer parameters" to "command or interface parameters"

- chg example to show env as a param of config, rather than an object operated on by config

- update example to use synph rather than codeblock, and use standard format for output and input

- delete "future"
- say "create semantic markup" rather than "apply specific processing"

- same as for pd

- add warning to use more semantic elems when avail (eg codeblock)

- clarify processing of prereq links, or link to explanation in "related-links"

- delete "more about this element"
- example: delete plural, delete extraneous " in headings, add source

propdeschd, proptypehd, propvaluehd
- say same as stentry rather than property

- example: remove doctype, <?xml

- same as refbody
- chg atts per concept

- same as refbody

- 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

- make clear it only applies within syntaxdiagram

- 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"

- example: correct formatting

- make clear it's part of syntaxdiagram

- example: delete extraneous first line, delete ref to imagemap

- delete "DITA insight" label, turn content into normal paragraph,

- define as simple list, describe output per descrip in sli

- href: correct descrip and examples

name: correct to "the name of the property whose state is being described"
value: the state of the property identified by name

- delete "for example" since forms typically do have a tab sequence

- delete "like a row..." since it is a row

- example: delete "Note:" text since typically that would be provided by a note element if needed

- delete "for example.. uicontrol" - example works for bold but not others

- example: fix formatting

- 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

- example: fix formatting

- 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

- chg atts per concept

- chg "represent" to "may have or require"

- valign: chg "table entry (cell)" to "table footer (tfoot)"

- chg document to topic, rewrite as necessary

- add that when titlealts absent, title gets used for everything
- example: swap values of title and navtitle (navtitle typically shorter)

- delete first sentence of "Remember", change remainder into normal para, chg "must be" to "may be"
- tmclass: delete ibmisms

- chg id, other atts per concept

- chg "topic's children" to "topic's children within the map"

- 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

- navtitle is required
- update other atts per topicref

- update atts per topicref

- in descrip, use appropriate example, eg codeph rather than uicontrol

- 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)

- chg "represents" to "identifies text that is the name of"
- clarify for example to describe cascade of menu choices

- delete "possibly within a message or API...". we do not have markup for environment variable names, using varname would be inappropriate

- chg "represents" to "identifies text that is the title of a window" etc.

- 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)

- xmlns shdn't be here

- conref: update examples - delete last one, add elementid to second one
- consolidate descrip before atts
- delete "not all these capabilities.."

- 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

- 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..."

- 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

- update per topicref-atts

- 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

content reference to fragments

Table 2. Architectural Specification
Issue Response
unclear guidance on conref to elements in fragments clarified conref description to make it clear that topic containment is necessary.

usage of keyword unclear

Table 3. Language Specification
Issue Resolution
keyword in prolog behaves differently from keyword in body clarified semantic purpose and usage of keyword with new description

specialization ancestry missing

Table 4. Language Specification
Issue Resolution
hard to determine specialization ancestry from the spec added inheritance section to every element description

containment info missing

Table 5. Language Specification
Issue Resolution
hard to determine containment info from the spec added contains and contained by sections to every element description

typos in committee drafts

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

typo in schemas

Table 8. Schema Specification
Issue Resolution
entry in table only allowing text, should allow standard list of elements fixed schema, entry in table now allows same list of elements as in dtd

unwieldy otherprops


Table 9. Architectural Specification
Issue Resolution
otherprops is an unwieldy way to author metadata attributes logged requirement for future version, documented workaround in "limits of specialization" topic
when you link to something that has been filtered out, the link should disappear you can use dita maps to express both the property on the target and the relationship to the target, so both get removed at the same time.

multiple review comments


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 comments

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.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]