From 90fa74375f8d55d321cfb1c6d49b6c1f39d587e7 Mon Sep 17 00:00:00 2001 From: Kristen James Eberlein Date: Mon, 26 Aug 2024 08:09:48 -0400 Subject: [PATCH] Updates based on Review Dave Alvin --- ...index-range-defined-in-a-topic-prolog.dita | 2 +- ...example-index-range-in-a-single-topic.dita | 21 +++--- .../archSpec/base/index-elements.dita | 20 +++--- .../archSpec/base/index-overview.dita | 64 +++++++++++-------- specification/archSpec/base/index-ranges.dita | 15 +++-- specification/archSpec/base/indexes.dita | 4 +- specification/archSpec/base/indexes.ditamap | 1 - .../base/location-of-indexterm-elements.dita | 7 +- ...ta-2.0-specification-subjectScheme.ditamap | 1 + specification/resources/DITA2.0-spec.ditaval | 2 +- 10 files changed, 75 insertions(+), 62 deletions(-) diff --git a/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita b/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita index 9be63ead..13ffd3ee 100644 --- a/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita +++ b/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita @@ -29,7 +29,7 @@ <metadata> <keywords> <indexterm start="acct">accounting</indexterm> - <indexterm end="acct">accounting</indexterm> + <indexterm end="acct"/> </keywords> </metadata> </prolog> diff --git a/specification/archSpec/base/example-index-range-in-a-single-topic.dita b/specification/archSpec/base/example-index-range-in-a-single-topic.dita index e824429c..77379d8e 100644 --- a/specification/archSpec/base/example-index-range-in-a-single-topic.dita +++ b/specification/archSpec/base/example-index-range-in-a-single-topic.dita @@ -1,17 +1,14 @@ - Example: Index range defined in a single topic - In this scenario, an index range is defined directly in the - body of a - topic. - -

In the following code sample, the index range begins at the - start of the second paragraph and continues to the beginning of the - last - paragraph.

- - <topic id="accounting"> + Example: Index range defined in a single topic + In this scenario, an index range is defined directly in the + body of a topic. + +

In the following code sample, the index range begins at the start of + the second paragraph and continues to the beginning of the last + paragraph.

+ <topic id="accounting"> <title>Accounting regulations</title> <body> <p>Be ethical in your accounting.</p> @@ -21,5 +18,5 @@ </body> <!-- Potential sub-topics --> </topic> - + diff --git a/specification/archSpec/base/index-elements.dita b/specification/archSpec/base/index-elements.dita index 0527f383..df811300 100644 --- a/specification/archSpec/base/index-elements.dita +++ b/specification/archSpec/base/index-elements.dita @@ -2,11 +2,12 @@ Index elements - The content of indexterm elements - provides the text for the entries in an - index. indexterm elements can be nested - to create additional levels of indexing, such - as secondary and tertiary index entries. + The contents of + indexterm elements provides the text for the + entries in an index. + indexterm elements can be nested to create + additional levels of indexing, such as + secondary and tertiary index entries. @@ -29,10 +30,11 @@
indexterm
Defines a term or subject that - can contribute to an index. The start and - end attributes on the - indexterm element specify index - ranges.
+ can contribute to an index. + Matching values of + start and end attributes on + indexterm elements can specify an + index range.
index-see
diff --git a/specification/archSpec/base/index-overview.dita b/specification/archSpec/base/index-overview.dita index da171e7b..fd5e3c8a 100644 --- a/specification/archSpec/base/index-overview.dita +++ b/specification/archSpec/base/index-overview.dita @@ -1,26 +1,29 @@ - - Index overview - DITA provides several elements to enable indexing. Whether and how an index is - rendered will vary based on implementation decisions and rendering formats. - + + Index overview + DITA provides several elements to enable indexing. Whether and + how an index is rendered will vary based on implementation decisions + and rendering formats. +

Here are some definitions:

  • An index is a mapping from indexterm elements to locations in the DITA content.
    • -
  • A generated index is a mapping of index terms to rendered locations.
    • +
  • A generated index is a mapping of index terms to + rendered locations.
-

While DITA provides several elements that support indexing, how those elements are used - will vary by implementation.

