Create elements for text attributes with translatable text.
Longer description
The problem: There
are several attributes in DITA that are meant to hold free text. There is
no way to reuse the values inside these attributes, or to make use of common
text inside the attributes. For example, the navtitle attribute on topicrefs
often contains reusable text such as product names, but this common text must
be entered in every attribute.
In addition, translation vendors have
expressed reservations about including translatable text in attributes. Tools
have to be programmed to recognize these attributes, and traditional values
such as xml:lang and the translate attribute do not combine easily with attributes
on the same element.
The solution: Add elements for each of the
text attributes, and deprecate the use of the attributes.
Note: This requirement was partially completed in DITA 1.1, which
included the <title> element in maps while deprecating the title attribute
on <map>.
Statement of Requirement
Translatable content
that appears in attributes should be expressible as element content, for the
following reasons:
- Ease of use for authoring - in many XML editors it is more difficult or
time consuming to edit attributes than to insert content in an element.
- Reuse of content - these attributes may contain reusable phrases, but
it is not possible to use conref inside an attribute.
- Difficulty of providing language or translation information - with an
element, it becomes possible to specify xml:lang, as well as the dir and translate
attributes, for the content.
- Easier adoption by translation tools - tools will not need to be specially
programed to recognize translatable attributes.
Use Cases
- An author creates a topichead element in the map. The topichead includes
a phrase that is reused elsewhere with conref (such as a product name). If
this phrase is in the navtitle attribute, the author must make a copy of the
phrase in this location. With the navigation title in an element, any portion
of the title may be reused.
- A translation tool wishes to support DITA. Default settings in many translation
tools assume that attributes do not contain real content and should not be
translated. If these translatable attributes are replaced with elements, the
tools will be able to support DITA more easily.
- The title of a topichead element should not be translated. If the title
can be specified in an element, the translate attribute can be used on that
element without setting an undesired value for children of the topichead.
Scope
Medium. Design is relatively simple.
Tools must be updated to be aware of the new elements. Tools may wish to warn
users about deprecated attributes.
Technical Requirements
There will be changes
to the DTDs, Schemas, and to processing. Changes to the DTD and Schemas will
be relatively minor. Changes to processing will be more complicated.
The
following attributes are candidates to be updated:
- reltable/@title: Add the title element as an optional first child of <reltable>.
Note that this typically is used for reference and does not generate any sort
of output.
- topicref/@navtitle: Add <navtitle> as an optional first child of <topicmeta>.
The new navtitle element would have the same content model as the title element.
When both the navtitle attribute and element are specified, the element should
be used.
Note: The navtitle attribute would no longer be required on topichead.
We cannot replace it with a required navtitle element, so it would be up to
processors to ensure that a title is specified for topichead.
Note: We
will need to specifically call out situations where navtitle has no defined
purpose or should not be used, such as on map, topicgroup, frontmatter,
or backmatter. Processors could optionally generate a warning when navtitle
is used in these locations.
- lq/@reftitle: This has the same semantic as the <cite> element, which
is already a child of <lq>. Rather than introduce a new element, we should
document that a <cite> in <lq> is the same as @reftitle. Processors
may optionally use the href attribute to turn a final <cite> into a link.
- object/@standby: Add <standby> as an optional child of <object>.
The content model should be updated from (desc?, param*) to (desc?, standby?,
param*).
Note: With the recent work on the @href/@format/@scope/@type requirement,
we decided not to modify object so that it maintained compatibility with its
HTML roots. Should the same thing apply here, or do the translation concerns
overrule that?
Previous versions of this proposal also suggested new version, release,
and modification elements within <vrm> to replace the equivalent attribute
values. However, the specification indicates that these attributes expect
to take simple numbers (such as 3) rather than translatable text (such as
Version 3). So, I have left that out of this proposal.
New or Changed Specification Language
Update
the language specification to add the new elements and contexts.
Update
the language specification to deprecate the old attributes.
Update the
architectural specification page that lists translatable elements and attributes.
Costs
Small amount of time to update the
DTDs, Schemas, and specifications.
Tools must be updated to recognize
and work with the new elements.
Benefits
- Less duplication of content when reusable text is needed in these contexts
- Usability enhancements for editors where it is not easy to edit attributes
- Easier to adapt translation tools to work with DITA