[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Deprecating @copy-to
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]