Next in thread →
Next in month →
Re: [dita] Deprecating @copy-to
Given that each ditaval can potentially introduce its own unique
version of any conditioned topic, it seems to me that this makes
the ditaval file the appropriate place to declare a "namespace"
for topics filtered by that particular ditaval. A new metadata
value added to the ditaval DTD would declare that val file's
namespace that would be prepended to filenames of topics modified
by that ditaval set (and only for modified topics in order not to
create duplicates from unmodified topics).
In branch filtered cases, the namespaces can aggregate, or last
one wins--not sure which is better. But this would ensure that all
filtered topics are still uniquely named.
Some users may prefer specific filenames for these conditions, in
which case namespacing from the ditaval won't solve that need. If
documents are to be published in an interoperable manner by
another company, then the naming method needs to be consistent
across tools. In Web publishing, the method of choice is a
separate slug for each published variant of the content. This
dependency of the process that produced the variant output on the
naming of that output means that the ditaval file should be the
place where each variant name (or slug) is declared, or at least
keyed from. Here, I think that the declared namespace in a ditaval
could also serve as a key to a particular set of keydefs (or their
context map) where the keydef serves as the place where that
particular slug value is bound to the actual resource. A topic
would have a different keydef/slug for each ditaval where explicit
naming is preferred (effectively supplanting the copy-to intent).
Summary: A ditaval with a namespace value will normally append
that namespace to any topic it affects. Alternatively, that
namespace also keys that ditaval to keydefs that provide alternate
output slug names for the touched renditions. (This is not
standard for keydefs held in a map, but it works fine for a
mapless dynamic publishing environment, and may inform on the need
for being able to group keydefs independently of a map.)
This proposal also eschews use of metadata within the topic as
the source for the slugname since the condition requiring the slug
is created by the processing context and should be changed in that
context without having to edit the topic for each presumed new SEO
campaign.
-
Don R. Day
Founding Chair, OASIS DITA Technical Committee (current version: DITA
1.3)
LinkedIn: donrday Twitter:
@donrday
About.me: Don R. Day Skype:
don.r.day
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
On 6/7/2016 11:13 AM, Eliot Kimber
wrote:
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.
I wrote a blog post about this issue recently: http://drmacros-xml-rants.blogspot.com/2016/05/delivering-html-from-dita-in-face-of.html#links
Cheers,
Eliot
----
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com
From: dita <>
on behalf of Jim Tivy <>
Date: Monday, June 6,
2016 at 9:23 PM
To: Eliot Kimber <>
Cc: dita <>
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 <>
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" <>
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:
[mailto:]
On
>Behalf
>> Of Eliot Kimber
>> Sent: May-26-16 7:41 AM
>> To:
>> 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" <
on behalf of
>> >
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:
[mailto:]
On
>> >Behalf
>> >> Of Eliot Kimber
>> >> Sent: May-25-16 11:30 AM
>> >> To:
>> >> 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" <
on
>> >>behalf of >
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: <>
on behalf of Eliot Kimber
>> >> ><>
>> >> >Date: Wednesday, May 25, 2016 at
11:07 AM
>> >> >To: ""
<>
>> >> >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 <>
on behalf of Chris Nitchie
>> >> ><>
>> >> >Date: Wednesday, May 25, 2016 at
7:52 AM
>> >> >To: dita <>
>> >> >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
-
Virus-free
Next in thread →
Next in month →