Re: [dita] Deprecating @copy-to

[Eliot Kimber <ekimber@contrext.com>]

I could see having a separate "deliverable anchor" property on a topicref,
but since references from any DITA content to that topicref will be by
key, that topicref already has a guaranteed-unique anchor (or anchors), so
having a separate property that would have to be set, managed, and
maintained in addition to any keys seems to overload any potential value
in terms of flexibility. In addition, if that level of control was a
requirement it can be added unilaterally using normal metadata facilities.
So it's not something that needs to be built into the architecture
(because it's not about addressing at the DITA level, only about
deliverable generation details).

There was a time when I felt pretty much the way you do: that every
navigation reference to a topic demands a new result file.

However, I've been convinced that at least in the specific case of HTML
delivered to Web sites that there is a real requirement to be able to have
a single HTML artifact for topics used in multiple contexts for a variety
of reasons, including SEO, navigational simplicity, "every page is page
one", etc. You can certainly imagine having HTML files that reflect the
union of inherited metadata or even that reflect different applied
conditions or resolved key references in a way that allows dynamic
filtering or flagging in the browser. Today the OT (at least through
1.8.5) will show all the parent and child links when a topic is used
multiple times and @copy-to is not applied, so there must be users who
prefer or tolerate the union approach.

I think this partly comes down to whether you consider the HTML you're
producing to be a book or to be a Web site. If it's a book then you
naturally want the same result as for PDF or any other monolithic result:
Every use of a topic produces a unique result artifact anchored clearly to
its position in the publication's navigation hierarchy.

But if you're producing a Web site then you very likely want to minimize
duplication of source content in the generated HTML as much as possible.
How you manage navigation into and out of re-used topics is a Web site
design and delivery user interface question but there are solutions.

Cheers,

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




On 5/25/16, 11:21 AM, "Chris Nitchie" <dita@lists.oasis-open.org on behalf
of chris.nitchie@oberontech.com> wrote:

>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
>
>
>