Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update subject scheme for index review #934

Merged
merged 3 commits into from
Aug 13, 2024
Merged

Update subject scheme for index review #934

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b81760f
Update subject scheme for index review
robander Jul 8, 2024
dae50cf
Review comment updates to indexing topics
robander Jul 20, 2024
1897ba0
Update subject scheme, remove obsolete index content
robander Jul 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions specification/archSpec/base/index-elements.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
<title>Index elements</title>
<shortdesc>The content of <xmlelement>indexterm</xmlelement> elements provides the text for the
entries in a generated index. <xmlelement>indexterm</xmlelement> elements can be nested to
create secondary and tertiary index entries. </shortdesc>
create <ph rev="review-chenier">additional levels of indexing, such as</ph> secondary and
tertiary index entries. </shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -21,29 +22,30 @@
</metadata>
</prolog>
<conbody>
<p>The following elements contain information that processors use to generate indexes.</p>
<p>The following elements contain information that processors <ph rev="review-chenier"
>can</ph> use to generate indexes.</p>
<dl>
<dlentry>
<dt><xmlelement>indexterm</xmlelement></dt>
<dd>Instructs a processor to generate an index entry. The <xmlatt>start</xmlatt> and
<xmlatt>end</xmlatt> attributes on the <xmlelement>indexterm</xmlelement>
element can specify index ranges.</dd>
<dd><ph rev="review-chenier">Defines a term or subject that can contribute to an
index.</ph> The <xmlatt>start</xmlatt> and <xmlatt>end</xmlatt> attributes
on the <xmlelement>indexterm</xmlelement> element can specify index ranges.</dd>
</dlentry>
<dlentry>
<dt><xmlelement>index-see</xmlelement></dt>
<dd rev="review-1">Instructs a processor to generate a <term>see reference</term>.
See references direct a reader to the preferred term.</dd>
<dd rev="review-1"><ph rev="review-chenier">Defines a term or subject to use as a
<term>see reference</term>.</ph> See references direct a reader to the
preferred term.</dd>
</dlentry>
<dlentry>
<dt><xmlelement>index-see-also</xmlelement></dt>
<dd rev="review-1">Instructs a processor to generate a <term>see also
reference</term>. See also references direct a reader to an alternate index
entry for additional information.</dd>
<dd rev="review-1"><ph rev="review-chenier">Defines a term or subject to use as a
<term>see also reference</term>.</ph> See also references direct a
reader to an alternate index entry for additional information.</dd>
</dlentry>
</dl>
<p>How the index elements are combined, the location of <xmlelement>indexterm</xmlelement>
elements, and the hierarchy of the DITA maps all affect how the index elements are
processed and the resulting generated index entries.</p>
<!--<draft-comment author="Joyce Lam" time="09 August 2019"><p>For clarity, I recommend writing this using an unordered list.</p><p>How the index elements are processed and the resulting generated index entries are effected by</p><ul><li>how the index elements are combined</li><li>the location of &lt;indexterm> elements, and</li><li>the hierarchy of the DITA maps.</li></ul></draft-comment>-->
</conbody>
</concept>
44 changes: 44 additions & 0 deletions specification/archSpec/base/index-overview.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="indexoverview" rev="review-chenier">
<title>Index overview</title>
<shortdesc>DITA provides several elements to enable indexing. Whether and how an index is
rendered will vary based on implementation decisions and rendering formats.</shortdesc>
<body>
<draft-comment author="rodaande">Placeholder for definition of "index" and "generated
index", as used within the DITA specification</draft-comment>
<p>While DITA provides several elements that support indexing, how those elements are used
will vary by implementation.</p>
<ul id="ul_vmb_tw3_1cc">
<li>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.</li>
<li>Another publishing format might have no rendered index at all, but instead use the
index element content to help weight search results.</li>
<li>Some implementations might choose to supplement a generated index with additional
content, such as treating a specialized <xmlelement>keyword</xmlelement> element as
both normal content and an index entry.</li>
<li>Implementations might have different ways to render indexing edge cases, based on
either implementation capabilities or style preferences.</li>
</ul>
<p>While DITA itself defines markup for indexing and specifies exactly what point an index
term 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.</p>
<p>The following list includes some of the conditions that implementations might want to be
aware of when considering how to generate an index:<ul id="ul_pxb_wdj_1cc">
<li>Index procssors typically ignore leading or trailing whitespace characters.</li>
<li>Processors might want to treat two entries separately if they are defined with
different cases.</li>
<li>Processors need to determine how to handle nested markup, such as
<xmlelement>keyword</xmlelement>, within an index entry.</li>
<li>Because <xmlelement>index-see</xmlelement> is used to refer to a term that is
used <i>instead of</i> the current entry, processors should consider how to
handle a case where an index term is used as a page locater but is also used
with an <xmlelement>index-see</xmlelement> for redirection.</li>
<li>Similarly, processors should consider how to handle a case where an index term
is defined with both an <xmlelement>index-see</xmlelement> and an
<xmlelement>index-see-also</xmlelement>.</li>
</ul></p>
</body>
</topic>
89 changes: 0 additions & 89 deletions specification/archSpec/base/index-redirection.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,94 +16,5 @@
reader should use <i>instead of</i> the current one, whereas the
<xmlelement>index-see-also</xmlelement> element contains text for an index entry
that the reader should use <i>in addition to</i> the current one.</p>
<div outputclass="errorcondition">
<p>Generated index entries should not contain both locators and redirections. Therefore,
it is an error if the following conditions occur:</p>
<dl id="dl_sct_jmr_pyb">
<dlentry>
<dt>An <xmlelement>indexterm</xmlelement> contains
<xmlelement>index-see</xmlelement>, and the publication contains other
<xmlelement>indexterm</xmlelement> with matching content</dt>
<dd>
<p>An <xmlelement>indexterm</xmlelement> element contains an
<xmlelement>index-see</xmlelement> element, and the publication
contains one or more <xmlelement>indexterm</xmlelement> elements with
matching textual content.</p>
<p>For example, topics referenced by the master map include the following
markup:</p>
<codeblock id="codeblock_tct_jmr_pyb">&lt;!-- Topic A -->
&lt;indexterm>memory stick
&lt;index-see>USB drive&lt;/index-see>
&lt;/indexterm>

