Topics

<resourceid> element's @appid attribute


john.kirkilis@...
 

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.


Radu Coravu
 

Hi John,

Not sure if this answers your question but for example in the Oxygen WebHelp Responsive output we use the "resourceid" to gather such application IDs and redirect to the topics containing them when the application ID is given in a query string to the web help output:

https://www.oxygenxml.com/doc/versions/23.0/ug-editor/topics/whr-context-sensitive.html

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 2/10/21 03:07, john.kirkilis@... 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.

  


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.


john.kirkilis@...
 

On Wed, Feb 10, 2021 at 10:01 AM, ekimber@... wrote:
An ID used by an application to identify the topic.
Thanks Elliot for mentioning the DITA 2.0 proposal. I'll check it out.

My question has more to do with the description of the @appid attribute. The @appname is obviously the name of the application that is being documented, such as "OxygenXML"or "Apache Tomcat", and the name "appid" would lead me to believe that it's a way to more specifically identify specific parts of the application identified by @appname, whether it be a page, tab, window, dialog box, form field, etc. However the description, "An ID used by an application to identify the topic" indicates to me that it's an id the application uses to refer to a documentation topic, not a part of the application, and the note which says that @appid should be used instead of the @id attribute in DITA 1.2's use of <resourceid> further makes it sound like its a way to refer to a DITA topic rather than an aspect of the application. In addition, the definition of @ux-context-string, "Contains the value of a user-assistance context-string that is used to identify the topic", confuses me as well by including "identify the topic" instead of ""further identify the context of the application" being documented.

Perhaps, I'm being overly literal, but I would appreciate clarity on which attributes refer to aspects of the documentation and which refer to the application being documented.


Kristen James Eberlein
 

John, if you have a question about the language used in the DITA specification (or suggestions about how to improve it), please send an e-mail to the dita-comment list.

The dita-comment list is the mechanism for folks outside of OASIS to communicate with the DITA TC. All dita-comment e-mails are added to the agenda for the weekly DITA TC call.

Here is a link for how you can subscribe to the dita-comment list: https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=dita

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)


On 2/10/2021 8:06 PM, john.kirkilis via groups.io wrote:
On Wed, Feb 10, 2021 at 10:01 AM, ekimber@... wrote:
An ID used by an application to identify the topic.
Thanks Elliot for mentioning the DITA 2.0 proposal. I'll check it out.

My question has more to do with the description of the @appid attribute. The @appname is obviously the name of the application that is being documented, such as "OxygenXML"or "Apache Tomcat", and the name "appid" would lead me to believe that it's a way to more specifically identify specific parts of the application identified by @appname, whether it be a page, tab, window, dialog box, form field, etc. However the description, "An ID used by an application to identify the topic" indicates to me that it's an id the application uses to refer to a documentation topic, not a part of the application, and the note which says that @appid should be used instead of the @id attribute in DITA 1.2's use of <resourceid> further makes it sound like its a way to refer to a DITA topic rather than an aspect of the application. In addition, the definition of @ux-context-string, "Contains the value of a user-assistance context-string that is used to identify the topic", confuses me as well by including "identify the topic" instead of ""further identify the context of the application" being documented.

Perhaps, I'm being overly literal, but I would appreciate clarity on which attributes refer to aspects of the documentation and which refer to the application being documented.


ekimber@contrext.com
 

The @appid attribute is specifying the application-specific ID to be associated with the topic (or topicref-referenced resource).

So @appname names the application, @appid is the ID by which the application will point to the topic.

Rereading the description of resourceid now, it's not actually clear to me what the functional difference between @appid and @ux-context-string is, but I know the designers of the UX-specific features had a reason for it.

Based on the proposed 2.0 semantics for <resourceid>, I think the distinction between @appid and @ux-context-string is that @appid *contributes* to the final deliverable anchor while @ux-context-string *is* the anchor (help-specific context identifier). That is, @appid can apply to any kind of anchor for any kind of deliverable, while @ux-context-string is specifically for context-sensitive help and is intended to be used exactly as specified.

Another detail is that @appid was added to correct the original design of <resourceid> where the @id attribute was used for what @appid is now used for. Using @id was incorrect because @id always identifies the *element* on which it appears.

I agree that the names @appname and @appid are not as clear as they could be--in the process of preparing the DITA 2.0 proposal (Issue 33, replace @copy-to), I had to keep reminding myself that @appid is the ID and @appname is the application name.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/10/21, 7:06 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:

On Wed, Feb 10, 2021 at 10:01 AM, ekimber@contrext.com wrote:

