[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Stage 3 Proposal: Issue 33, Remove @copy-to
The stage 3 proposal for issue 33, Remove @copy-to, has been passed by all the reviewers. I couldn't figure out how to upload it to the new Oasis documents area so the PDF and HTML as well as the source DITA are attached. The PDF is not really useful (because of the table layout) but the HTML is good or the DITA source, of course. The DITA source is committed on the Stage 3 branch in the TC SVN repo. The biggest new thing since this was discussed at Stage 2 is additional rules for the application of DITAVAL ref resource prefix and suffix to @appid values. Basically, where dvrResourcePrefix/Suffix apply to the effective @copy-to value in DITA 1.x, they now apply to the effective @appid value. Cheers, E. -- Eliot Kimber http://contrext.com
Attachment:
Stage-3-Issue33-DeprecateOrRemoveCopyTo.pdf
Description: Adobe PDF document
Remove the @copy-to attribute, replace with enhancements to the
<resourceid> element.
Eliot Kimber
| Event | Date | Links |
|---|---|---|
| Stage 1 proposal accepted | 30 May 2017 | https://lists.oasis-open.org/archives/dita/201706/msg00013.html |
| Stage 2 proposal submitted | 13 Dec 2020 | PDF: https://www.oasis-open.org/apps/org/workgroup/dita/download.php/68220/Issue33-DeprecateOrRemoveCopyTo.pdf |
| Stage 2 proposal discussed | 15 Dec 2020 | https://lists.oasis-open.org/archives/dita/202012/msg00028.html |
| Stage 2 proposal approved | 2 Feb 2021 | https://lists.oasis-open.org/archives/dita/202102/msg00010.html |
| Stage 3 proposal submitted to reviewers | 15 March 2021 | Robert Anderson, Chris Nitchie, Eric Sirois |
| Stage 3 proposal (this document) submitted to TC | 3 May 2021 | Â |
@copy-to attribute involves the following changes to
the DITA markup design:@copy-to from all elements@appid-role attribute to
<resourceid>@appid-role token
deliverable-anchorNo direct dependent or interrelated proposals.
| mapGroupDomain.rng (before) | mapGroupDomain.rng (after) |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| mapGroup.mod (before) | mapGroup.mod (after) |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| mapMod.rng (before) | mapMod.rng (after) |
|---|---|
|
|
| map.mod (before) | map.mod (after) |
|---|---|
|
|
| subjectSchemeMod.rng (before) | subjectSchemeMod.rng (after_ |
|---|---|
|
|
|
|
| subjectScheme.mod (before) | subjectScheme.mod (after) |
|---|---|
|
|
|
|
| metaDeclMod.rng (before) | metaDeclMod.rng (after) |
|---|---|
|
|
| metaDecl.mod (before) | metaDecl.mod (after) |
|---|---|
|
|
No new or modified terminology.
|
Maps that use @copy-to will need to be migrated. Migration actions may
include:
@copy-to attributes must be removed.Topicrefs that use @copy-to will likely need to add one or more
<resourceid> elements with an @appid-role of
"deliverable-anchor".
Alternatively, the topic to which the @copy-to applied could be
literally copied in the source repository and the topicref updated to refer to the new
copy. This would allow existing direct URI references to the @copy-to
value to continue to work as they have.
<resourceid> elements to topic references or to topics in
order to assign deliverable anchors to the uses of a topic (when used within topic
references) or to a topic without regard to use context (when used within a topic's
prolog).Processors that depend on or expect the use of @copy-to, for example to
signal the generation of distinct artifacts from that use of a topic, will need to implement
the new @appid-role attribute.
Existing specialization and constrain modules that declare the @copy-to
attribute will need to remove the attribute declaration.
Specialization and constraint modules that extend or constrain
<resourceid> may need to be updated to reflect the new
@appid-role attribute.
<resourceid> with an
@appid-role of
"delivable-anchor"
to determine deliverable URIs.<resourceid>A resource ID provides an identifier for applications that must use their own identifier scheme, such as context-sensitive help systems and databases.
The @appid and @appname attributes are available to
associate an ID or deliverable anchor component with an application. Multiple
@appid values can be associated with a single @appname
value, and multiple @appname values can be associated with a single
@appid value. Because the values for the @appid and
@appname attributes work in combination to specify a specific ID for a
specific application, each combination of values for the @appid and
@appname attributes should be unique within the context of a single
root map. The @appid attribute contributes to deliverable anchors
while @ux-context-string specifies an exact context-sensitive help
context
identifier.
Effective @appid values reflect the application of any resource prefix
or suffix values from <ditavalref>
elements.
Processors determine which <resourceid> elements apply to them,
normally by examining the @appname value, if present. Processors are
free to assume that a <resourceid> element with no
@appname attribute applies to them. Normal filtering can also be used
to control which resource IDs are used for a given deliverable, i.e., filtering on
@deliveryTarget.
When the @appid-role value is "deliverable-anchor", the resource ID is
intended to contribute to the effective anchor URI of the resource as delivered in the
deliverables to which the resource ID applies, i.e., the base part of an HTML filename,
a URI fragment identifier, a PDF anchor name, etc. Processors MAY choose to use IDs with
the role "context-sensitive-help" to construct deliverable anchors in any kind of
deliverable. A given deliverable component MAY have any number of anchors associated
with it if the deliverable provides for multiple anchors (for example, a single topic
might get multiple anchors in a PDF and multiple <a> elements
with different @id values in an HTML deliverable).
When @appid-role is "deliverable-anchor", processors that accept the
<resourceid> element as applying to them
SHOULD
use the @appid value when constructing a delivery URI for the resource.
The details of how a processor uses @appid values in the construction of
URIs is processor dependent. However the resulting URI SHOULD reflect as much as
possible the original @appid in such a way that one can reasonably go
from the URI to the <resourceid> element that may have
contributed to it.
Processors MAY use other properties of the referenced resource or of the reference to the resource to construct full deliverable anchors, for example, using key scope names, key names, or source filenames to construct unique anchor values. Processors SHOULD clearly document the algorithms used to construct anchors.
To the greatest degree possible, processors SHOULD ensure that a resource ID used for the same resource and produced as the same deliverable type from the same DITA source, filtering conditions, and processor settings, will result in the same deliverable URI. This should always be true for the same version in time of the DITA source and should be true for closely-related different versions in time of the same source. For example, producing a deliverable from a new version of the DITA source where the source was revised but large structural changes were not made should result in the same deliverable URIs as for the previous version if at all possible.
The intent of these expectations is to encourage the stability of deliverable URIs over time as well as to make it possible, if not easy, to correlate URIs in deliverables back to the resource IDs from which they were derived.
The following attributes are available on this element: and the attributes defined below.
@appname@appid@appid when @appid-role is
"deliverable-anchor" SHOULD be limited to values that can contribute to any of the
following URI components:@appid values SHOULD NOT contain multiple URI path
components.@appid values should avoid specifying
deliverable-specific aspects of URIs such as filename extensions. For example, for
a targeted deliverable that produces HTML files as its primary deliverable
component, @appid values should specify only the base filename for
the delivered files, i.e., "installation-guide" not
"installation-guide.html".@appid values as
general-purpose as possible.@appid-role@appid-role values, If not specified, the effective value of
@appid-role is "context-sensitive-help". Applications MUST
recognize the following values:@appid value
SHOULD
be used to construct anchors for the associated resource in any deliverables
associated with the <resourceid>.@appid value SHOULD be used in connecting the associated
resource with application components that use the resource as context
sensitive help.@ux-context-string@ux-source-prioritySpecifies precedence for handling <resourceid> definitions
that exist in both a map and a topic. This attribute only is valid when used
within a <topicref> element in a map. The allowable
values are -dita-use-conref-target and the
following:
@ux-windowref@name attribute on the
<ux-window> element that is used to display the topic when
called from a help API.In the following example, user-assistance context hooks are applied to three topics that are referenced from a DITA map. The second topic has two hooks for the same topic.
<map title="Widget Help">
<topicref href="" type="concept">
<topicref href="" type="task">
<topicmeta>
<resourceid appname="ua" appid="1234" ux-context-string="idh_filesave"
ux-source-priority="topic-only" />
</topicmeta>
</topicref>
<topicref href="" type="task">
<topicmeta>
<resourceid appname="ua"
appid="2345" ux-context-string="idh_filedelete" />
<resourceid appname="ua"
appid="6789" ux-context-string="idh_filekill" />
</topicmeta>
</topicref>
<topicref href="" type="task">
<topicmeta>
<resourceid appname="ua"
appid="5432" ux-context-string="idh_fileedit" ux-windowref="csh" />
</topicmeta>
</topicref>
</topicref>
</map>In the following example, a user-assistance context hook is defined in the prolog of a
task topic. The context hook is made up of a context ID (value for
@appid attribute) and a context string (value for
@ux-context-string attribute). A user-assistance window profile also
is referenced for this topic.
<task id="fedt">
<title>Editing a File</title>
<prolog>
<resourceid appname="ua"
appid="5432" ux-context-string="idh_fileedit" ux-windowref="csh" />
</prolog>
<taskbody>
<context>After you have created a new file, you can edit it.</context>
<steps>
<step><cmd>Open...</cmd></step>
<step><cmd>Edit...</cmd></step>
<step><cmd>Save...</cmd></step>
</steps>
</taskbody>
</task><map>
...
<topicref keyscope="model-01" keys="operation" keyref="topic-0100">
...
<topicref keys="replace-cartridge" keyref="topic-0014">
<topicmeta>
<resourceid appid="replace_cartridge_model_01"
appid-role="deliverable-anchor"
/>
</topicmet>
</topicref>
...
</topicref>
<topicref keyscope="model-02" keys="operation" keyref="topic-0200">
...
<topicref keys="replace-cartridge" keyref="topic-0014">
<topicmeta>
<resourceid appid="replace_cartridge_model_02"
appid-role="deliverable-anchor"
/>
</topicmet>
</topicref>
...
</topicref>
...
</map>For this content the HTML deliverable might generate two HTML files for the "replace
cartridge" topic with the names "replace_cartridge_model_01.html" and
"replace_cartridge_model_02.html" and for PDF the PDF anchors might just be the
@appid values (as PDF anchors are just unique strings).
@appid values:<map>
...
<topicref keyscope="model-01" keys="operation" keyref="topic-0100">
...
<topicref keys="replace-cartridge" keyref="topic-0014">
<topicmeta>
<resourceid appid="replace_cartridge"
appid-role="deliverable-anchor"
/>
</topicmet>
</topicref>
...
</topicref>
<topicref keyscope="model-02" keys="operation" keyref="topic-0200">
...
<topicref keys="replace-cartridge" keyref="topic-0014">
<topicmeta>
<resourceid appid="replace_cartridge"
appid-role="deliverable-anchor"
/>
</topicmet>
</topicref>
...
</topicref>
...
</map>This approach requires that the processors implement the use of key scope names to construct deliverable anchors, making it less general over all but more convenient for authors.
<resourceid> elements from the topicrefs into the topic
itself:<topic id="topic-0200">
<title>Replace the cartridge</title>
<topicmeta>
<resourceid appid="replace_cartridge"
appid-role="deliverable-anchor"
/>
</topicmeta>
...
</topic>The topic now specifies a base resource ID that, when combined with any applicable key scopes, should result in use-specific deliverable anchors without the need to specify the resource IDs in the referencing maps.
Attachment:
Stage-3-Issue33-DeprecateOrRemoveCopyTo.dita
Description: Binary data
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]