Skip to content

Review of Navigation: Reworked navigation and alternative title topics #949

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

Open
drmacro wants to merge 2 commits into
base: DITA-2.0
Choose a base branch
from
Open

Review of Navigation: Reworked navigation and alternative title topics #949

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
38f5e37
Review of Navigation: Reworked navigation and alternative title topics
ekimbernow Mar 18, 2025
e68a6bd
Ignore hidden files
ekimbernow Mar 23, 2025
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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ specification/proposal-647-content.ditamap
specification/review-stage-3-of-issue-647.ditamap
specification/DITA2.0-spec.ditaval
~*
.*
specification/imagemap/Bronte_Sisters.jpg
specification/imagemap/
specification/test/food.dita
Expand Down
133 changes: 133 additions & 0 deletions specification/archSpec/base/alternative-title-examples.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="alternative-title-examples">
<title>Alternative title examples</title>
<shortdesc>Non-normative examples of alternative titles</shortdesc>
<conbody>
<section
id="section_o3v_qwf_s2c">
<title>Examples: Navigation title precedence</title>
<p>Consider the following series of topic references to topics:</p>
<codeblock>&lt;topicref href="topics.dita#one"/>
&lt;topicref href="topics.dita#two">
&lt;topicmeta>
&lt;titlealt title-role="navigation">Topic Two (Map navigation title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref href="topics.dita#three">
&lt;topicmeta>
&lt;titlealt title-role="linking">Topic Three (Map linking title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref href="topics.dita#four">
&lt;topicmeta>
&lt;titlealt title-role="linking">Topic Four (Map linking title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref></codeblock>
<p>Here is the ditabase document containing those topics:</p>
<codeblock>&lt;dita>
&lt;topic id="one">
&lt;title>Topic One&lt;/title>
&lt;/topic>
&lt;topic id="two">
&lt;title>Topic Two&lt;/title>
&lt;prolog>
&lt;titlealt title-role="navigation">Topic Two (Topic navigation title)&lt;/titlealt>
&lt;/prolog>
&lt;/topic>
&lt;topic id="three">
&lt;title>Topic Three&lt;/title>
&lt;/topic>
&lt;topic id="four">
&lt;title>Topic Four&lt;/title>
&lt;prolog>
&lt;titlealt title-role="navigation">Topic Four (Topic navigation title)&lt;/titlealt>
&lt;/prolog>
&lt;/topic>
&lt;/dita></codeblock>
<p>The resulting navigation structure would be as follows:</p>
<ol
id="ul_z2w_rx5_dgb">
<li><b>Topic One</b> — The navigation title is the title of the topic, as neither the topicref nor the topic specify a navigation title.</li>
<li><b>Topic Two (Map navigation title)</b> — The navigation title comes from the topicref, as its navigation title takes precedence over that in the topic.</li>
<li><b>Topic Three (Map linking title)</b> — The navigation title comes from the "linking" alternative title in the topicref, because "linking" role titles serve as the fallback for navigation titles when no <codeph>navigation</codeph>
alternative title is provided.</li>
<li><b>Topic Four (Topic navigation title)</b> — The navigation title comes from the topic. Even though the map specifies a <xmlelement>titlealt</xmlelement> with a role of <codeph>linking</codeph>, and normally maps take precedence, a
<codeph>linking</codeph> alternative title is only used for navigation when there is no <codeph>navigation</codeph> alternative title available. In this case, the one from the topic is present, and is therefore used. To override the
topic's navigation title in this case, the topic reference would have to explicitly provide a <codeph>navigation</codeph> alternative title. The <codeph>linking</codeph> title in the map still applies as the resource's linking title,
just not its navigation title.</li>
</ol>
</section>
<section
id="section_p3v_qwf_s2c">
<title>Example: Reconciling map and topic alternative titles</title>
<p>A <xmlelement>topicref</xmlelement> contains the following titles:</p>
<codeblock>&lt;topicref href="topic.dita">
&lt;topicmeta>
&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;/topicmeta.
&lt;/topicref></codeblock>
<p>The referenced topic has the following prolog:</p>
<codeblock>&lt;prolog>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="breadcrumbTitle flipbookTitle">Stuff&lt;/titlealt>
&lt;/prolog></codeblock>
<p>The effective set of alternative titles reflects the titles from the topicref followed by the titles from the topic. The "first title role has precendence" rule is used to determine the effective title for each role:</p>
<codeblock>&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="breadcrumbTitle flipbookTitle">Stuff&lt;/titlealt></codeblock>
<p>Note that <codeph>breadcrumbTitle</codeph> is specified in both the topicref and the topic, and the topicref's value takes precedence. However, that same alternative title in the topic specifies an additional role of
<codeph>flipbookTitle</codeph>, which is not overridden by the map, and so should be preserved.</p>
<p>The equivalent merged alternative titles, with duplicates removed, is:</p>
<codeblock>&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="flipbookTitle">Stuff&lt;/titlealt></codeblock>
</section>
<section
id="section_q3v_qwf_s2c">
<title>Example: Keyrefs and alternative titles</title>
<p>Consider the following two topic references:</p>
<codeblock>&lt;topicref keys="a">
&lt;topicmeta>
&lt;titlealt title-role="navigation">Navigation Title&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref keyref="a">
&lt;topicmeta>
&lt;titlealt title-role="navigation">Navigation Title from Keyref&lt;/titlealt>
&lt;titlealt title-role="linking">Linking Title from Keyref&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref></codeblock>
<p>The resolved titles would look something like this:</p>
<codeblock>
&lt;titlealt title-role="linking">Linking Title from Keyref&lt;/titlealt>
&lt;titlealt title-role="navigation">Navigation Title from Keyref&lt;/titlealt>
&lt;titlealt title-role="navigation">Navigation Title&lt;/titlealt>
</codeblock>
<p>That is, the "local" alternative titles in the referencing topicref have precedence over those in the refernenced topicref. In cases where only a single alternative title of a given role can be used, the first takes precedence, so the
<codeph>navigation</codeph> title from the referenced topicref has no effect.</p>
</section>
<section
id="section_n3v_qwf_s2c">
<title>Example: Custom title roles</title>
<p>A content architect could create a Topic specialization with custom <xmlelement>titlealt</xmlelement> specializations <xmlelement>windowtitle</xmlelement> and <xmlelement>breadcrumbtitle</xmlelement>. These specializations would
specify default <xmlatt>title-role</xmlatt> values of <codeph>window</codeph> and <codeph>breadcrumb</codeph>, respectively, so that authors do not have to specify those roles explicitly.</p>
<p>Content containing these specializations could look like the following.</p>
<codeblock base="ci-xml">&lt;helpTopic id="topic167">
&lt;title>Doing the Thing in the Place where the Stuff Is&lt;/title>
&lt;prolog>
&lt;windowtitle>Doing Things&lt;/windowtitle>
&lt;breadcrumbtitle>Things&lt;/breadcrumbtitle>
&lt;/prolog></codeblock>
<p>They could also incorporate these elements into their map document type shell, enabling map authors to override the values in topics.</p>
<codeblock base="ci-xml">&lt;topicref href="topic167.dita">
&lt;topicmeta>
&lt;breadcrumbtitle>Thing Doing&lt;/breadcrumbtitle>
&lt;/topicmeta>
&lt;/topicref></codeblock>
</section>
</conbody>
</concept>
25 changes: 25 additions & 0 deletions specification/archSpec/base/alternative-title-precedence.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="alternative-title-precedence">
<title>Alternative title precedence</title>
<shortdesc>Alternative titles from topic references take precedence over the same title roles in referenced topics. Within a set of alternative titles, the first instance of a given title role takes precedence.</shortdesc>
<prolog>
<author>ServiceNow</author>
<critdates>
<created date="2025-03-18T08:09:18-05:00"/>
<revised modified="2025-03-18T08:09:18-05:00"/>
</critdates>
<metadata>
<keywords>
<keyword><?oxy-placeholder content="Add keywords for search"?></keyword>
</keywords>
</metadata>
</prolog>
<conbody>
<p>When determining the effective value of a given alternative title for a topic as referenced from a map, alternative titles specified by the referencing topicref take precedence over alternative titles with the same
<xmlatt>topic-role</xmlatt> value in the topic. When an alternative title element specifies two or more role names as the <xmlatt>topic-role</xmlatt> value, each role name is considered separately, as though each role had been specified
on a separate element. Within a <xmlelement>titlealts</xmlelement> element, the earliest use of a <xmlatt>topic-role</xmlatt> value takes precedence.</p>
<p>For topics referenced from maps, the alternative title fallback rules as defined by the <xmlelement>titlealt</xmlelement> element are applied after the effective alternative titles are determined for a given reference to a topic.</p>
<p>When a topicref makes a key reference to another topicref, the alternative titles in the referencing topicref take precedence over alternative titles in the referenced topic reference.</p>
</conbody>
</concept>
163 changes: 4 additions & 159 deletions specification/archSpec/base/alternative-titles.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,163 +2,8 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="alternative-titles">
<title>Alternative titles</title>
<shortdesc>This topic contains examples of alternative titles moved
from the <xmlelement>titlealt</xmlelement> topic. It needs editing and
to be restructured.</shortdesc>
<conbody>
<section>
<title>Custom title roles</title>
<p>A content architect could create a Topic specialization with
custom <xmlelement>titlealt</xmlelement> specializations called
<xmlelement>windowtitle</xmlelement> and
<xmlelement>breadcrumbtitle</xmlelement>. These specializations
specify default <xmlatt>title-role</xmlatt> values of
<codeph>window</codeph> and <codeph>breadcrumb</codeph>,
respectively, so that authors do not have to specify those roles
explicitly. Content containing these specializations could look
like the following.</p>
<codeblock base="ci-xml">&lt;helpTopic id="topic167">
&lt;title>Doing the Thing in the Place where the Stuff Is&lt;/title>
&lt;prolog>
&lt;windowtitle>Doing Things&lt;/windowtitle>
&lt;breadcrumbtitle>Things&lt;/breadcrumbtitle>
&lt;/prolog></codeblock>
<p>They could also incorporate these elements into their map document
type shell, enabling map authors to override the values in
topics.</p>
<codeblock base="ci-xml">&lt;topicref href="topic167.dita">
&lt;topicmeta>
&lt;breadcrumbtitle>Thing Doing&lt;/breadcrumbtitle>
&lt;/topicmeta>
&lt;/topicref></codeblock>
</section>
<section>
<title>Navigation titles and precedence</title>
<p>Move to archSpec</p>
<p>Consider the following series of topic references:</p>
<codeblock>&lt;topicref href="topics.dita#one"/>
&lt;topicref href="topics.dita#two">
&lt;topicmeta>
&lt;titlealt title-role="navigation">Topic Two (Map navigation title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref href="topics.dita#three">
&lt;topicmeta>
&lt;titlealt title-role="linking">Topic Three (Map linking title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref href="topics.dita#four">
&lt;topicmeta>
&lt;titlealt title-role="linking">Topic Four (Map linking title)&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref></codeblock>
<p>Here is the ditabase document containing those topics:</p>
<codeblock>&lt;dita>
&lt;topic id="one">
&lt;title>Topic One&lt;/title>
&lt;/topic>
&lt;topic id="two">
&lt;title>Topic Two&lt;/title>
&lt;prolog>
&lt;titlealt title-role="navigation">Topic Two (Topic navigation title)&lt;/titlealt>
&lt;/prolog>
&lt;/topic>
&lt;topic id="three">
&lt;title>Topic Three&lt;/title>
&lt;/topic>
&lt;topic id="four">
&lt;title>Topic Four&lt;/title>
&lt;prolog>
&lt;titlealt title-role="navigation">Topic Four (Topic navigation title)&lt;/titlealt>
&lt;/prolog>
&lt;/topic>
&lt;/dita></codeblock>
<p>The resulting navigation structure would be as follows:</p>
<ol id="ul_z2w_rx5_dgb">
<li><b>Topic One</b> - The navigation title is pulled from the
title of the topic, since neither the map nor the topic specify a
navigation title.</li>
<li><b>Topic Two (Map navigation title)</b> - The navigation title
comes from the map, as its navigation title takes precedence over
that in the topic.</li>
<li><b>Topic Three (Map linking title)</b> - The navigation title
comes from the map, which serves as the fallback for navigation
titles when no <codeph>navigation</codeph> alternative title is
provided.</li>
<li><b>Topic Four (Topic navigation title)</b> - The navigation
title comes from the topic. Even though the map specifies a
<xmlelement>titlealt</xmlelement> with a role of
<codeph>linking</codeph>, and normally maps take precedence, a
<codeph>linking</codeph> alternative title is only used for
navigation when there is no <codeph>navigation</codeph>
alternative title available. In this case, the one from the topic
is present, and is therefore used. To override the topic's
navigation title in this case, the topic reference would have to
explicitly provide a <codeph>navigation</codeph> alternative
title. The <codeph>linking</codeph> title in the map still
applies as the resource's linking title, just not its navigation
title.</li>
</ol>
</section>
<section>
<title>Example: Reconciling Map and Topic Alternative Titles</title>
<p>A <xmlelement>topicref</xmlelement> contains the following
titles:</p>
<codeblock>&lt;topicref href="topic.dita">
&lt;topicmeta>
&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;/topicmeta.
&lt;/topicref></codeblock>
<p>The referenced topic has the following prolog:</p>
<codeblock>&lt;prolog>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="breadcrumbTitle flipbookTitle">Stuff&lt;/titlealt>
&lt;/prolog></codeblock>
<p>During processing, the two sets of elements will be concatenated
together (logically, if not physically), with the map's elements
coming first:</p>
<codeblock>&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="breadcrumbTitle flipbookTitle">Stuff&lt;/titlealt></codeblock>
<p>Note that <codeph>breadcrumbTitle</codeph> is specified in both
the map and the topic, and the map's value takes precedence.
However, that same alternative title in the topic specifies an
additional role of <codeph>flipbookTitle</codeph>, which is not
overridden by the map, and so should be preserved.</p>
<p>The equivalent merged alternative titles, with duplicates removed,
would look as follows.</p>
<codeblock>&lt;titlealt title-role="breadcrumbTitle">Doin' Stuff&lt;/titlealt>
&lt;titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.&lt;/titlealt>
&lt;titlealt title-role="subtitle">Doing Stuff&lt;/titlealt>
&lt;titlealt title-role="flipbookTitle">Stuff&lt;/titlealt></codeblock>
</section>
<section>
<title>Keyrefs and alternative titles</title>
<p>Move to archSpec. Content of &lt;titlealt> needs to change; it's
backwards.</p>
<p>Consider the following two topic references:</p>
<codeblock>&lt;topicref keys="a">
&lt;topicmeta>
&lt;titlealt title-role="linking">Linking Title from Keyref&lt;/titlealt>
&lt;titlealt title-role="navigation">Navigation Title from Keyref&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref>
&lt;topicref keyref="a">
&lt;topicmeta>
&lt;titlealt title-role="navigation">Navigation Title&lt;/titlealt>
&lt;/topicmeta>
&lt;/topicref></codeblock>
<p>The resolved titles would look something like this:</p>
<codeblock>&lt;titlealt title-role="navigation">Navigation Title&lt;/titlealt>
&lt;titlealt title-role="linking">Linking Title from Keyref&lt;/titlealt>
&lt;titlealt title-role="navigation">Navigation Title from Keyref&lt;/titlealt></codeblock>
<p>That is, the "local" alternative titles come before those pulled
from the key reference. In cases where only a single alternative
title of a given role can be used, the first takes precedence, so
the <codeph>navigation</codeph> title from the key reference has no
effect.</p>
</section>
</conbody>
<shortdesc>The <xref
keyref="titlealt"><xmlelement>titlealt</xmlelement></xref> element is used to define alternative titles for maps, topics, and topic references for various purposes, including navigation- and search-specific titles. The
<xmlelement>titlealt</xmlelement> element uses the <xmlatt>title-role</xmlatt> attribute to specify the semantic role a given alternative title plays. Processors choose alternative titles based on the title roles the processors
recognize for a given purpose. The <xmlelement>titlealt</xmlelement> element defines a base set of title role values.</shortdesc>
</concept>
2 changes: 1 addition & 1 deletion specification/archSpec/base/cascading-metadata.ditamap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
</topicref>
<topicref href="reconciling-topic-and-map-metadata.dita"/>
<topicref href="map-to-map-cascading-of-metadata.dita">
<topicref href="cascading-of-attributes-from-map-to-map.dita"/>
<topicref keys="cascading-of-attributes-from-map-to-map" href="cascading-of-attributes-from-map-to-map.dita" />
<topicref href="cascading-of-metadata-elements-from-map-to-map.dita"/>
</topicref>
<topicref href="examples-of-cascading.dita">
Expand Down
Loading
Loading