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 about DITA A-Z article

Overall, as with Tom, I like the tone and it seems to catch all the updates. I've noted some factual errors that should be corrected / clarified, along with a couple of typos that should probably be fixed.

Accessibility markup for tables
This one worries me - I think it's very misleading. It implies that tables in DITA prior to 1.3 are not or cannot be accessible. That's simply not true. For example, with the table described, properly marked up tables using DITA 1.0 markup, such as <thead>, can generate perfectly accessible output for screen readers. DITA-OT has done so since day one; this was in fact a pre-requisite for the HTML to be used by IBM, so support was there in DITA-OT 1.0. The new markup is necessary only in the following situations:
* Use of tools that do not create accessible tables based on existing markup - authors can now maintain that by hand.
* Tables with unusual headers, such as a single header cell in the middle of the table, or a header column in the middle of a table (while possible, I've never seen this required by any of my customers in IBM).

I'm not sure how best to convey that in simple language but would be happy to help. I've already had to calm people who heard about this feature and feared they needed DITA 1.3 to produce accessible output, so I think it's important we don't cause more of that.

Branch filtering
Minor comment about this text: "For example, if your topics have information listed in metric and imperial units of measure, you can now easily generate tailored publications from a single map instead of having two separate maps or ..."

As described, that can be done today (gnerate multiple publications from a single map). The key with branch filtering is that you can generate both sets of tailored information in a single publication. Maybe something like this?
"For example, if your topics have information listed in metric and imperial units of measure, you can now easily generate tailored versions of the information within a single publication instead of having two separate maps or ..."

Context-Sensitive Help
I think there is a minor factual error in this: "Positional information for a particular target display can be set using the new <ux-window> element within the topicmeta of a map or as an attribute within a topic."

Positional information can be set using <ux-window>, and then *referenced by* an attribute (on <resourceid>) within a topic. It cannot be set within the topic.

I really like the write-up, just have a couple of things:
1. Described as a binary "yes|no" nature -- in fact there are 3 meaningful values (with "printonly"). Not sure if this counts as a binary nature. Maybe better to describe as "The limited set of values (yes, no, or printonly) was too..."?
2. It says @print has been replaced with @deliveryTarget. It hasn't actually been replaced, it's deprecated in favor of @deliveryTarget. I realize this document may want to avoid the technical term deprecated - I just don't want to give people the impression @print is gone and their documents must change to be valid.

Also, if you wanted to add a third limitation -- @print could only be used at the topicref level, @deliveryTarget can be used at any level.

Filtering attributes can be grouped
This one is wrong - you can use audience="administrator programmer" with all versions of DITA. The new groups allow you to subset the attribute. One of those things I expect to be of great utility to a relatively small number of people. Best example I've found, and where we use it in IBM, is on @product -- you can group types of products that are related to your content. For example, something that works on top of 2 databases and 3 different application servers would let you group those within @product --
product="database(A B) appserver(X Y Z)"
The purpose of the groups is to let you filter those independently. If you want to exclude both databases, this content can be filtered out, regardless of what application servers are used.

This is not easy to explain in simple language (it's intended for advanced DITA users). Maybe it's best to explain it by saying - you can now mock up specialized attributes within the DITA 1.0 filtering attributes of audience, platform, product, and otherprops. Backwards compatibility restraints do not let us turn these into specialized attributes. When you have multiple categories of metadata that are really specialized types of audience (or platform or product), this lets you treat those categories as independent attributes while continuing to identify them as an audience (or platform or product).

MathML and SVG
Editing typo, should remove either "for those trying to make" or "in order to make": "... involved repeated trial-and-error for those trying to make in order to make ..."

Sorting element
Very minor thing but looks like an editing typo. Second sentence starts with "So a writer can...". I think this is supposed to be something like "A writer can now..."

Other updates to Individual Elements / Attributes
The third bullet is wrong:
"For many elements, the attribute values @format and @scope—commonly used in links—use the value "ditamap" so that links now point by default to the map rather than to the topic."
I think this is a reference to the new defaults for @format and @scope, but I'm not sure. If that's the case, a better description might be:
"For many elements, the attribute values for @format and @scope--commonly used in links--can now be inferred based on the value of @href. For example, this means that links to a file with a ".html" extension will automatically be treated as links to an HTML file, without the need to set @format."

The eighth bullet is not quite right:
"The <prop> and <revprop> elements can now take the @style attribute, so text selected in a DITAVAL file can be set to bold, italics, or any other style property."
The @style attribute was present when prop/revprop were defined in 1.1. The change in 1.2 is that you can now type in any value (or multiple values); previously, it was limited to a few.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)

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