From 38f5e374cec5c531c61121e2d76aaedaeaaccc1c Mon Sep 17 00:00:00 2001 From: Eliot Kimber Date: Tue, 18 Mar 2025 08:34:52 -0500 Subject: [PATCH 1/2] Review of Navigation: Reworked navigation and alternative title topics --- .../base/alternative-title-examples.dita | 133 ++++++++++++++ .../base/alternative-title-precedence.dita | 25 +++ .../archSpec/base/alternative-titles.dita | 163 +----------------- .../archSpec/base/cascading-metadata.ditamap | 2 +- .../archSpec/base/processing.ditamap | 49 ++++-- .../archSpec/base/table-of-contents.dita | 50 +++--- .../alternativetitles-domain-elements.ditamap | 2 +- .../langRef/basic-topic-elements.ditamap | 38 ++-- .../containers/alternativeTitles-d.dita | 13 +- 9 files changed, 249 insertions(+), 226 deletions(-) create mode 100644 specification/archSpec/base/alternative-title-examples.dita create mode 100644 specification/archSpec/base/alternative-title-precedence.dita diff --git a/specification/archSpec/base/alternative-title-examples.dita b/specification/archSpec/base/alternative-title-examples.dita new file mode 100644 index 00000000..1fbcb62e --- /dev/null +++ b/specification/archSpec/base/alternative-title-examples.dita @@ -0,0 +1,133 @@ + + + + Alternative title examples + Non-normative examples of alternative titles + +
+ Examples: Navigation title precedence +

Consider the following series of topic references to topics:

+ <topicref href="topics.dita#one"/> +<topicref href="topics.dita#two"> + <topicmeta> + <titlealt title-role="navigation">Topic Two (Map navigation title)</titlealt> + </topicmeta> +</topicref> +<topicref href="topics.dita#three"> + <topicmeta> + <titlealt title-role="linking">Topic Three (Map linking title)</titlealt> + </topicmeta> +</topicref> +<topicref href="topics.dita#four"> + <topicmeta> + <titlealt title-role="linking">Topic Four (Map linking title)</titlealt> + </topicmeta> +</topicref> +

Here is the ditabase document containing those topics:

+ <dita> + <topic id="one"> + <title>Topic One</title> + </topic> + <topic id="two"> + <title>Topic Two</title> + <prolog> + <titlealt title-role="navigation">Topic Two (Topic navigation title)</titlealt> + </prolog> + </topic> + <topic id="three"> + <title>Topic Three</title> + </topic> + <topic id="four"> + <title>Topic Four</title> + <prolog> + <titlealt title-role="navigation">Topic Four (Topic navigation title)</titlealt> + </prolog> + </topic> +</dita> +

The resulting navigation structure would be as follows:

+
    +
  1. Topic One — The navigation title is the title of the topic, as neither the topicref nor the topic specify a navigation title.
    2. +
  2. Topic Two (Map navigation title) — The navigation title comes from the topicref, as its navigation title takes precedence over that in the topic.
    3. +
  3. Topic Three (Map linking title) — 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 navigation + alternative title is provided.
    4. +
  4. Topic Four (Topic navigation title) — The navigation title comes from the topic. Even though the map specifies a titlealt with a role of linking, and normally maps take precedence, a + linking alternative title is only used for navigation when there is no navigation 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 navigation alternative title. The linking title in the map still applies as the resource's linking title, + just not its navigation title.
    5. +
+
+
+ Example: Reconciling map and topic alternative titles +

A topicref contains the following titles:

+ <topicref href="topic.dita"> + <topicmeta> + <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> + <titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> + </topicmeta. +</topicref> +

The referenced topic has the following prolog:

+ <prolog> + <titlealt title-role="subtitle">Doing Stuff</titlealt> + <titlealt title-role="breadcrumbTitle flipbookTitle">Stuff</titlealt> +</prolog> +

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:

+ <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> +<titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> +<titlealt title-role="subtitle">Doing Stuff</titlealt> +<titlealt title-role="breadcrumbTitle flipbookTitle">Stuff</titlealt> +

Note that breadcrumbTitle 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 + flipbookTitle, which is not overridden by the map, and so should be preserved.

+

The equivalent merged alternative titles, with duplicates removed, is:

+ <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> +<titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> +<titlealt title-role="subtitle">Doing Stuff</titlealt> +<titlealt title-role="flipbookTitle">Stuff</titlealt> +
+
+ Example: Keyrefs and alternative titles +

Consider the following two topic references:

+ <topicref keys="a"> + <topicmeta> + <titlealt title-role="navigation">Navigation Title</titlealt> + </topicmeta> +</topicref> +<topicref keyref="a"> + <topicmeta> + <titlealt title-role="navigation">Navigation Title from Keyref</titlealt> + <titlealt title-role="linking">Linking Title from Keyref</titlealt> + </topicmeta> +</topicref> +

The resolved titles would look something like this:

+ +<titlealt title-role="linking">Linking Title from Keyref</titlealt> +<titlealt title-role="navigation">Navigation Title from Keyref</titlealt> +<titlealt title-role="navigation">Navigation Title</titlealt> + +

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 + navigation title from the referenced topicref has no effect.

+
+
+ Example: Custom title roles +

A content architect could create a Topic specialization with custom titlealt specializations windowtitle and breadcrumbtitle. These specializations would + specify default title-role values of window and breadcrumb, respectively, so that authors do not have to specify those roles explicitly.

+

Content containing these specializations could look like the following.

+ <helpTopic id="topic167"> + <title>Doing the Thing in the Place where the Stuff Is</title> + <prolog> + <windowtitle>Doing Things</windowtitle> + <breadcrumbtitle>Things</breadcrumbtitle> + </prolog> +

They could also incorporate these elements into their map document type shell, enabling map authors to override the values in topics.

+ <topicref href="topic167.dita"> + <topicmeta> + <breadcrumbtitle>Thing Doing</breadcrumbtitle> + </topicmeta> +</topicref> +
+ + diff --git a/specification/archSpec/base/alternative-title-precedence.dita b/specification/archSpec/base/alternative-title-precedence.dita new file mode 100644 index 00000000..f36dcc34 --- /dev/null +++ b/specification/archSpec/base/alternative-title-precedence.dita @@ -0,0 +1,25 @@ + + + + Alternative title precedence + 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. + + ServiceNow + + + + + + + + + + + +

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 + topic-role value in the topic. When an alternative title element specifies two or more role names as the topic-role value, each role name is considered separately, as though each role had been specified + on a separate element. Within a titlealts element, the earliest use of a topic-role value takes precedence.

+

For topics referenced from maps, the alternative title fallback rules as defined by the titlealt element are applied after the effective alternative titles are determined for a given reference to a topic.

+

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.

+ + diff --git a/specification/archSpec/base/alternative-titles.dita b/specification/archSpec/base/alternative-titles.dita index 44e735b9..da772048 100644 --- a/specification/archSpec/base/alternative-titles.dita +++ b/specification/archSpec/base/alternative-titles.dita @@ -2,163 +2,8 @@ Alternative titles - This topic contains examples of alternative titles moved - from the titlealt topic. It needs editing and - to be restructured. - -
- Custom title roles -

A content architect could create a Topic specialization with - custom titlealt specializations called - windowtitle and - breadcrumbtitle. These specializations - specify default title-role values of - window and breadcrumb, - respectively, so that authors do not have to specify those roles - explicitly. Content containing these specializations could look - like the following.

- <helpTopic id="topic167"> - <title>Doing the Thing in the Place where the Stuff Is</title> - <prolog> - <windowtitle>Doing Things</windowtitle> - <breadcrumbtitle>Things</breadcrumbtitle> - </prolog> -

They could also incorporate these elements into their map document - type shell, enabling map authors to override the values in - topics.

- <topicref href="topic167.dita"> - <topicmeta> - <breadcrumbtitle>Thing Doing</breadcrumbtitle> - </topicmeta> -</topicref> -
-
- Navigation titles and precedence -

Move to archSpec

-

Consider the following series of topic references:

- <topicref href="topics.dita#one"/> -<topicref href="topics.dita#two"> - <topicmeta> - <titlealt title-role="navigation">Topic Two (Map navigation title)</titlealt> - </topicmeta> -</topicref> -<topicref href="topics.dita#three"> - <topicmeta> - <titlealt title-role="linking">Topic Three (Map linking title)</titlealt> - </topicmeta> -</topicref> -<topicref href="topics.dita#four"> - <topicmeta> - <titlealt title-role="linking">Topic Four (Map linking title)</titlealt> - </topicmeta> -</topicref> -

Here is the ditabase document containing those topics:

- <dita> - <topic id="one"> - <title>Topic One</title> - </topic> - <topic id="two"> - <title>Topic Two</title> - <prolog> - <titlealt title-role="navigation">Topic Two (Topic navigation title)</titlealt> - </prolog> - </topic> - <topic id="three"> - <title>Topic Three</title> - </topic> - <topic id="four"> - <title>Topic Four</title> - <prolog> - <titlealt title-role="navigation">Topic Four (Topic navigation title)</titlealt> - </prolog> - </topic> -</dita> -

