Issue #33: Replace copy-to: How To Signal Intent

[Eliot Kimber <ekimber@contrext.com>]

Reviewing the samples provided by Deb, Scott, and Stan, it's clear that they are all being used to define context sensitive help-specific anchors for the topics to which they are associated. 

Deb and Scott do not qualify their <resourceid> elements, which suggests they are intended for use by a specific processor that does their help generation, with no expectation that any other processors would use <resourceid> for anything or that there would be different help generation applications.

Stan's example has qualified <resourceid> elements (different @appname values) and they are for different applications (although it's not clear if the application distinction is the application for which the help is the documentation or the application to which the help is published).

Reviewing the discussion from the 3 Nov 2020 meeting where we identified the need for a clear signal that the intent of a given <resourceid> element is to do what @copy-to was doing (determining the effective URI of the topic as delivered) and where we determined that the use of <resourceid> for that purpose should be mandatory, coupled with the knowledge that there is widespread use of <resourceid>, and in particular, unqualified <resourceid>, for CSH delivery, I think the implications are:

1. Where unqualified <resourceid> is used it is likely that it is intended for use only with a specific help delivery and therefore should *not* also determine the effective URI of the topic in other delivery contexts.
2. We need a clear signal that the intended use of a given <resourceid> is to determine the effective URI of the use of the topic to which it is associated.

The question then is what should that signal be?

I see several possibilities:

1. A DITA-defined value for @appname, i.e., "#effective-uri", that indicates that the <resourceid> must be used to determine the URI of the topic as delivered.
2. A rule that says "if @appname is specified then processors that accept that appname as applying to them MUST use the @appid value to determine the effective URI of the topic as delivered".
3. A new attribute, i.e. @role, that takes a keyword indicating the purpose of the <resourceid>, so a value of "effective-uri" would mean "this <resourceid> determines the effective URI of the topic for the named application. If no application is named then this <resourceid> determines the effective URI for all applications." The default for @role would either be unspecified, or perhaps be "context-sensitive-help" to match the expectations set by the original <resourceid> design (that it was specifically intended for use with help systems). The set of possible @role values would not be constrained so processors could support other values of @role for whatever reason.

I think option (3) is the best option because it doesn't change the existing semantics or processing expectations for <resourceid> and would also enable an easy specialization that fixes the value of @role, i.e., <copy-to appid="somefile"/> where @role is defaulted to "effective-uri".

Option (1) implies that @appname be treated as a set of tokens even though the spec does not require (or even suggest) that treatment.

Option (2) also requires both qualifying <resourceid> just to get the @copy-to behavior and effectively requires treating @appname as token list (since you might have to specify multiple target applications to avoid having to have multiple <resourceid> elements.

Note that "effective URI" is actually quite encompassing because it includes not just the direct resource-part of the URL (i.e., /foo/bar/somefile.html"), but query parameters and fragment identifiers, so the notion of "effective URI" encompasses PDF anchors (for which the PDF spec provides a fragment identifier syntax) and EPUB locators, for which the EPUB specification also provides a fragment ID syntax). 

Likewise, it encompasses the Zoomin-examples where the <resourceid> value becomes the target of a Zoomin-specific query parameter on the URI (".../csh?approved_chemicals"). That is, for any deliverable for which a URI syntax (scheme, fragment ID, query parameters) is defined, "effective URI" is meaningful.

Applying this logic to Deb's original Zoomin use case, if you specified @role="effective-uri" on the Zoomin-specific <resourceid> it would be accurate (because Zoomin is ultimately providing URI resolution to specific resources through its server) but it would then require that you qualify the <resourceid> to limit its use to Zoomin and not, for example, normal HTML output, i.e.,:

<resourceid appid="approved_chemicals" appname="zoomin" role="effective-uri"/>

The place where "effective URI" is not meaningful is systems where the published content is not accessed via URI but by some internal, application-specific mechanism, which really means embedded help of the old-school Windows Help variety.

Cheers,

E.

--
Eliot Kimber
http://contrext.com