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: Some additional post-1.0 issues

keyref architecture:
The keyref attribute is intended to provide a key-based referencing scheme, with a level of indirection to allow for remapping of targets when content is reused in contexts where the target is unavailable. The keyref attribute is described in some detail in the language specification, but the mechanics of its processing, and of the indirection layer, are not yet defined.

shortdesc (expand):
Sometimes the existing content model is insufficient; there are times when the opening paragraph needs to contain a list for example. Consider expanding the shortdesc model.

shortdesc (contract):
Conversely, there are times when the opening paragraph of content is already too long for use as hoverhelp/link previews. Consider providing a marker element within shortdesc to allow authors to define a particular sentence within the shortdesc for use in hoverhelp, without affecting the shortdesc's function as first paragraph of content in other contexts.

semantic linking:
There are cases where phrase-level markup in DITA content has clear equivalents in topic-level markup. For example, a <term> in content might be linked to a glossary topic, and an <apiname> in content might be linked to an API description or reference topic. While completely automatic linking has a high risk factor (since it depends on the semantics being consistently used, and on targets being unambiguous and correct even in new contexts), there is a compromise level of linking between fully automatic linking and fully specified linking: let's call it scoped semantic linking. The idea is to define, within a map, a branch of topics which contain semantic tags that should be processed as candidates for automatic linking, with another specified branch of topics providing the candidate targets. A new set of elements would be required to announce the intent to apply semantic linking, identify the elements to process, identify their potential targets, and identify match criteria.

For example:

<topicref href=""myprogrammingtasks.dita">
<!-- for this topic and its children, apply semantic linking to <apiname> elements: -->
<linkword href=""apiname">
    <!-- look for targets in the topics referenced in this other map, in the baseAPI branch -->
    <linkwordDefs href=""javaAPI.ditamap#baseAPI">
        <!-- look for a match in the title element of reference topics -->
        <linkwordMatch href=""reference//title"/>
<!--more child topics to apply the same linking rules to-->
<topicref href=""programmingtask1.dita"/>

    <topicref id="baseAPI" href=""baseAPI.dita">

Erik and I have been bashing this idea around for a bit, and can probably put together a more formal proposal with edge cases ironed out, but this covers the gist I think. The basic principle is to allow the authors to control initial linking rules via the map; reusers can then either apply the same linking rules, or new ones, depending on their understanding of the content and its context.  It should be easy for the author to declare the scope for semantic linking, and to process multiple sets of content from different sources that require different scopes. For example, when programming tasks from two different groups are combined, they don't have to match their APIs to the same libraries: each one can identify the API libraries being used in their task set, without interfering in the semantic linking process for the other task set.

Michael Priestley

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