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: Re: [dita] Deprecating @copy-to


I hadn’t fully considered the use case of needing a referenceable identifier that is present on the as-published representation of a map. While you _could_ use keys for that purpose, as Eliot suggests, I think having some sort of explicit mechanism for it is better than leaving it up to preferences or conventions that can vary from group to group or implementation to implementation.
 
That said, in reading the 1.3 spec language, as-published anchors are not called out as a use case for @copy-to. The fact that @copy-to can be used for this purpose is a side-effect of the out-of-the-box DITA-OT implementation of the feature, not a spec-mandated behavior. Even if it were, @copy-to is a lousy name for such a feature. So I think I stand by my suggestion of deprecating @copy-to, allowing that we may need to replace it with something more semantically appropriate for as-published addressability.

One other minor quibble with Eliot’s points.

<lq author=”Eliot”>
However, this same indication can be done with keys: if a @keys value is specified on a navigation topicref it necessarily implies generation of a new result component for the simple reason that it establishes a new addressible use of the topic. If a navigation topicref does not specify @keys then that use of the topic is not directly addressible and therefore there is no requirement to generate a unique result component (because there would be no way for any other topic to address that specific use).

Thus simply by using or not using @keys on navigation topicrefs map authors can control whether or not new result components are required or not required. @copy-to becomes both unneeded and unwanted.
</lq>

I actually go further – every navigational topicref to a given topic, regardless of presence/absence of keys, _should_ result in a unique output artifact because the modifications imposed on a topic’s metadata (by virtue of <topicmeta> content at and above the topicref) and/or related-links (parent/child/sibling/etc.) and/or keyref resolution (because of keyscopes) can vary from reference to reference, resulting in sometimes very different renderings of the same topic even within the same map. Addressability is only one among many factors involved.

Chris 

From: <dita@lists.oasis-open.org> on behalf of Eliot Kimber <ekimber@contrext.com>
Date: Wednesday, May 25, 2016 at 11:07 AM
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: Re: [dita] Deprecating @copy-to

I agree with Chris' analysis. 

In particular, processors should be encouraged to use key names on navigation topicrefs as the basis for determining the deliverable anchor or filename for the topics used by those topicrefs. 

(And if I ran the world @href on all linking elements used within topics would be restricted to only allowing URLs that are fragment identifiers but I realize that idea wouldn't be accepted at this time. Although it occurs to me now that that would be an easy thing to check with a Schematron. Hmmm...)

The @copy-to attribute specifies an effective source URI for the referenced topic, as though the referenced topic had been literally copied to the specified URI. This has implications for processors that map source topics to result deliverable components and that use source URIs to determine deliverable anchors.

One problem with @copy-to is that it's inherently difficult in a topic to refer by direct URL to the virtual copy of the target topic. That is, if the source topic "oldname.dita" and the @copy-to value on a reference to "oldname.dita" is "newname.dita", in a topic that wants to link to the "newname.dita" use of "oldname.dita", the topic author has to know what the @copy-to value is and specify href="newname.dita" instead of href="oldname.dita". This is a problem for several reasons: during authoring there is no actual topic named "newname.dita" so authoring tools either can't resolve the link (and thus report it as broken) or they have to look in the map to see if any @copy-to attributes specify "newname.dita". And then there's the general problem with direct URI references from topics to other topics.

This way of taking advantage of @copy-to is really a way to refer to a specific use of a topic. But clearly using keys is the better practice.

If we always use keys in order to link to specific uses of topics then @copy-to only serves to specify the effective source filename of a topic on a specific use (or uses) of that topic. However, the value of that is suspect given that it only really makes sense in the context of determining result anchors (e.g., HTML filenames or PDF anchors or whatever). But for that requirement I would argue that keys are the better solution.

The only other thing that @copy-to has the effect of doing is controlling whether or not a use of a given topic always results in a new HTML file. 

That is, if @copy-to is specified, unless a processor actually compared topics to determine if two different topic files where in fact identical, a processor that maps source topics to result components has no choice to but to treat a topic referenced on a topicref with @copy-to as a new topic. That gives authors a way to force generation of new HTML files for processors that otherwise only generate a single result file for a given topic regardless of how many times it's used (which is how the Open Toolkit currently behaves).

However, this same indication can be done with keys: if a @keys value is specified on a navigation topicref it necessarily implies generation of a new result component for the simple reason that it establishes a new addressible use of the topic. If a navigation topicref does not specify @keys then that use of the topic is not directly addressible and therefore there is no requirement to generate a unique result component (because there would be no way for any other topic to address that specific use).

Thus simply by using or not using @keys on navigation topicrefs map authors can control whether or not new result components are required or not required. @copy-to becomes both unneeded and unwanted.

Because @keys can specify multiple values, processors can establish conventions for how to choose which key to use to determine result anchors (e.g., HTML filenames). For example, they can use the first key in@keys as the basis for anchors or the last key or a key starting with some conventional prefix.

For example, using a "last key" convention would allow you to have both a "primary" key, perhaps that reflects the rhetorical use of the topic, and a "result anchor key" that does what @copy-to did.

So for the newname.dita/oldname.dita example above, you could instead do:

<topicref keys="installation newname"
  href="oldname.dita"
/>

Where "installation" is the "primary" key (reflecting the rhetorical role of the topic at that use) and "newname", as the last @keys value, serves as the basis for the result anchor (e.g., "newname.html" for this use of topic oldname.dita").

Processors could be more sophisticated, for example, treating the same unqualified key name for the same topic used in different scopes as being a single use if the referenced topic does not otherwise require multiple result components (because it doesn't have any references to keys in its ancestor scopes or is not affected by branch filtering).

Cheers,

Eliot

----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com

From: dita <dita@lists.oasis-open.org> on behalf of Chris Nitchie <chris.nitchie@oberontech.com>
Date: Wednesday, May 25, 2016 at 7:52 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Deprecating @copy-to

The @copy-to attribute is based on the way the DITA Open Toolkit is implemented, and makes some assumptions about DITA processing that are not otherwise (to my knowledge) mandated in the spec. Specifically, it assumes that a given input topic will, by default, be represented by a single referenceable output artifact; specifying @copy-to allows that output artifact to be copied (logically if not physically) to another referenceable location. I’d like to posit that any use case served by @copy-to would be better served by using keys.
 
Chris





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