An ID used by an application to identify the topic.

Thanks Elliot for mentioning the DITA 2.0 proposal. I'll check it out.

My question has more to do with the description of the @appid attribute. The @appname is obviously the name of the application that is being documented, such as "OxygenXML"or "Apache Tomcat", and the name "appid" would lead me to believe that it's a way to more specifically identify specific parts of the application identified by @appname, whether it be a page, tab, window, dialog box, form field, etc. However the description, "An ID used by an application to identify the topic" indicates to me that it's an id the application uses to refer to a documentation topic, not a part of the application, and the note which says that @appid should be used instead of the @id attribute in DITA 1.2's use of <resourceid> further makes it sound like its a way to refer to a DITA topic rather than an aspect of the application. In addition, the definition of @ux-context-string, "Contains the value of a user-assistance context-string that is used to identify the topic", confuses me as well by including "identify the topic" instead of ""further identify the context of the application" being documented.

Perhaps, I'm being overly literal, but I would appreciate clarity on which attributes refer to aspects of the documentation and which refer to the application being documented.


Bill Burns
 

Just some historical perspective here. Microsoft HTML Help (CHM) requires a numeric context ID (the value of @appid) and a topic id (the value of context @ux-context-string) to complete the CS help mappings. The context ID is mapped to the topic ID in a header file (which can come from app developers or can be maintained by hand), and the topic ID is mapped to the topic files in the hhp file (which also has a link to the header file). You can find Microsoft's guidelines here. Kind of an early approach to indirect referencing as you can swap out header files to establish new link targets.


On Thu, Feb 11, 2021 at 7:43 AM ekimber@... <ekimber@...> wrote:
The @appid attribute is specifying the application-specific ID to be associated with the topic (or topicref-referenced resource).

So @appname names the application, @appid is the ID by which the application will point to the topic.

Rereading the description of resourceid now, it's not actually clear to me what the functional difference between @appid and @ux-context-string is, but I know the designers of the UX-specific features had a reason for it.

Based on the proposed 2.0 semantics for <resourceid>, I think the distinction between @appid and @ux-context-string is that @appid *contributes* to the final deliverable anchor while @ux-context-string *is* the anchor (help-specific context identifier). That is, @appid can apply to any kind of anchor for any kind of deliverable, while @ux-context-string is specifically for context-sensitive help and is intended to be used exactly as specified.

Another detail is that @appid was added to correct the original design of <resourceid> where the @id attribute was used for what @appid is now used for. Using @id was incorrect because @id always identifies the *element* on which it appears.

I agree that the names @appname and @appid are not as clear as they could be--in the process of preparing the DITA 2.0 proposal (Issue 33, replace @copy-to), I had to keep reminding myself that @appid is the ID and @appname is the application name.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/10/21, 7:06 PM, "main@dita-users.groups.io on behalf of john.kirkilis@..." <main@dita-users.groups.io on behalf of john.kirkilis@...> wrote:

    On Wed, Feb 10, 2021 at 10:01 AM, ekimber@... wrote:

    An ID used by an application to identify the topic.

    Thanks Elliot for mentioning the DITA 2.0 proposal. I'll check it out.

    My question has more to do with the description of the @appid attribute. The @appname is obviously the name of the application that is being documented, such as "OxygenXML"or "Apache Tomcat", and the name "appid" would lead me to believe that it's a way to more specifically identify specific parts of the application identified by @appname, whether it be a page, tab, window, dialog box, form field, etc. However the description, "An ID used by an application to identify the topic" indicates to me that it's an id the application uses to refer to a documentation topic, not a part of the application, and the note which says that @appid should be used instead of the @id attribute in DITA 1.2's use of <resourceid> further makes it sound like its a way to refer to a DITA topic rather than an aspect of the application. In addition, the definition of @ux-context-string, "Contains the value of a user-assistance context-string that is used to identify the topic", confuses me as well by including "identify the topic" instead of ""further identify the context of the application" being documented.

    Perhaps, I'm being overly literal, but I would appreciate clarity on which attributes refer to aspects of the documentation and which refer to the application being documented.














--
Bill Burns
512-646-2100
--
We are [A] 


Julio J Vazquez
 

Because Microsoft doesn't really support CHM anymore, does it make sense to bring across that sort of baggage into 2.0? Should we remove the unneeded and move forward with required attributes? Because 2.0 doesn't need to be backward compatible, remove the chaff.


Julio J. Vazquez


john.kirkilis@...
 

