From 352e1855c64610470153d5f22d54489772f95f82 Mon Sep 17 00:00:00 2001 From: Robert D Anderson Date: Tue, 8 Oct 2024 09:29:03 -0500 Subject: [PATCH] Review comments from conref arch spec review --- .../archSpec/base/conref-overview.dita | 17 +++++++------- specification/archSpec/base/conref.dita | 10 ++++----- .../archSpec/base/ditauseconreftarget.dita | 17 +++++++------- .../archSpec/base/theconactionattribute.dita | 16 +++++++------- .../archSpec/base/theconkeyrefattribute.dita | 15 ++++++------- .../archSpec/base/theconrefattribute.dita | 22 +++++++++---------- .../archSpec/base/theconrefendattribute.dita | 10 ++++----- ...ta-2.0-specification-subjectScheme.ditamap | 1 + 8 files changed, 54 insertions(+), 54 deletions(-) diff --git a/specification/archSpec/base/conref-overview.dita b/specification/archSpec/base/conref-overview.dita index 32df80c9..8ecb44d3 100644 --- a/specification/archSpec/base/conref-overview.dita +++ b/specification/archSpec/base/conref-overview.dita @@ -1,7 +1,7 @@ - <ph >Conref overview</ph> + <ph rev="review-ella">Content referencing</ph> overview @@ -18,17 +18,18 @@ as defined in .

-
Pulling content to the referencing element
+
Pulling content into the referencing element

When the conref or conkeyref attribute is used alone, - the referencing element acts as a placeholder for the referenced element, and the - content of the referenced element is rendered in place of the referencing element.

+ the referencing element acts as a placeholder for the referenced element. The content of the referenced element is rendered in place of the + referencing element.

The combination of the conrefend attribute with either conref or conkeyref specifies a range of elements - that is rendered in place of the referencing element. Although - the start and end elements must be of the same type as the referencing element (or - specialized from that element type), the elements inside the range can be any - type.

+ that is rendered in place of the referencing element. The start + and end elements in a range must be siblings. Although the start and end elements + must be of the same type as the referencing element (or specialized from that element + type), the elements inside the range can be any type.

 diff --git a/specification/archSpec/base/conref.dita b/specification/archSpec/base/conref.dita index f11d3ae8..e3277460 100644 --- a/specification/archSpec/base/conref.dita +++ b/specification/archSpec/base/conref.dita @@ -2,11 +2,10 @@ Content <ph >reference</ph> (conref) - The DITA conref attributes provide mechanisms for reusing content. DITA content - references support reuse scenarios that are difficult or impossible to implement using many - XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content references - have rules that help ensure that the results of content inclusion remain valid after - resolution + The DITA conref attributes are mechanisms that enable effective + content reuse. DITA content references support complex reuse scenarios that are otherwise + challenging or impossible to achieve. In addition, DITA content references have rules to ensure + that the content is valid DITA after the content reference has been resolved. @@ -16,4 +15,5 @@ + diff --git a/specification/archSpec/base/ditauseconreftarget.dita b/specification/archSpec/base/ditauseconreftarget.dita index cadf6a3a..c558bcc1 100644 --- a/specification/archSpec/base/ditauseconreftarget.dita +++ b/specification/archSpec/base/ditauseconreftarget.dita @@ -1,6 +1,6 @@ - - + + Using the <keyword>-dita-use-conref-target</keyword> value The value -dita-use-conref-target is available on enumerated attributes and can also be specified on other attributes. When an element uses @@ -15,14 +15,13 @@ - -
+ This topic is moving into the arch spec, but needs further editing to split overview / conceptual info from processing info; this and other conref-attribute topics currently have a bunch of processing info that is missing from the actual "Processing conref" arch spec topics. -
-

Ordinarily, when an element uses conref, any other + +

Ordinarily, when an element uses conref, any other attributes specified locally will be preserved when the reference is resolved. This causes problems when attributes are required, because required attributes must be specified regardless of whether the conref attribute is present. The purpose of the @@ -37,7 +36,7 @@ tgroup. However, the token is not allowed for the id attribute on the topic element, because "-dita-use-conref-target" does not fit the syntax required by the XML grammar - files.

+ files.