The resulting navigation structure would be as follows:

-
    -
  1. Topic One - The navigation title is pulled from the - title of the topic, since neither the map nor the topic specify a - navigation title.
    2. -
  2. Topic Two (Map navigation title) - The navigation title - comes from the map, as its navigation title takes precedence over - that in the topic.
    3. -
  3. Topic Three (Map linking title) - The navigation title - comes from the map, which serves as the fallback for navigation - titles when no navigation alternative title is - provided.
    4. -
  4. Topic Four (Topic navigation title) - The navigation - title comes from the topic. Even though the map specifies a - titlealt with a role of - linking, and normally maps take precedence, a - linking alternative title is only used for - navigation when there is no navigation - 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 navigation alternative - title. The linking title in the map still - applies as the resource's linking title, just not its navigation - title.
    5. -
-
-
- Example: Reconciling Map and Topic Alternative Titles -

A topicref contains the following - titles:

- <topicref href="topic.dita"> - <topicmeta> - <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> - <titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> - </topicmeta. -</topicref> -

The referenced topic has the following prolog:

- <prolog> - <titlealt title-role="subtitle">Doing Stuff</titlealt> - <titlealt title-role="breadcrumbTitle flipbookTitle">Stuff</titlealt> -</prolog> -

During processing, the two sets of elements will be concatenated - together (logically, if not physically), with the map's elements - coming first:

- <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> -<titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> -<titlealt title-role="subtitle">Doing Stuff</titlealt> -<titlealt title-role="breadcrumbTitle flipbookTitle">Stuff</titlealt> -

Note that breadcrumbTitle 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 flipbookTitle, which is not - overridden by the map, and so should be preserved.

-

The equivalent merged alternative titles, with duplicates removed, - would look as follows.

- <titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt> -<titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt> -<titlealt title-role="subtitle">Doing Stuff</titlealt> -<titlealt title-role="flipbookTitle">Stuff</titlealt> -
-
- Keyrefs and alternative titles -

Move to archSpec. Content of <titlealt> needs to change; it's - backwards.

-

Consider the following two topic references:

- <topicref keys="a"> - <topicmeta> - <titlealt title-role="linking">Linking Title from Keyref</titlealt> - <titlealt title-role="navigation">Navigation Title from Keyref</titlealt> - </topicmeta> -</topicref> -<topicref keyref="a"> - <topicmeta> - <titlealt title-role="navigation">Navigation Title</titlealt> - </topicmeta> -</topicref> -

The resolved titles would look something like this:

- <titlealt title-role="navigation">Navigation Title</titlealt> -<titlealt title-role="linking">Linking Title from Keyref</titlealt> -<titlealt title-role="navigation">Navigation Title from Keyref</titlealt> -

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 navigation title from the key reference has no - effect.

-
- + The titlealt element is used to define alternative titles for maps, topics, and topic references for various purposes, including navigation- and search-specific titles. The + titlealt element uses the title-role 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 titlealt element defines a base set of title role values. diff --git a/specification/archSpec/base/cascading-metadata.ditamap b/specification/archSpec/base/cascading-metadata.ditamap index 8e69861d..0ddef44c 100644 --- a/specification/archSpec/base/cascading-metadata.ditamap +++ b/specification/archSpec/base/cascading-metadata.ditamap @@ -9,7 +9,7 @@ - + diff --git a/specification/archSpec/base/processing.ditamap b/specification/archSpec/base/processing.ditamap index af45aaeb..5a855bfe 100644 --- a/specification/archSpec/base/processing.ditamap +++ b/specification/archSpec/base/processing.ditamap @@ -1,18 +1,37 @@ - - Processing - - - - - - - - - - - - + + Processing + + + + + + + + + + + + + + + - diff --git a/specification/archSpec/base/table-of-contents.dita b/specification/archSpec/base/table-of-contents.dita index 1584a7a8..da17ef7a 100644 --- a/specification/archSpec/base/table-of-contents.dita +++ b/specification/archSpec/base/table-of-contents.dita @@ -1,36 +1,26 @@ - Table of contents - Processors can generate a table of contents (TOC) based on the hierarchy of the elements - in a DITA map. By default, each topicref element in a map represents a - node in the TOC. These topic references define a navigation tree. + Navigation trees (Tables of contents) + Processors can produce navigation structures, such as tables of contents, based on the hierarchy of the elements in a DITA map. By default, each normal-role topic reference in a map represents an entry in a navigation tree. The + most common presentation form of navigation tree is a Table of Contents (TOC), but navigation structures derived from DITA maps may take many forms and be rendered in many different ways. -

