Re: <resourceid> element's @appid attribute


ekimber@contrext.com
 

The intent of resourceid is to allow you to associate arbitrary, application-specific identifiers, with topics or other resources addressed by topicrefs.

So if by "representation" you mean "how do I tag it up?" I think the answer is: You create a topic with the help content, associate a resource IDs with it, and then include those IDs in the published help for the target system, whatever that means.

I think the implication here is that individual fields will need to be documented in individual topics, as opposed to within the body of a topic (i.e., in a table, definition list, using section elements, whatever).

There's no defined mechanism using <resourceid> to bind a resource ID to an element within a topic, which is what I think you're asking for. I could see a given help system providing some convention for that, i.e., combining the topic's resource ID with an element ID from within the topic to create a resolvable anchor in the published help, but that behavior would be beyond what the DITA standard defines.

DITA's naming and addressing architecture basically says "the unit of addressability exposed to the outside world is the topicref". This is implicit (or, arguably, explicit) in the fact that maps are the place where you can define globally-unique identifiers for things by using keys or resource IDs to bind names to the things the topicrefs reference in the context of a specific root map.

Because root maps have identity (they are objects in the general computer science sense of things that have identity within the set of all possible things), by definition, the names defined in them are globally unique (because the location of the root map establishes a unique base address for all the unique names defined in the map). In particular, keys are, by definition, unique within the scope of a given root map. In terms of Web architecture, every root map has a unique URI and thus establishes a unique base URI for all the names defined within that root map, making all the names globally unique among all URI-addressible resources. (This is true for XML documents generally but in DITA root maps have a special role in that root maps cannot themselves be re-used. That's what being "root" means: a map that is not re-used directly by any other map.) The implication is that, because root maps have global identity (unique URIs), deliverables produced from them also have global identity, so the uniqueness of identifiers in root maps carry over to the deliverables produced from those root maps (or, more precisely, can be carried over to the deliverables produced from those root maps, since deliverable production systems can do whatever they way, including breaking the inherent uniqueness of the identifiers in the DITA source--the most the DITA standard can do is define the required properties of the source content).

Resource IDs are not, by the rules of the DITA spec, globally unique because there's no rule that prevents you assigning the same application name/app-id pair to multiple topics or topcirefs in the context of a single root map, but you would normally want to do that in order for your published help system to work correctly. This allows you to keep the DITA-specific identifiers (keys) separate from any application-specific identifiers you need to publish to. It also allows adding new application-specific identifiers after the fact (to avoid, for example, having to modify existing keys or adding additional keys, which could be disruptive or difficult depending on how you are using or not using keys).

Note that for DITA 2.0 we have just accepted a proposal to extend <resourceid> to allow it to satisfy the requirements for which @copy-to is currently used.

This proposal doesn't change anything about the DITA 1.3 definition of <resourceid> but does extend it to play a more general role in defining deliverable-specific anchor information, something that @copy-to was designed to do but that it didn't really do very well. So for example, if you have the requirement to define, on a topicref, that the referenced topic should have a specific HTML filename in the published HTML rendering of that topic, <resourceid> in DITA 2.0 will allow you to say that more explicitly than you can today (although you can use <resourceid> for that today given appropriate support in your publishing tools and some tools in fact do that today, using <resourceid> app-ids to generate anchors in HTML).

The main thing we add to <resourceid> is a way for authors to indicate that a given <resourceid> element is providing deliverable anchor information instead of help system identifiers (the original intended use and what existing systems that use <resourceid> assume when there is no @appname value). We also refine and clarify how <resourceid> information should be used by processors in the construction of deliverable anchors (tl;dr: processors should use the <resourceid> information as much as possible in a clear and consistent way so that the deliverable anchors produced for a given deliverable are as predictable and repeatable as possible, understanding that the details of deliverable generation, including anchor construction, are necessarily processor dependent).

Cheers,

E.

--
Eliot Kimber
http://contrext.com


´╗┐On 2/9/21, 7:07 PM, "main@dita-users.groups.io on behalf of john.kirkilis@nokia.com" <main@dita-users.groups.io on behalf of john.kirkilis@nokia.com> wrote:

The DITA 1.3 spec describes the @appid attribute of the <resourceid> as follows:

An ID used by an application to identify the topic.

While the @ux-context-string is defined as:

Contains the value of a user-assistance context-string that is used to identify the topic.

What I'm not clear about is how a UX resource, whether it be a page of a webapp or an individual field in a webform, should be represented in DITA so that when a help icon is clicked on a UX widget in a webapp, the proper topic can be referenced.

Join main@dita-users.groups.io to automatically receive all group messages.