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 wanted to follow up on Stan's remarks about @copy-to causing multiple copies of a topic in the HTML result and this being a problem for search.

This is a larger problem than just @copy-to—it occurs in any situation where the same topic is used more than once and those uses require different rendered results or you simply choose to produce separate result artifacts for each use. 

In particular, the use of key scopes and branch filtering can result in this case regardless of the use of @copy-to or @keys on the topicrefs involved: each different use of the same topic could reflect different filtering results or different resolved key references and therefore the rendition of the topic in each use needs to reflect those differences.

The practical problem for the implementors of HTML-type outputs is how to handle this case: through generation of separate HTML files, one for each use that results in a different rendered result, or through display-time dynamic mechanisms embedded in a single result file. Today the Open Toolkit takes the first approach, mostly, which is easy to implement, but many users would really rather have a single-file, dynamic rendering solution.

There is also the problem with tracking user navigation in such a case, either as a result of arriving at a rendered topic via search or navigating to it through some sequence of navigation links. Both have important user interaction implications and present interaction design challenges.

These issues are inherent in doing reuse and are not directly related to the use of @copy-to or keys. The issues are simply an unavoidable side effect of delivering re-used content to multi-file outputs like HTML.  Removing @copy-to and using keys in their place does not actually do anything to address these issues, because these are delivery-in-the-face of re-use issues, not source markup issues. The issues have always been present in DITA since 1.0 but it's only been with branch filtering and key scopes that the challenge has become blindingly obvious because there are more opportunities for re-used topics to require different renderings for different uses.


Cheers,

Eliot

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

From: dita <dita@lists.oasis-open.org> on behalf of Jim Tivy <jimt@bluestream.com>
Date: Monday, June 6, 2016 at 9:23 PM
To: Eliot Kimber <ekimber@contrext.com>
Cc: dita <dita@lists.oasis-open.org>
Subject: Re: [dita] Deprecating @copy-to

What I was saying is ?ditaScope="foo" would be defined by DITA to have the meaning that it means reference that scope within the current map.

On Tue, May 31, 2016 at 7:43 AM, Eliot Kimber <ekimber@contrext.com> wrote:
I don't understand this comment:

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

The DITA standard simply requires that direct addresses to resources
(e.g., @href, @conref, etc.) be URIs and that URIs to elements in DITA
documents use the DITA-defined fragment identifiers. Beyond that it places
no restrictions on the details of URIs used, so no aspect of the use of
URNs or query parameters is restricted by the DITA specification.


That is, it is not possible to not be "compliant with DITA" with any URI
as long as that URI is 1) a valid URI per the applicable IETF and W3C
specifications and 2) uses a DITA-defined fragment identifier if the
address is to a DITA element that is not the root element or, for topics
in <dita> documents, the first child of the root element (meaning URIs
that don't require fragment identifiers to address a map or topic element).

Thus, this URI is perfectly valid DITA as far as the DITA spec is
concerned:

urn:someschemeimadeup:foo:bar:baz?queryParam1=thing1&queryParam2=thing2

The resolution of this URI is entirely in the domain of processing outside
the scope of the DITA standard. As long as the result of resolving it
satisfies the requirements of the DITA element that makes the reference
then conformance requirements are satisfied.

Cheers,

E.


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




On 5/30/16, 3:01 PM, "Jim Tivy" <jimt@bluestream.com> wrote:

>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=""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=""
>> >> >instead of href="". 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=""
>> >> >/>
>> >> >
>> >> >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
>
>
>



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




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