RE: [dita] Deprecating @copy-to

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

I agree we could explicitly have a concept of a "normal role key definition"
designating a "use".
And that would allow us to use such keys to satisfy scoped linking
references using keyrefs to such a "use".
And thus the removal of copy-to.

Ruling out <keydef> (resource role) keydefs does have some implications.
And what about <keydefs> that are key definitions in terms of a keyref to
another key.  Seems we would use the final normal role definition in the
keyref reference chain - if there was one?

I do, however,  find that teasing apart the concepts of keys, addressing and
scope, as my proposal did, is an interesting alternative to examine because:

* It provides a fundamental addressing form for scope specific linking:
"GenericTractor.dita?scope=TractorY".  
* It means you do not have to define a key on a normal topicref to address
its rendition within that scope.  We simply use the scope (keyscope) which
in many cases has already been defined.
* It means that either processing-role normal or resource can still be used
for key definition for the purposes of cross linking.
* A URI addressable resource in a keydef is simply the URI String
"GenericTractor.dita?scope=TractorY" without more implicit binding rules
based on the position of the key in the keyscope hierarchy.

On your other note - using a query param would be within DITA - how a CCMS
uses it would have to be compliant with DITA.
That said, perhaps for downstream users of the URI a more unique parameter
name like "dita_mapscope" or "dita_keyscope" might be a better.

cheers
Jim

> -----Original Message-----
> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
Behalf
> Of Eliot Kimber
> Sent: May-26-16 7:41 AM
> To: dita@lists.oasis-open.org
> Subject: Re: [dita] Deprecating @copy-to
> 
> I'm not sure why you say:
> 
> But even with a key we need to know the base href form - in this case the
URI
> "GenericTractor.dita?scope=TractorY".
> 
> Normal-role key definitions unambiguously establish the use context of the
> resources they reference--for a given key in a given scope ancestry there
can
> only be one effective definition so there is no possibility of ambiguity
of the
> context of the reference. Resource-only key definitions are not generally
> appropriate as targets for cross references (because the referenced
resource
> has no defined position in the map's navigation hierarchy). Basically, if
you
> have a cross reference to a resource-only key you're saying "this topic,
if
> rendered, has no defined navigational relationship to any other topic used
> from the map." In most cases that would be a thing to be avoided. In the
> case of monolithic formats like PDF and EPUB is presents the problem of
> "where do we put these topics?" given that they have no defined position?
At
> the end? At the beginning? Omit them and have unresolved references". The
> obvious conclusion is "don't do that."
> 
> If the DITA standard started defining the details of query parameters for
> DITA-specific URIs it would be getting into the domain of processing APIs
and
> I, for one, think that would be a very, very bad idea.
> 
> The DITA specification does define it's own rules for DITA-specific
fragment
> identifiers. That is, I think, a necessary evil and is certainly supported
by
> general Web practice where the responsibility for defining fragment
> identifier semantics is explicitly delegated to the owners of specific
data
> formats (meaning there is no single standard for fragment identifiers).
> 
> But defining query parameters would put is in the realm of URI resolution
> processing, which is the domain of component content management systems.
> The DITA architecture goes to great lengths to avoid the need to codify or
> standardize any aspects of DITA content management systems.
> 
> If a given CMS wanted to use such a query syntax as a way of satisfying
some
> CMS-specific requirement (for example, supporting the use of direct URI
> references for clients that insist on not moving to keys), it's free to do
so. But
> such use should not be standardized as part of the base DITA architecture.
> 
> Cheers,
> 
> E.
> 
> 
> ----
> Eliot Kimber, Owner
> Contrext, LLC
> http://contrext.com
> 
> 
> 
> 
> On 5/25/16, 6:13 PM, "Jim Tivy" <dita@lists.oasis-open.org on behalf of
> jimt@bluestream.com> wrote:
> 
> >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
> >
> >
> >
> >---------------------------------------------------------------------
> >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
> >
> >
> 
> 
> 
> ---------------------------------------------------------------------
> 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