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