I need a diagram with content on one side and a UX mock-up on the other, with arrows, cardinality/ordinality, and example values... either that or an old priest and a young priest to perform a brain-worm exorcism.


john.kirkilis@...
 

Hi Radu,

In the hopes of finding an example document set, I downloaded the Oxygen userguide source from GitHub and couldn't find any instances of <resourceid> being used anywhere in the content. I thought perhaps that's how you linked to your web help from Oxygen's help icon in every dialog box.

Regards,

John


Radu Coravu
 

Hi John,

Our WebHelp feature which generates context ids used to link to topics looks at both the @id attribute of the topic and at the "resourceid" element. As topic IDs are required and need to be specified inside the DITA topic anyway we decided to use the topic ID as the context id, and added some Schematron rules to insure that the topic ID always matches the file name, to provide some kind of uniqueness of the topic ID in the entire DITA project context.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 2/13/21 04:27, john.kirkilis@... wrote:

Hi Radu,

In the hopes of finding an example document set, I downloaded the Oxygen userguide source from GitHub and couldn't find any instances of <resourceid> being used anywhere in the content. I thought perhaps that's how you linked to your web help from Oxygen's help icon in every dialog box.

Regards,

John

  


ekimber@contrext.com
 

Radu's approach works *as long as* topic IDs and/or filenames are unique across your corpus of topics. There is nothing in the DITA standard that requires either of those two conditions to be true.

Because I'm that guy, I make a point of making every topic ID "topicid" when I can to ensure that systems and processors that assume topic IDs are always unique will break. Likewise, in a given corpus, you might have many topics with a filename of "introduction.dita" or something [Full disclosure: I built a DITA import process for a product I used to work on where it broke when filenames were not unique--that was particularly painful because I discovered the breakage when I tried to import a set of data I had created: the DITA version of John Bosak's XML Shakespeare's Plays. Hoist on my own petard.].

Of course, the full URI of any given topic is unique, so using a hash of the URI would always produce a unique value but that's not very human friendly.

The most general solution would be to either use <resourceid> within topics to assign unique names within some appropriate scope (might be your full corpus, might be just for a given product's documentation, or a library of products, or whatever) or to use keys as the basis of deliverable anchors.

Putting <resourceid> in topics where you ensure the <resourceid> values are appropriately unique makes the topics independently globally named (that is, you aren't relying on keys defined in maps to get name uniqueness). It serves the same purpose that Radu's ID- or filename-based approach does but doesn't limit your choices for either IDs or filenames, which might have other forces that need to control their values in a way that doesn't necessarily guarantee uniqueness.

I'm starting to see <resourceid> as the best way to manage global identifier uniqueness separate from keys, IDs, or filenames. It has several advantages over using any of the other available identifiers:

* Can have completely independent business rules.
* Can have different rules for different use environments (different deliverables, different tools, different business rules)
* Can have multiple resource IDs for the same resource
* Topics can assert their own resource IDs (topics cannot assert their own keys using DITA-defined mechanisms)

If you consider the use case of needing to migrate your content to a new organizational strategy or a new storage model, that likely means a change to some or all filenames or a change to your key naming strategy or some other potentially disruptive change. Because resource IDs are separate from these, they can be unaffected by this sort of source-level change. You might also decide to change your information architecture approach, which can change how you use keys, requiring a change to key names (or the addition of new keys to reflect the new architecture).

For people just starting out with DITA, it's probably hard to imagine how these name-management concerns are important, but once you've been using DITA for a few years, you will almost certainly be faced with some kind of disruptive change to how your DITA source is stored and managed, or a change to your Information Architecture approach, that requires modifying keys, filenames, or IDs. It will happen.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/14/21, 10:41 PM, "Radu Coravu" <main@dita-users.groups.io on behalf of radu_coravu@sync.ro> wrote:






Hi John,
Our WebHelp feature which generates context ids used to link to
topics looks at both the @id attribute of the topic and at the
"resourceid" element. As topic IDs are required and need to be
specified inside the DITA topic anyway we decided to use the topic
ID as the context id, and added some Schematron rules to insure
that the topic ID always matches the file name, to provide some
kind of uniqueness of the topic ID in the entire DITA project
context.

Regards,
Radu
Radu Coravu
Oxygen XML Editor

On 2/13/21 04:27,
john.kirkilis@nokia.com wrote:



Hi Radu,

In the hopes of finding an example document set, I downloaded the
Oxygen userguide source from GitHub and couldn't find any
instances of <resourceid> being used anywhere in the
content. I thought perhaps that's how you linked to your web help
from Oxygen's help icon in every dialog box.

Regards,

John