&lt;!-- Topic B -->
&lt;indexterm>memory stick&lt;/indexterm></codeblock>
</dd>
</dlentry>
<dlentry>
<dt>An <xmlelement>indexterm</xmlelement> contains
<xmlelement>index-see</xmlelement> and
<xmlelement>index-see-also</xmlelement></dt>
<dd>
<p>An <xmlelement>indexterm</xmlelement> element contains both an
<xmlelement>index-see</xmlelement> element and an
<xmlelement>index-see-also</xmlelement> element.</p>
<p>For example, a topic contains the following
<xmlelement>indexterm</xmlelement> element:</p>
<codeblock id="codeblock_uct_jmr_pyb">&lt;indexterm>
memory stick
&lt;index-see>USB drive&lt;/index-see>
&lt;index-see-also>flash stick&lt;/index-see-also>
&lt;/indexterm></codeblock>
</dd>
</dlentry>
</dl>
</div>
<p outputclass="errorcondition">A processor <term outputclass="RFC-2119">MAY</term> give an
error message when it encounters the following error conditions:<ul>
<li rev="review-1">An <xmlelement>indexterm</xmlelement> element contains an
<xmlelement>index-see</xmlelement> element, and the publication contains one
or more <xmlelement>indexterm</xmlelement> elements with matching textual
content.</li>
<li>Both <xmlelement>index-see</xmlelement> and
<xmlelement>index-see-also</xmlelement> elements within the same
<xmlelement>indexterm</xmlelement> element.</li>
</ul> Processors <term outputclass="RFC-2119">MAY</term> recover from these error
conditions by treating the <xmlelement>index-see</xmlelement> element as an
<xmlelement>index-see-also</xmlelement> element.</p>
<!--<draft-comment author="Kristen J Eberlein" time="07 July 2019"><p>Do we want to state what processors should do for the first error condition listed above? Issue an error messsage?</p><p>Do we want to use RFC-2119 terminology?</p></draft-comment>-->
<!--<draft-comment author="Eliot Kimber"><p>I'm not sure [if the first error condition above] is an error given the above analysis.</p><p>For example, it could make just as much sense to treat the index-see as an index-see-also in this case.</p><p>Alternatively the two entries could be combined to create one effective entry that matches topic A's version.</p><p>That is, whether or not this is considered an error is really user option based on their editorial rules for indexes. Processors should probably provide runtime options for how to handle these situations:</p><ul><li>Report as error</li><li>Recover by treating index-see as index-see-also</li><li>Merge entries to a single effective structure</li></ul></draft-comment>-->
<draft-comment author="Joyce Lam" time="08 August 2019">
<p>Context = Normative statement about "An <xmlelement>indexterm</xmlelement> contains
<xmlelement>index-see</xmlelement> and <xmlelement>index-see-also</xmlelement>" </p>
<p>Because we emphasize "MAY", it also means that it "may not". I would like to ask "Who
are we leaving the decision up to?"</p>
<p>Is this instead a question of "SHOULD"?</p>
</draft-comment>
<draft-comment author="Eliot Kimber" time="09 August 2019">
<p>I think SHOULD is better too</p>
</draft-comment>
<draft-comment author="Kristen J Eberlein" time="12 August 2019">
<p>I think we cannot make this a stronger statement here than <term
outputclass="RFC-2119">MAY</term>:</p>
<ul>
<li>There are no interoperability issues involved.</li>
<li>Processors might choose to handle this error condition different. Basically, we
(the TC) are suggesting one possible approach that seems well considered.</li>
</ul>
<p>Reminder for people to review the following material when considering any spec
statement that contains RFC-2119 terminology:</p>
<ul>
<li><xref href="../../introduction/terminology.dita"/></li>
<li><xref
href="http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html"
format="html" scope="external">Guidelines to Writing Conformance Clauses for
OASIS Specifications</xref></li>
</ul>
</draft-comment>
<draft-comment author="rodaande" time="13 December 2022">Because this is only meant to offer
a possible suggested mitigation – and we already have the MAY rule giving permission to
treat this as an error - can we get rid of the extra normative MAY and switch to a
lower-case "might"?</draft-comment>
</conbody>
</concept>
29 changes: 1 addition & 28 deletions specification/archSpec/base/indexes.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,5 @@
<concept xml:lang="en-us" id="indexes">
<title>Indexes</title>
<shortdesc>Processors can generate an index from the content of indexing elements.</shortdesc>
<conbody>
<draft-comment author="Kristen J Eberlein" time="09 August 2019">
<p>Comment by Eliot Kimber:</p>
<p>I think we need a general discussion of index processing and rendering that covers:</p>
<ul>
<li>Generation of page numbers or other locators (addresses "typical" question)</li>
<li>General rules or expectations for merging entries to produce the "effective index
markup"</li>
<li>General guidance for reporting conditions such as see-also references to non-existent
entries and missing @end for @start specified in maps.</li>
</ul>
<p>The current writeup reflects a lot of unstated assumptions about how index processing does or
should work, obviously reflecting how IBM's tools worked (and work today). These assumptions
need to be surfaced.</p>
</draft-comment>
<draft-comment author="Kristen J Eberlein" time="12 August 2019">
<p>We need to clearly state our assumptions, but I think we need to be careful about specifying
expected processing too precisely:</p>
<ul>
<li>We have no idea what output format people are transforming their DITA to; we cannot assume
that it is print-based. And we have no idea what sort of output formats might emerge after DITA
2.0 is released!</li>
<li>Not all DITA processors support indexing.</li>
</ul>
<p>It would be good to be upfront about the fact that many details about index generation will be
implementation specific.</p>
</draft-comment>
</conbody>
<conbody/>
</concept>
2 changes: 1 addition & 1 deletion specification/archSpec/base/indexes.ditamap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
<map>
<title>Indexes</title>
<topicref href="indexes.dita">
<topicref href="index-overview.dita"/>
<topicref href="index-elements.dita"/>
<topicref href="location-of-indexterm-elements.dita"/>
<topicref href="index-page-references.dita"/>
<topicref href="index-redirection.dita"/>
<topicref href="index-ranges.dita"/>
<topicref href="index-sorting.dita"/>
<topicref href="merging-index-elements.dita"/>
<topicref href="examples-indexing.dita">
<topicref href="example-of-nested-indexterm-elements.dita"/>
<topicref href="example-index-range-in-a-single-topic.dita"/>
Expand Down
4 changes: 4 additions & 0 deletions specification/dita-2.0-specification-subjectScheme.ditamap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@
<subjectdef keys="review-s"/>
<subjectdef keys="review-t"/>
<subjectdef keys="review-aretha"/>
<subjectdef keys="review-chenier"/>
<subjectdef keys="2.0"/>
<subjectdef keys="tc-review"/>
<subjectdef keys="rendering">
Expand All @@ -71,6 +72,9 @@
individual topics</shortdesc>
</topicmeta></subjectdef>
<subjectdef keys="review-a-2024"/>
<!-- Used for an early 2.0 review but not added to scheme,
adding later to get clean report from validation tools -->
<subjectdef keys="review-1"/>
</subjectdef>
<subjectdef keys="values-product">
<subjectdef keys="DITA-1.3"/>
Expand Down
Loading