Re: [dita] Deprecating @copy-to

[Eliot Kimber <ekimber@contrext.com>]

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