This example shows a DITA map where the topichead element uses conref. It specifies the deliveryTarget attribute as @@ -90,5 +89,5 @@ - - + + diff --git a/specification/archSpec/base/theconactionattribute.dita b/specification/archSpec/base/theconactionattribute.dita index 0b11ef69..a5e384ea 100644 --- a/specification/archSpec/base/theconactionattribute.dita +++ b/specification/archSpec/base/theconactionattribute.dita @@ -1,7 +1,7 @@ - - + + The <xmlatt>conaction</xmlatt> attribute The conaction attribute allows users to push content from one location into another. It causes the conref attribute to work in reverse, so that @@ -14,8 +14,8 @@ - -

In the descriptions below, the word target always refers to the element referenced by a + +In the descriptions below, the word target always refers to the element referenced by a conref attribute.

There are three possible functions using the conaction attribute: replacing an element, pushing content before an element, and pushing content after an element. The conaction attribute always declares the desired function while the @@ -36,7 +36,7 @@ not legal to push a list item (li) in order to replace a step, because the list item allows many items that are not valid in the specialized context. -

+
Replacing content in another topic

When the conaction attribute is set to pushreplace, the @@ -120,6 +120,6 @@ was not addressed in the original proposal.--> application can recover by warning the user, ignoring the conrefend attribute, or with some other implementation strategy.

- - + + diff --git a/specification/archSpec/base/theconkeyrefattribute.dita b/specification/archSpec/base/theconkeyrefattribute.dita index 20768d37..a664589d 100644 --- a/specification/archSpec/base/theconkeyrefattribute.dita +++ b/specification/archSpec/base/theconkeyrefattribute.dita @@ -1,7 +1,7 @@ - - + + The <xmlatt>conkeyref</xmlatt> attribute The conkeyref attribute provides an indirect content reference to topic elements, map elements, or elements within maps or topics. It allows the referencing @@ -13,8 +13,7 @@ - -
+

When the target of a content reference is an element within a topic or map, the value of the conkeyref attribute is a key name, followed by a slash ("/"), followed by the ID of the referenced element. The key name must be bound to the topic or map that @@ -32,6 +31,6 @@ by the conrefend attribute. See for more information and for examples of this behavior.

-
- - + + + diff --git a/specification/archSpec/base/theconrefattribute.dita b/specification/archSpec/base/theconrefattribute.dita index 721c3573..65cce28a 100644 --- a/specification/archSpec/base/theconrefattribute.dita +++ b/specification/archSpec/base/theconrefattribute.dita @@ -1,7 +1,7 @@ - - + + The <xmlatt>conref</xmlatt> attribute The conref attribute is used to reference content that can be reused. It allows reuse of DITA elements, including topic or map level elements. @@ -12,16 +12,16 @@ - -

The value of the conref attribute is a URI reference to a DITA element. See + +

The value of the conref attribute is a URI reference to a DITA element. See for details on specifying URI references to DITA elements. As with other DITA references, a conref attribute that references a resource without an ID is treated as a reference to the first topic or map in the document.

When using the conref attribute on an element, the content of that element is - ignored. For example, if a phrase is marked up like - this:<ph conref="#topic/ph">Something</ph> the - word "Something" will be replaced by the content of the referenced - ph element.
- - + ignored by processors. For example, if a phrase is marked up like + this:<ph conref="#topic/ph">Something</ph> the word "Something" + will be replaced by the content of the referenced ph + element. + + diff --git a/specification/archSpec/base/theconrefendattribute.dita b/specification/archSpec/base/theconrefendattribute.dita index 476b3130..166627a0 100644 --- a/specification/archSpec/base/theconrefendattribute.dita +++ b/specification/archSpec/base/theconrefendattribute.dita @@ -1,6 +1,6 @@ - - + + The <xmlatt>conrefend</xmlatt> attribute The conrefend attribute is used when referencing a range of elements with the conref mechanism. The conref or conkeyref attribute @@ -13,7 +13,7 @@ - +
Using <xmlatt>conref</xmlatt> together with <xmlatt>conrefend</xmlatt>

The following markup rules apply when using or implementing conrefend:

    @@ -74,5 +74,5 @@ the conref attribute itself is not present for fallback, the conrefend attribute is ignored.

- - + + diff --git a/specification/dita-2.0-specification-subjectScheme.ditamap b/specification/dita-2.0-specification-subjectScheme.ditamap index 982f0b2a..8b2b4e5d 100644 --- a/specification/dita-2.0-specification-subjectScheme.ditamap +++ b/specification/dita-2.0-specification-subjectScheme.ditamap @@ -64,6 +64,7 @@ +