When a map contains a topic reference to a map (often called a map reference), processors - integrate the navigation tree of the referenced map with the navigation tree of the - referencing map at the point of reference. In this way, a deliverable can be compiled from - multiple DITA maps.

- -

The effective navigation title is used for the value of the TOC node. A TOC node is generated - for every topicref element that references a topic or specifies a - navigation title, except in the following cases:

-
    -
  • The processing-role attribute that is specified on the - topicref element or an ancestor element is set to - "resource-only".
    • -
  • Conditional processing is used to filter out the node or an ancestor node.
    • -
  • There is no information from which a TOC entry can be constructed; there is no referenced - resource or navigation title.
    • -
  • The node is a topicgroup element, even if it specifies a navigation - title.
    • -
-

To suppress a topicref element from appearing in the TOC, set the - toc attribute to "no". The value of the toc attribute cascades - to child topicref elements, so if toc is set to "no" on - a particular topicref, all children of the - topicref element are also excluded from the TOC. If a child - topicref overrides the cascading operation by specifying - toc="yes", then the node that specifies toc="yes" appears in - the TOC (minus the intermediate nodes that set toc to "no").

+

Navigation trees are produced from the effective resolved map defined by the root map that is input to the production process, reflecting the resolving of any map references, the cascading of attributes and metadata, and any other + DITA-defined processing for DITA maps.

+

Each entry in a generated navigation structure SHOULD reflect the effective navigation title of the target resource if resource titles are used in the rendered navigation structure. By default, the navigation title for a navigation + entry is defined by the "navigation" role title alternative, if present. Processors can use other alternative title roles to determine effective navigation titles but should use "navigation"-role titles if no more specific alternative + title is available. See .For example, a processor that produces "metro map" navigation structures for guided path navigation and recognizes the alternative title role "guided-path-title" can use guided path titles even + if a resource also defines a "navigation"-role alternative title. But if a resource defines only a "navigation"-role title, that title would be used in the metro map navigation.

+

Topic references in the effective resolved map SHOULD result in navigation entries unless they satisfy any of the following conditions:

    +
  • The effective processing-role value is resource-only.
    • +
  • The effective toc value is "no".
    • +
  • The topic reference is filtered out.
    • +
  • The topic reference element is topicgroup or a specialization of topicgroup, even if it specifies a navigation title.
    • +
  • There is no information from which to construct a navigation entry: there is no referenced resource or effective navigation title.
    • +

+

The effective values of processing-role and toc are determined by attribute cascading. See .

 diff --git a/specification/langRef/alternativetitles-domain-elements.ditamap b/specification/langRef/alternativetitles-domain-elements.ditamap index a978621b..020a8889 100644 --- a/specification/langRef/alternativetitles-domain-elements.ditamap +++ b/specification/langRef/alternativetitles-domain-elements.ditamap @@ -2,7 +2,7 @@ Alternative titles domain elements - + diff --git a/specification/langRef/basic-topic-elements.ditamap b/specification/langRef/basic-topic-elements.ditamap index 037dfefe..ed9dad08 100644 --- a/specification/langRef/basic-topic-elements.ditamap +++ b/specification/langRef/basic-topic-elements.ditamap @@ -1,17 +1,29 @@ - Basic topic elements - - - - - - - - - - - - + Basic topic elements + + + + + + + + + + + + diff --git a/specification/langRef/containers/alternativeTitles-d.dita b/specification/langRef/containers/alternativeTitles-d.dita index db0121c6..36074994 100644 --- a/specification/langRef/containers/alternativeTitles-d.dita +++ b/specification/langRef/containers/alternativeTitles-d.dita @@ -1,16 +1,15 @@  - + Alternative-titles domain elements - The alternative title elements are designed to provide - alternative titles for resources. The elements in - the alternative-titles domain are specialized from the - titlealt element. + The alternative title elements are designed to provide alternative titles for resources. The elements in the alternative-titles domain are specialized from the titlealt element. - alternative - titlesoverview + alternative titlesoverview domainsalternative titles From e68a6bdf90ee0dde251c737a4174eb335a74332f Mon Sep 17 00:00:00 2001 From: Eliot Kimber Date: Sun, 23 Mar 2025 09:21:34 -0500 Subject: [PATCH 2/2] Ignore hidden files --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 40733030..8a00aed7 100644 --- a/.gitignore +++ b/.gitignore @@ -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