-
    +

    While DITA provides several elements that support indexing, how + those elements are used will vary by implementation.

    +
    • A publishing format like PDF might use a back-of-the-book style index with page numbers, which typically involves merging index - elements and rendering with page numbers.
      • -
    • Another publishing format might have no rendered index at all, - but instead use the index element content to help weight search - results.
      • + elements and generating page + numbers. +
    • Another publishing format might have no rendered index, but it + would instead use the content of index elements to help weight + search results.
    • Some implementations might choose to supplement a generated index with additional content, such as treating a specialized keyword element as both normal content @@ -29,29 +32,34 @@ cases, based on either implementation capabilities or style preferences.
    -

    While DITA itself defines markup for indexing and specifies - exactly what point an indexterm refers to, - it cannot force DITA documents to use consistent patterns that work - for all formats. Implementations should consider what edge cases are - relevant and how to treat them when rendering.

    -

    The following list includes some of the conditions that +

    While DITA defines markup for indexing and specifies exactly the + point to which an indexterm refers, it + cannot force DITA documents to use consistent patterns that work for + all formats. Implementations should + consider edge cases and how to treat them.

    +

    The following list includes some of the conditions that implementations might want to be aware of when considering how to generate an index:

      -
    • Index processors typically ignore leading or trailing - whitespace characters.
      • +
    • Index processors typically ignore leading and trailing whitespace + characters.
    • Processors might want to treat two entries separately if they - are defined with different cases.
      • + are defined with different capitalization.
    • Processors need to determine how to handle nested markup, such - as keyword, within an index entry.
      • + as an keyword + element that is located within an + indexterm element.
    • Because index-see is used to refer to a term that is used instead of the current entry, processors should consider how to handle a case where an index term is used both as a page locator and with an - index-see for redirection.
      • -
    • Similarly, processors should consider how to handle a case - where an index term is defined with both an - index-see and an + index-see + element for redirection.
      • +
    • Similarly, processors should consider how to handle the case where an index term is + defined with both an index-see and an index-see-also element.

    - + diff --git a/specification/archSpec/base/index-ranges.dita b/specification/archSpec/base/index-ranges.dita index 9df2a522..03089176 100644 --- a/specification/archSpec/base/index-ranges.dita +++ b/specification/archSpec/base/index-ranges.dita @@ -3,9 +3,11 @@ Index ranges Authors can use the start and - end attributes on indexterm - elements to index an extended discussion. - The generated index entry reflects the span + end attributes on a pair + of + indexterm elements to index an extended discussion. The generated index entry reflects the span between the two indexterm elements . @@ -21,12 +23,15 @@ indexterm with a start attribute. This is called a start-of-range element.

    -

    The end of an index range is indicated by an +

    The end of an index range is indicated by an indexterm element with an end attribute with a value that matches the start attribute on the start element. This is called an end-of-range element.

    + >end-of-range element. + End-of-range element should contain no + content or nested elements. +

    The location of the indexterm elements determines how the span is defined:

    diff --git a/specification/archSpec/base/indexes.dita b/specification/archSpec/base/indexes.dita index b76b888f..d542603f 100644 --- a/specification/archSpec/base/indexes.dita +++ b/specification/archSpec/base/indexes.dita @@ -2,6 +2,6 @@ Indexes - Processors can generate an index from the content of indexing elements. - + Processors can generate indexes from the content of indexing elements. diff --git a/specification/archSpec/base/indexes.ditamap b/specification/archSpec/base/indexes.ditamap index 13b1500d..b30255f3 100644 --- a/specification/archSpec/base/indexes.ditamap +++ b/specification/archSpec/base/indexes.ditamap @@ -11,7 +11,6 @@ - diff --git a/specification/archSpec/base/location-of-indexterm-elements.dita b/specification/archSpec/base/location-of-indexterm-elements.dita index b9abf2bd..578fd53f 100644 --- a/specification/archSpec/base/location-of-indexterm-elements.dita +++ b/specification/archSpec/base/location-of-indexterm-elements.dita @@ -26,9 +26,10 @@
    Anywhere else in a DITA topic
    -
    An indexterm element that is located in a topic (and - not the topic prolog) is a point reference to the location where the - indexterm element occurs.
    +
    An indexterm element that is + located in a topic (and not in + the topic prolog) is a point reference to the location where the + indexterm element occurs.
    DITA maps
    diff --git a/specification/dita-2.0-specification-subjectScheme.ditamap b/specification/dita-2.0-specification-subjectScheme.ditamap index 3bf855dc..982f0b2a 100644 --- a/specification/dita-2.0-specification-subjectScheme.ditamap +++ b/specification/dita-2.0-specification-subjectScheme.ditamap @@ -63,6 +63,7 @@ + diff --git a/specification/resources/DITA2.0-spec.ditaval b/specification/resources/DITA2.0-spec.ditaval index c87f9b46..16dd8ddc 100644 --- a/specification/resources/DITA2.0-spec.ditaval +++ b/specification/resources/DITA2.0-spec.ditaval @@ -129,5 +129,5 @@ - +