RE: [dita] Deprecating @copy-to

["Jim Tivy" <jimt@bluestream.com>]

Yes, good points - copyto does seem to have problems.

First thoughts on this are:

Although a simple topic can be rendered without a map context, it is not the
typical case.

In the typical case a topic is rendered within a context.  The context is
typically created by a map and may be augmented at certain "scopes" within
the hierarchy of the map.
In 1.3 we introduced two such scoped context features: ditaval processing
and keyscopes.

It seems that the best way to reference a rendition is by specifying its
context scope and its DITA source filename.
Something like:   href="GenericTractor.dita?scope=TractorY

Where TractorY is a scope defined within the map topicref hierarchy.

It would be better to use a keyref for this eg: keyref="TractorY.Tractor"

But even with a key we need to know the base href form - in this case the
URI "GenericTractor.dita?scope=TractorY".

To do this we could just use the keyscope idea as a scope name or we could
expand the idea of context scope.

Then we can let the processors decide when to materialize renditions and
when not to.

Jim




> -----Original Message-----
> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
Behalf
> Of Eliot Kimber
> Sent: May-25-16 11:30 AM
> To: dita@lists.oasis-open.org
> Subject: Re: [dita] Deprecating @copy-to
> 
> 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
> >
> >
> >
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-
> open.org/apps/org/workgroup/portal/my_workgroups.php