[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Eberlein review of removing @copy-to proposal
| 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 ...
<?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="<p><b>General Requirements</b></p>"?>
<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="<note type="important">This section must be complete in order for the proposal to be approved.</note>"?>
<?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:
<map>
<title>Reused Topics Test 01</title>
<topicref href="reuse_with_copy_to_01.dita">
<topicref href="topic_a.dita"/>
<topicref href="topic_b.dita"/>
<topicref href="topic_c.dita"/>
<topicref href="topic_a.dita"<b> copy-to="topic_a-use-02.dita"</b> >
<topicmeta>
<navtitle>Topic A Second Use</navtitle>
</topicmeta>
</topicref>
<topicref href="topic_a.dita"<b> copy-to="topic_a-use-03.dita"</b> >
<topicmeta>
<navtitle>Topic A Third Use</navtitle>
</topicmeta>
</topicref>
<topicref href="topic_a.dita"<b> copy-to="topic_a-use-04.dita"</b> >
<topicmeta>
<navtitle>Topic A Fourth Use</navtitle>
</topicmeta>
</topicref>
</topicref>
</map>
Topic that links to copy-to versions of topics:
<topic id="topic_b">
<title>Topic B</title>
<body>
<p>Link to URI "topic_a.dita":
<xref href="topic_a.dita"/>
</p>
<p>Link to URI "topic_a-use-02.dita":
<xref href="topic_a-use-02.dita"/>
</p>
<p>Link to URI "topic_a-use-02.dita (no fragment ID)":
<xref href="topic_a-use-02.dita"/>
</p>
<p>Link to URI "topic_a-use-03.dita":
<xref href="topic_a-use-03.dita#topic_a"/>
</p>
<p>Link to URI "topic_a-use-04.dita":
<xref href="topic_a-use-04.dita#topic_a"/>
</p>
</body>
</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:
<map>
<title>Reused Topics Test 01</title>
<topicref href="reuse_with_copy_to_01.dita">
<topicref href="topic_a.dita" keys="topic_a"/>
<topicref href="topic_b.dita" keys="topic_b"/>
<topicref href="topic_c.dita" keys="topic_c"/>
<topicref href="topic_a.dita" <b>keys="topic_a-use-02"</b> >
<topicmeta>
<navtitle>Topic A Second Use</navtitle>
</topicmeta>
</topicref>
<topicref href="topic_a.dita" <b>keys="topic_a-use-03"</b> >
<topicmeta>
<navtitle>Topic A Third Use</navtitle>
</topicmeta>
</topicref>
<topicref href="topic_a.dita" <b>keys="topic_a-use-04"</b> >
<topicmeta>
<navtitle>Topic A Fourth Use</navtitle>
</topicmeta>
</topicref>
</topicref>
</map>
Topic that links to specific uses of topic_a:
<topic id="topic_b">
<title>Topic B</title>
<body>
<p>Link to key "topic_a":
<xref <b>keyref="topic_a"</b>/>
</p>
<p>Link to key "topic_a-use-02":
<xref <b>keyref="topic_a-use-02"</b>/>
</p>
<p>Link to key "topic_a-use-03":
<xref <b>keyref="topic_a-use-03"</b>/>
</p>
<p>Link to key "topic_a-use-04":
<xref <b>keyref="topic_a-use-04"</b>/>
</p>
</body>
</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><map>
<title>Installation instructions for Windows, Linux, and macOS</title>
<topicref href="installing-windows.dita>
<topicref href="install-info.dita/>
<topicref href="installing-dbase-windows.dita/>
...
</topicref>
<topicref href="installing-linux.dita>
<topicref href="install-info.dita copy-to="install-info-linux.dita"/>
<topicref href="installing-dbase-linux.dita/>
...
</topicref>
<topicref href="installing-macos.dita>
<topicref href="install-info.dita copy-to="install-info-macos.dita"/>
<topicref href="installing-macos-linux.dita/>
...
</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?>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]