OASIS Darwin Information Typing Architecture (DITA) TC

 View Only

Eberlein review of removing @copy-to proposal

  • 1.  Eberlein review of removing @copy-to proposal

    Posted 08-24-2020 17:02
    Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee OASIS Distinguished Contributor Principal consultant, Eberlein Consulting LLC www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) -------- Forwarded Message -------- Subject: Remove @copy-to example Date: Sun, 20 Oct 2019 19:26:38 -0400 From: Kristen James Eberlein <kris@eberleinconsulting.com> To: Eliot Kimber <ekimber@contrext.com> CC: Robert Anderson <robander@us.ibm.com> , Chris Nitchie <chris.nitchie@oberontech.com> I am sorry that I am late with this. I also think that I have raised more issues ... Oxygen change tracked except for where I added (many) draft comments. I added an additional Example section at the end; please see my comment there. -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> <reference id="IssueNumber00" xml:lang="en-us"> <title><?oxy_delete author="Kristen J Eberlein" timestamp="20191014T193057-0400" content="DITA 2.0 proposed feature #33"?><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193104-0400"?>Stage two: #33 Remove <xmlatt>copy-to</xmlatt><?oxy_insert_end?></title> <shortdesc>Remove<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193134-0400"?> the<?oxy_insert_end?> <?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193142-0400" type="surround"?><xmlatt><?oxy_insert_end?>copy-to</xmlatt><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193145-0400"?> attribute<?oxy_insert_end?>.</shortdesc> <refbody> <section> <title>Date and version information</title> <p> <dl> <dlentry> <dt>Date that this feature proposal was completed</dt> <dd>05 Oct 2019<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193216-0400"?> â This should be the date of THIS proposal<?oxy_insert_end?></dd> </dlentry> <dlentry> <dt>Champion of the proposal</dt> <dd>Eliot Kimber<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193228-0400"?>, Individual member<?oxy_insert_end?></dd> </dlentry> <dlentry> <dt>Links to any previous versions of the proposal</dt> <dd><?oxy_delete author="Kristen J Eberlein" timestamp="20191014T193237-0400" content="N/A"?><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193406-0400"?><xref href=" https://lists.oasis-open.org/archives/dita/201910/msg00033.html" ; format="html" scope="external">05 October 2019</xref><?oxy_insert_end?></dd> </dlentry> <dlentry> <dt>Links to minutes where this proposal was discussed at stage 1 and moved to stage 2</dt> <dd><xref href=" https://lists.oasis-open.org/archives/dita/201706/msg00013.html" ; format="html" scope="external" >30 May 2017</xref></dd> </dlentry> <dlentry> <dt>Reviewers for Stage 2 proposal</dt> <dd>Chris Nitchie<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193431-0400"?>, Oberon Technologies<?oxy_insert_end?></dd> <dd>Robert Anderson<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T193439-0400"?>, IBM<?oxy_insert_end?></dd> </dlentry> <dlentry> <dt>Links to e-mail discussion that resulted in new versions of the proposal</dt> <dd>N/A</dd> </dlentry> <dlentry> <dt>Link to the GitHub issue</dt> <dd><xref href=" https://github.com/oasis-tcs/dita/issues/33" ; format="html" scope="external" > https://github.com/oasis-tcs/dita/issues/33https://github.com/oasis-tcs/dita/issues/33 </xref></dd> </dlentry> </dl> </p> </section> <section> <title>Original requirement or use case</title> <p>From the minutes linked to above, Chris Nitchie is recorded as saying:<lq> <p>The copy-to @ assumes certain things about the way processing is done, specifically the dita-ot way, and with key-scopes that's the wrong way. We should find some other way to address those needs and remove copy-to.</p> </lq></p> </section> <section id="section_dp4_dw4_xgb"> <title>Use cases</title> <?oxy_delete author="Kristen J Eberlein" timestamp="20191018T135441-0400" content="&lt;p&gt;&lt;b&gt;General Requirements&lt;/b&gt;&lt;/p&gt;"?> <draft-comment author="Kristen J Eberlein" time="14 October 2019"> <p>The content in this section is a mixture of the following:</p> <ul> <li>Use cases that drove the original inclusion of <xmlatt>copy-to</xmlatt> in the DITA standard</li> <li>Fact that <xmlatt>keys</xmlatt> and <xmlatt>keyref</xmlatt> attribute can "completely meet" requirements that led to development of <xmlatt>copy-to</xmlatt> (KJE: I don't think this is completely accurate.)</li> <li>Branch filtering and the <xmlatt>keyscope</xmlatt> attribute add to an author's arsenal</li> <li>Statement that many of these use cases are problematic, since they have to do with content delivery rather than core DITA architecture.</li> </ul> <p>I think these different aspects of the issue need to be handled separately. Finally, this section needs to clearly state the use case for removing the <xmlatt>copy-to</xmlatt> attribute. Right now that information is buried.</p> </draft-comment> <draft-comment author="Kristen J Eberlein" time="18 October 2019"> <p>I think the following <xmlelement>ul</xmlelement> should be changed to a definition list. That would provide highlighting for a label, and allow you to use paragraphs to cover different types of information: Elaboration, example, comments about DITA functionality such as key scopes and branch filtering</p> </draft-comment> <p><?oxy_delete author="Kristen J Eberlein" timestamp="20191018T135459-0400" content="The requirements to which"?><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T135459-0400"?>The<?oxy_insert_end?> <xmlatt>copy-to</xmlatt><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T135504-0400"?> attribute was developed to address the following use cases<?oxy_insert_end?><?oxy_delete author="Kristen J Eberlein" timestamp="20191018T135522-0400" content=" was a response include"?>:<ul id="ul_hrm_vx2_5fb"> <li>The <?oxy_delete author="Kristen J Eberlein" timestamp="20191018T135635-0400" content="ability"?><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T135635-0400"?>need<?oxy_insert_end?> to <?oxy_delete author="Kristen J Eberlein" timestamp="20191018T135640-0400" content="unambiguously and reliably"?> link from within DITA source to a specific use of a topic when the topic is used more than once within the same publication. Before DITA 1.2 this requirement was met, weakly, by the <xmlatt>copy-to</xmlatt> attribute. With DITA 1.2 it can be met completely by the use of keys and references to keys in place of direct URI references to source topics.</li> <li>The ability to say, as the author of a map, that a given topic used more than once should produce a single result artifact or should produce multiple result artifacts for different uses of the topic. For example, a topic may be used in multiple chapters but the desire is for a single HTML result to which all links to the topic resolve. Conversely, there may be a desire to have each chapter-specific use of a topic result in a separate result HTML file. While keys enable unambiguous references to specific uses of topics they do not, by themselves, provide a way to indicate the deliverable intent for re-used topics. The use of key scopes and branch filtering effectively require the generation of unique results in some circumstances and may be sufficient to signal author intent. For example, a reference to a use of a topic within a specific scope where the topic is used in a different scope, seems to demand, or least strongly suggest, the need for a unique result artifact in a multi-artifact deliverable (however, just having two uses, even in different scopes is not sufficient to <b>require</b> two result artifacts).<draft-comment author="Kristen J Eberlein" time="18 October 2019"> <p>Did <xmlatt>copy-to</xmlatt> ever address this use case?</p> </draft-comment></li> <li>The <?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T140022-0400"?>need<?oxy_insert_end?> to<?oxy_delete author="Kristen J Eberlein" timestamp="20191018T140028-0400" content=" strongly "?>determine the anchors used in a deliverable independent from the filenames used for the source topics. For example, having published a set of HTML files for a publication and knowing that readers have created links (e.g., bookmarks) to specific HTML files in that publication, when the publication is updated and republished the filenames of the HTML files must be preserved as much as possible, even if the source files have changed, for example because the source was moved into a CCMS that imposes its own file naming scheme or because the source files were renamed and reorganized to reflect some new general source organization practice.</li> <li>The ability to indicate that topicheads should be treated as though they were references to title-only topics.</li> <li>Replace the shortdesc of the referenced topic with a short description provided by the referencing topicref.</li> </ul></p> <draft-comment author="Kristen J Eberlein" time="18 October 2019">The first sentence of the paragraph below is actually the use case for this proposal. As the proposal is written, this use case is completely buried here!</draft-comment> <p>All of these requirements, while valid, fall into the realm of delivery processing (except for the last one, replacement of short descriptions) and therefore are outside the scope of what the DITA specification can mandate. In particular, the relationship between DITA source files and anything in any kind of deliverable is entirely up to the processor to determine. While the use of keys to refer to specific uses of topics provides an unambiguous identifier for that use, and thus something reliable as the basis for persistent anchors in deliverables, that utility is not sufficient to then <i>require</i> that processors use those keys when generating anchors.</p> <p>The requirement to enable dynamic replacement of short descriptions in referenced topics, while logical, is difficult to justify. Open Toolkit never implemented this feature so it is highly unlikely that anyone ever used it. The requirement to have use-context-specific content in a topic is met more generally by using key scopes and key-scope-specific key definitions or content references.</p> <p>With the existence of keys the requirement to unambiguously identify and refer to specific uses of a given topic is satisfied. Thus the <xmlatt>copy-to</xmlatt> attribute is no longer needed.</p> </section> <section> <title>Proposed solution</title> <draft-comment author="Kristen J Eberlein" time="14 October 2019"> <p>Reg<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T140825-0400"?>a<?oxy_insert_end?>rding the 2nd list item, has the TC discussed a stage one proposal for an additional chunking proposal? Or has this been handled in the approved proposal for changes to chinking?</p> <p>Does the section on changes to the written specification (later in this proposal) cover "language added in DITA 1.2 around the implications of <xmlatt>copy-to</xmlatt> on topic heads and the implication for the generation of title-only topics"?</p> </draft-comment> <ul id="ul_wkm_1x4_xgb"> <li> <p>Remove the <xmlatt>copy-to</xmlatt> attribute.</p> </li> <li>The processing requirements for <xmlatt>chunk</xmlatt> related to the presence of <xmlatt>copy-to</xmlatt> must be removed or redefined to reflect the appropriate mechanism, if any. This should be addressed in the separate chunking rework proposal. It is likely that the language added in DITA 1.2 around the implications of <xmlatt>copy-to</xmlatt> on topic heads and the implication for the generation of title-only topics was a Bad Idea and should simply be removed from DITA 2.0.</li> </ul> </section> <section> <title>Benefits</title> <p> <dl> <dlentry> <dt>Who will benefit from this feature?</dt> <dd> <ul id="ul_vwf_mgp_xgb"> <li>Tool vendors who no longer need to account for the effect of <xmlatt>copy-to</xmlatt>.</li> <li>Authors who no longer need to use <xmlatt>copy-to</xmlatt> simply to achieve a processor-specific, deliverable-specific result.</li> </ul> </dd> </dlentry> <dlentry> <dt>What is the expected benefit?</dt> <dd> <ul id="ul_ubc_pgp_xgb"> <li>Simplification of the DITA specification by removing a problematic and redundant feature.</li> <li>Providing, through guidance to implementors, richer and more consistent facilities for managing the anchors in deliverables generated from DITA source.</li> </ul> </dd> </dlentry> <dlentry> <dt>How many people probably will make use of this feature?</dt> <dd>Not relevant (removing an existing feature).</dd> </dlentry> <dlentry> <dt>How much of a positive impact is expected for the users who will make use of the feature?</dt> <dd>This should be a significant positive impact for DITA users who currently depend on the use of <xmlatt>copy-to</xmlatt> or otherwise struggle to manage the anchors in their generated deliverables.</dd> <dd> <draft-comment author="Kristen J Eberlein" time="16 October 2019"> <p>This will be true ONLY if processors implement new features that enable users handle the use cases that were previously met by <xmlatt>copy-to</xmlatt>.</p> <p>I think we cannot underestimate this. This proposal and the following stage three proposal need to clearly outline for folks who implement processors the use cases that need to be met and the different DITA markup options â <xmlatt>keys</xmlatt>, <xmlelement>keyref</xmlelement>, <xmlatt>keyscope</xmlatt>, <xmlelement>data</xmlelement> elements, <xmlatt>outputclass</xmlatt> â that they might use to implement a solution.</p> </draft-comment> </dd> </dlentry> </dl> </p> </section> <section> <title>Technical requirements</title> <?oxy_delete author="Kristen J Eberlein" timestamp="20191014T195621-0400" content="&lt;note type=&quot;important&quot;&gt;This section must be complete in order for the proposal to be approved.&lt;/note&gt;"?> <?oxy_insert_start author="Kristen J Eberlein" timestamp="20191014T195733-0400"?> <p>This proposal involves the following changes:</p> <?oxy_insert_end?> <p>Remove the declaration of the <xmlatt>copy-to</xmlatt> attribute from the following groups:<ul id="ul_onr_hhp_xgb"> <li>topichead.attributes (<filepath>mapGroupDomain.rng)</filepath></li> <li>anchorref.attributes (<filepath>mapGroupDomain.rng)</filepath></li> <li>mapref.attributes (<filepath>mapGroupDomain.rng)</filepath></li> <li>keydef.attributes (<filepath>mapGroupDomain.rng)</filepath></li> <li>topicref.attributes (<filepath>mapMod.rng)</filepath></li> </ul></p> <p> <dl> <dlentry> <dt>Processing impact</dt> <dd> <p>The removal of <xmlatt>copy-to</xmlatt> should not require a change to any processor.</p> <p>Processors that currently handle <xmlatt>copy-to</xmlatt> can remove or disable that code if desired.</p> <p>Processors may need to add new features to enable appropriate anchor generation based on the use of keys or other author-provided hints (<xmlatt>outputclass</xmlatt> values, new run time parameters, etc.).</p> <draft-comment author="Kristen J Eberlein" time="14 October 2019"> <p>I think " Processors may need to add new features â" is WAY too weak a statement. Processors will HAVE to make changes in order to support the user requirements</p> </draft-comment> </dd> </dlentry> </dl> <dl> <dlentry> <dt>Overall usability</dt> <dd>Documents that currently use <xmlatt>copy-to</xmlatt> will need to be migrated to replace <xmlatt>copy-to</xmlatt> with the appropriate replacement, i.e., the use of unique keys for each use of a topic where <xmlatt>copy-to</xmlatt> was previously used to distinguish different uses of the topic and for which there are direct URI references to the effective source file defined by <xmlatt>copy-to</xmlatt>.</dd> </dlentry> </dl> </p> </section> <section rev="2.0"> <title>Backwards compatibility</title> <p>DITA 2.0 is the first DITA release that is open to changes affecting backwards compatibility. To help highlight any impact, does this proposal involve any of the following?</p> <dl> <dlentry> <dt>Was this change previously announced in an earlier version of DITA?</dt> <dd>No. The <xmlatt>copy-to</xmlatt> attribute was not marked as "deprecated" in DITA 1.x.</dd> </dlentry> <dlentry> <dt>Removing a document type that was shipped in DITA 1.3?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Removing a domain that was shipped in DITA 1.3?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Removing a domain from a document type shell was shipped in DITA 1.3?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Removing or renaming an element that was shipped in DITA 1.3?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Removing or renaming an attribute that was shipped in DITA 1.3?</dt> <dd>Yes: <xmlatt>copy-to</xmlatt>.</dd> </dlentry> <dlentry> <dt>Changing the meaning of an element or attribute in a way that would disallow existing usage?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Changing a content model by removing something that was previously allowed, or by requiring something that was not?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Changing specialization ancestry?</dt> <dd>No.</dd> </dlentry> <dlentry> <dt>Removing or replacing a processing feature that was defined in DITA 1.3?</dt> <dd>This change removes the ability to <i>directly</i> define the effective filename of a referenced topic. However, processors are encouraged to use <xmlatt>keys</xmlatt> values for that where appropriate or necessary (for example, to determine the filename of HTML files resulting from referenced topics).<p>May remove the current (likely unused) ability to impose short descriptions onto effective copies of topics.<draft-comment author="Kristen J Eberlein" time="18 October 2019"> <p>Are we removing this processing expectation or not? I think this proposal can't say "We might remove the requirement".</p> </draft-comment></p></dd> </dlentry> <dlentry> <dt>Are element or attribute groups being renamed or shuffled?</dt> <dd>No.</dd> </dlentry> </dl> </section> <section rev="2.0"> <title>Migration plan</title> <p>If the answer to any question in the previous section is "yes":</p> <dl> <dlentry> <dt>Might any existing documents need to be migrated?</dt> <dd>Maps that use <xmlatt>copy-to</xmlatt> will need to be migrated. Migration actions<?oxy_delete author="Kristen J Eberlein" timestamp="20191018T141253-0400" content=" may"?><?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T141253-0400"?> <?oxy_insert_end?> include:<ul id="ul_vj5_s3p_xgb"> <li>The <xmlatt>copy-to</xmlatt> attributes must be removed.</li> <li>If a topicref that used <xmlatt>copy-to</xmlatt> does not already have a unique key associated with it, it will likely be necessary to assign a unique key to the topicref, especially if the topic is a target of a direct URI reference to the effective filename defined by the <xmlatt>copy-to</xmlatt> attribute. For example, a migration tool can use the <xmlatt>copy-to</xmlatt> value as a new or additional value for <xmlatt>keys</xmlatt>, possibly removing any extension in the <xmlatt>copy-to</xmlatt> value (i.e., removing ".dita" and then using the result as a new <xmlatt>keys</xmlatt> value).</li> <li>Cross references or content references that make direct URI references (<xmlatt>href</xmlatt>, <xmlatt>conref</xmlatt>) to the effective filenames defined by <xmlatt>copy-to</xmlatt> attributes must be updated to address the appropriate resource, normally the unique key of the topicref. For example, a migration tool could simply use the target filename as the <xmlatt>keyref</xmlatt> or <xmlatt>conkeyref</xmlatt> value, assuming that the migration tool also uses the <xmlatt>copy-to</xmlatt> value as a new value for <xmlatt>keys</xmlatt>.</li> </ul></dd> </dlentry> <dlentry> <dt>Might any existing processors or implementations need to change their expectations?</dt> <dd> <p>Processors that depend on or expect the use of <xmlatt>copy-to</xmlatt>, for example to signal the generation of distinct artifacts from that use of a topic, will need to provide other ways to provide that signal, such as rules associated with the use of keys or <xmlatt>outputclass</xmlatt> values.</p> </dd> </dlentry> <dlentry> <dt>Might any existing specialization or constraint modules need to be migrated?</dt> <dd> <p>Existing specialization or constrain<?oxy_insert_start author="Kristen J Eberlein" timestamp="20191018T141327-0400"?>t<?oxy_insert_end?> modules that declare the <xmlatt>copy-to</xmlatt> attribute will need to remove the attribute declaration.</p> </dd> </dlentry> </dl> </section> <section> <title>Costs</title> <p>Outline the impact (time and effort) of the feature on the following groups.</p> <dl> <dlentry> <dt>Maintainers of the grammar files</dt> <dd>Trivial.</dd> </dlentry> <dlentry> <dt>Editors of the DITA specification</dt> <dd> <ul> <li>How many new topics will be required? At least one topic to document the new processing expectations. Possibly more for an explanatory appendix.</li> <li>Which existing topics will need to be edited?<p>Eight topics in the architecture spec:</p><ul id="ul_h4w_jwp_xgb"> <li><filepath>chunkingdetails.dita</filepath> has rules involving <xmlatt>copy-to</xmlatt> in the discussion of rules for chunking. To the degree that these rules survive the separate chunking rework, this topic will need to be updated to remove references to <xmlatt>copy-to</xmlatt>.</li> <li><filepath>chunkingexamples.dita</filepath> examples include those with <xmlatt>copy-to</xmlatt>. They will need to be reworked as appropriate.</li> <li><filepath>ditamap-attributes.dita</filepath> has a definition of the <xmlatt>copy-to</xmlatt> attribute. It will need to be removed.</li> <li><filepath>dtd-coding-element-types.dita</filepath> and <filepath>reconciling-topic-and-map-metadata.dita</filepath> show example attribute list declarations that includes <xmlatt>copy-to</xmlatt>.</li> <li><filepath>metadata-in-maps-and-topics.dita</filepath> has a statement about maps being allowed to (MAY) override topic short descriptions if <xmlatt>copy-to</xmlatt> is specified. Remove this language. </li> <li><filepath>processing-key-references-general.dita</filepath> mentions <xmlatt>copy-to</xmlatt> under the section title "Reusing a topic in multiple key scopes". This statement needs to be revised to remove mention of <xmlatt>copy-to</xmlatt>.</li> <li><filepath>reconciling-topic-and-map-metadata.dita</filepath> has an entry for <xmlelement>shortdesc</xmlelement> that refers to the same implication for shortdesc replacement when <xmlatt>copy-to</xmlatt> is specified similar to the statement in <filepath>metadata-in-maps-and-topics.dita</filepath>. Remove this language.</li> </ul><p>Five topics in the language reference (not counting topics that reflect generated attribute lists):</p><ul id="ul_kqy_nzp_xgb"> <li><filepath>dvrResourcePrefix.dita</filepath> and <filepath>dvrResourceSuffix.dita</filepath> use the reusable phrase "ditavalref-copyto" from <filepath>conref-file.dita</filepath>. The statement is not relevant to these elements with the removal of <xmlatt>copy-to</xmlatt>. However, it is probably appropriate to say something about how prefix and suffix can affect anchor generation (namely, that the prefix and suffix should be used as appropriate when constructing deliverable anchors). These topics also refer to the renaming rules for <xmlatt>copy-to</xmlatt>.</li> <li><filepath>topicrefElementAttributes.dita</filepath> defines the <xmlatt>copy-to</xmlatt> attribute.</li> <li><filepath>abstract.dita</filepath> refers to the potential for <xmlatt>copy-to</xmlatt> to impose a short description.</li> <li><filepath>shortdesc.dita</filepath> refers to the implication for <xmlatt>copy-to</xmlatt> on the imposition of short descriptions.</li> </ul><p>The non-normative appendix <filepath>interoperability-considerations.dita</filepath> has a section on the implications for <xmlatt>copy-to</xmlatt>. That section can be removed.</p></li> <li>Will the feature require substantial changes to the information architecture of the DITA specification? If so, what?<p>No substantial change.</p></li> <li rev="2.0">If there is new terminology, is it likely to conflict with any usage of those terms in the existing specification?<p>No new terminology.</p></li> </ul> </dd> </dlentry> <dlentry> <dt>Vendors of tools</dt> <dd>Tool vendors will need to adjust their processors to not depend on the use of <xmlatt>copy-to</xmlatt> and, if necessary, provide additional features that give users the appropriate control over deliverable anchors.<draft-comment author="Kristen J Eberlein" time="18 October 2018"> <p>I think we need to make a stronger statement here.</p> </draft-comment></dd> </dlentry> <dlentry> <dt>DITA community-at-large</dt> <dd> <draft-comment author="Kristen J Eberlein" time="18 October 2018"> <p>I think we need to address the potential cost to the DITA community here. We're taking away something that they've used, and we are not replacing it.</p> <p>I agree that we need to get rid of <xmlatt>copy-to</xmlatt>, and that it is not the place of the specification to outline HOW processors should implement replacements of <xmlatt>copy-to</xmlatt>. But I think we need to be scrupulously careful about we present removing <xmlatt>copy-to</xmlatt> to the larger community. </p> <p>We've pledged that we'll do our best to avoid unnecessary disruption. Yes, disruption is necessary here, but I think it means that we have to go to lengths to present this proposal properly.</p> </draft-comment> <ul> <li>Will this feature add to the perception that DITA is becoming too complex?<p>Since we are removing a confusing attribute, it should reduce the perceived complexity.</p></li> <li>Will it be simple for end users to understand?<p>Hard to say as the implications of reuse are always challenging and this change exposes some inherent challenges around managing references to and anchors for reused content. The challenges have always been present (they are inherent in any system that provides DITA's level of reuse) but have not always been obvious.</p></li> <li rev="2.0">If the feature breaks backwards compatibility, how many documents are likely to be affected, and what is the cost of migration?<p>There are probably a fairly large number of documents that use <xmlatt>copy-to</xmlatt>. They will all need to be migrated. In the simple case the migration is a simple use of the <xmlatt>copy-to</xmlatt> value as a <xmlatt>keys</xmlatt> value with a corresponding change to any references to the topic. Some migration scenarios will be more involved, but in those cases it is likely that a deeper consideration of the information architecture was required in any case.</p></li> </ul> </dd> </dlentry> <dlentry> <dt>Producing migration instructions or tools</dt> <dd> <ul> <li>How extensive will migration instructions be, if it is integrated into an overall 1.3 â 2.0 migration publication or white paper?<p>Migration instructions should be fairly short, as evidenced above. They can be included in a migration whitepaper.</p></li> <li>Will this require an independent white paper or other publication to provide migration details?<p>No.</p><draft-comment author="Kristen J Eberlein" time="18 October 2018"> <p>Hmm â Do we need a committee note to:</p> <ul> <li>Outline the use cases for which people are using <xmlatt>copy-to</xmlatt>?</li> <li>Examine samples of DITA markup that uses <xmlatt>copy-to</xmlatt> and suggest alternatives?</li> <li>Be clear about the use cases that cannot be met currently?</li> </ul> </draft-comment></li> <li>Do migration tools need to be created before this change can be made? If so, how complex will those tools be to create and to use?<p>No.</p></li> </ul> </dd> </dlentry> </dl> </section> <section> <title>Examples</title> <p>A general requirement for DITA processors that produce deliverables (HTML, PDF, online help, etc.) is to provide a reliable way to map from aspects of the DITA source to "anchors" in a deliverable generated from the source, where by "anchor" is meant any uniquely-identified thing in the deliverable that can be linked to in some way. Types of anchors include HTML filenames, IDs on elements in HTML, named anchors in PDF, and help IDs. An obvious use of this is the generation of HTML for a publication: once published to the web, users may bookmark specific HTML pages or even specific HTML elements with <xmlatt>id</xmlatt> values. If the HTML filenames or ID values change when the HTML is republished it can be very disruptive to readers who have previously bookmarked those pages. Thus the processor that produces the HTML should do its best to consistently generate result filenames and ID values. The <xmlatt>copy-to</xmlatt> attribute was an early attempt to satisfy this requirement.</p> <p>The relationship between any aspect of the DITA source and the anchors in any deliverable generated from that source is entirely processor dependent. While keys provide a good base for generating anchors (because they have precise uniqueness rules and are controlled entirely by the map author) they are only one of many possible ways of generating reliable deliverable anchors. Processors should provide ways to manage the source-to-anchor mapping.</p> <p>In the following example, documents that use <xmlatt>copy-to</xmlatt> are updated to use <xmlatt>keys</xmlatt> instead, using the name part of the <xmlatt>copy-to</xmlatt> filenames as the keys. This retains the topicref-specific distinctions that <xmlatt>copy-to</xmlatt> was providing. However, it is up to processors to use the <xmlatt>keys</xmlatt> values in some way when generating deliverables. Other ways to capture the original <xmlatt>copy-to</xmlatt> distinction include using the <xmlelement>resourceid</xmlelement> element or processor-specific <xmlelement>data</xmlelement> or a specialization of <xmlelement>data</xmlelement> within the topicrefs' metadata.</p> <p rev="2.0" >Before:<codeblock>Root map: &lt;map> &lt;title>Reused Topics Test 01&lt;/title> &lt;topicref href="reuse_with_copy_to_01.dita"> &lt;topicref href="topic_a.dita"/> &lt;topicref href="topic_b.dita"/> &lt;topicref href="topic_c.dita"/> &lt;topicref href="topic_a.dita"<b> copy-to="topic_a-use-02.dita"</b> > &lt;topicmeta> &lt;navtitle>Topic A Second Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;topicref href="topic_a.dita"<b> copy-to="topic_a-use-03.dita"</b> > &lt;topicmeta> &lt;navtitle>Topic A Third Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;topicref href="topic_a.dita"<b> copy-to="topic_a-use-04.dita"</b> > &lt;topicmeta> &lt;navtitle>Topic A Fourth Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;/topicref> &lt;/map> Topic that links to copy-to versions of topics: &lt;topic id="topic_b"> &lt;title>Topic B&lt;/title> &lt;body> &lt;p>Link to URI "topic_a.dita": &lt;xref href="topic_a.dita"/> &lt;/p> &lt;p>Link to URI "topic_a-use-02.dita": &lt;xref href="topic_a-use-02.dita"/> &lt;/p> &lt;p>Link to URI "topic_a-use-02.dita (no fragment ID)": &lt;xref href="topic_a-use-02.dita"/> &lt;/p> &lt;p>Link to URI "topic_a-use-03.dita": &lt;xref href="topic_a-use-03.dita#topic_a"/> &lt;/p> &lt;p>Link to URI "topic_a-use-04.dita": &lt;xref href="topic_a-use-04.dita#topic_a"/> &lt;/p> &lt;/body> &lt;/topic></codeblock></p> <p rev="2.0">After (<xmlatt>copy-to</xmlatt> replaced with keys, <xmlatt>href</xmlatt> on <xmlelement>xref</xmlelement> replaced by <xmlatt>keyref</xmlatt>):<codeblock>Root map: &lt;map> &lt;title>Reused Topics Test 01&lt;/title> &lt;topicref href="reuse_with_copy_to_01.dita"> &lt;topicref href="topic_a.dita" keys="topic_a"/> &lt;topicref href="topic_b.dita" keys="topic_b"/> &lt;topicref href="topic_c.dita" keys="topic_c"/> &lt;topicref href="topic_a.dita" <b>keys="topic_a-use-02"</b> > &lt;topicmeta> &lt;navtitle>Topic A Second Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;topicref href="topic_a.dita" <b>keys="topic_a-use-03"</b> > &lt;topicmeta> &lt;navtitle>Topic A Third Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;topicref href="topic_a.dita" <b>keys="topic_a-use-04"</b> > &lt;topicmeta> &lt;navtitle>Topic A Fourth Use&lt;/navtitle> &lt;/topicmeta> &lt;/topicref> &lt;/topicref> &lt;/map> Topic that links to specific uses of topic_a: &lt;topic id="topic_b"> &lt;title>Topic B&lt;/title> &lt;body> &lt;p>Link to key "topic_a": &lt;xref <b>keyref="topic_a"</b>/> &lt;/p> &lt;p>Link to key "topic_a-use-02": &lt;xref <b>keyref="topic_a-use-02"</b>/> &lt;/p> &lt;p>Link to key "topic_a-use-03": &lt;xref <b>keyref="topic_a-use-03"</b>/> &lt;/p> &lt;p>Link to key "topic_a-use-04": &lt;xref <b>keyref="topic_a-use-04"</b>/> &lt;/p> &lt;/body> &lt;/topic></codeblock></p> </section> <section> <title>Examples</title> <p>This section contains examples of DITA 1.3 code that uses <xmlatt>copy-to</xmlatt> and DITA 2.0 code that uses <xmlatt>keys</xmlatt> and <xmlatt>keyref</xmlatt> instead.</p> <fig> <title>DITA 1.3 source that uses <xmlatt>copy-to</xmlatt> to generate unique output when a topic is referenced multiple times</title> <p>The following code sample illustrates how an information architect used the <xmlatt>copy-to</xmlatt> attribute to ensure that a unique HTML file is are generated for each use of the <filepath>install-info.dita</filepath> topic. The information architect's intent is to ensure that correct "Parent topic," "Previous topic," and "Next topic" links are rendered in the HTML output.</p> <codeblock>&lt;map> &lt;title>Installation instructions for Windows, Linux, and macOS&lt;/title> &lt;topicref href="installing-windows.dita> &lt;topicref href="install-info.dita/> &lt;topicref href="installing-dbase-windows.dita/> ... &lt;/topicref> &lt;topicref href="installing-linux.dita> &lt;topicref href="install-info.dita copy-to="install-info-linux.dita"/> &lt;topicref href="installing-dbase-linux.dita/> ... &lt;/topicref> &lt;topicref href="installing-macos.dita> &lt;topicref href="install-info.dita copy-to="install-info-macos.dita"/> &lt;topicref href="installing-macos-linux.dita/> ... &lt;/topicref></codeblock> </fig> <fig> <title>DITA 2.0 source with replacement markup for <xmlatt>copy-to</xmlatt></title> <p> <draft-comment author="Kristen J Eberlein" time="20 October 2019"> <p>Eliot, how do yousuggest that this would be handled?</p> </draft-comment> </p> </fig> </section> </refbody> </reference><?Pub Caret -3?> <?Pub *0000003625?>