Here's the updated Stage 2 proposal. This uses <keytext> and not <variabletext> as most of this was written before this morning's list traffic; we can discuss naming during the meeting.

Chris

Stage two: #16 Improvements to `<titlealts>`

This feature makes the alternate-title mechanism more extensible, and allows its use in maps as well as topics.

Date and version information

Include the following information:

Date that this feature proposal was completed

1/8/2019

Champion of the proposal

Chris Nitchie

Links to any previous versions of the proposal

N/A

Links to minutes where this proposal was discussed at stage 1 and moved to stage 2

https://lists.oasis-open.org/archives/dita/201705/msg00015.html

Reviewers for Stage 2 proposal

Eliot Kimber, Robert Anderson, Alan Houser

Links to e-mail discussion that resulted in new versions of the proposal

N/A

Link to the GitHub issue

https://github.com/oasis-tcs/dita/issues/16

Original requirement or use case

We should allow <titlealts> inside <map> as well as <topic>. We should also add a zero-or-more <titlealt> element that can be specialized for specific purposes, and consider making <navtitle> and <searchtitle> specializations of <titlealt>.

In developing applications that leverage DITA, you very frequently need to ask the question, âwhatâs this documentâs title?â It should be as simple as looking for the <title> element, or its specialization, at the top level of the file. However, this doesnât work for bookmap, because its title element - <booktitle> - is actually a collection of pseudo-title elements specialized from <ph> - <mainbooktitle> and <booktitlealt>. So you have to write special-case code to handle BookMap, which is irksome. Even then, it wonât work for other <map> types that use a similar trick (like D4P PubMap). Adding <titlealts> to <map> solves it for new map types.

Use cases

A developer of a DITA map specialization wants to allow map authors to specify subtitles without specializing from <ph> inside of <title>, as Bookmap currently does.
A content architect at a software company wants to add the ability for help topic authors to specify the window title for their topics using new <windowtitle> and <breadcrumbtitle> alternative title types.
That same content architect wants to be able to put those titles inside <topicmeta> on <topicref> elements, as well as or instead of in the topics.

New terminology

None.

Proposed solution

A new base element, called <titlealt>, will be added to the base vocabulary. This element is allowed within <titlealts> in topics and <topicmeta> in maps.
The <navtitle> and <searchtitle> elements will be extracted to a new Alternative Titles domain, and made specializations of <titlealt>.
The <linktext> element as used in maps will be refactored into two distinct elements.

<linktitle>

A specialization of <titlealt> in the Alternative Titles domain, for use when determining the text to use for links to the referenced resource.

<keytext>

A new base element for specifying the text to use when the element is referenced via key from an element in a topic.

Note: The <linktext> element as used within topic <link> tags will not be modified.

Benefits

Who will benefit from this feature?

Content architects who want to allow custom alternative title types.

Authors whose content needs such alternative titles.

DITA map content architects.

Vendors that need to determine the primary titles in documents using future map specializations that allow for alternate/sub titles.

What is the expected benefit?

Standard mechanism for customized alternate titles.

Formalized alternate titles for maps and map specializations.

Applicability of custom alternate title specializations for topics, maps, and topicrefs.

Greater clarity in the markup to use for link text.

How many people probably will make use of this feature?

Lots. Everyone using the new BookMap. Any group requiring their own special alternative title types.

How much of a positive impact is expected for the users who will make use of the feature?

Very much. Current solutions are hacks (<pubtitlealt>, use of <data> specializations in <prolog> for alternate topic titles) or simply not possible.

Technical requirements

New base element type, <titlealt>, for use in <titlealts> and <topicmeta>. Within <topicmeta>, it appears in place of the current <navtitle> element.
<titlealt> carries the global and universal attribute groups. It also carries a required CDATA @title-role attribute describing the intended purpose or purposes of the alternate title. Specializations should provide a default or fixed value for this attribute. For example, the @title-role for <navtitle> would default to "navtitle". A single <titlealt> element can have multiple @title-role values, separated by white space, when it fulfills multiple roles.
If a given @title-role token appears more than once within a given <titlealts> or <topicmeta> element, the first one takes precedence.
When merging <titlealt> elements between topics and maps, the result is the union of all <titlealt> elements from both, with the elements from the map first, followed by those from the topic.

Note: When these two rules are taken together, the effect is that a topicref's entry for a given @title-role token takes precedence over any matching role in the topic.

When one <topicref> has a @keyref to another, and the target <topicref> includes alternate titles, those alternate titles are inherited by the referencing element. Any alternate titles on the referencing element take precedence over those from the key definition that carry the same @title-role token.
New "Alternate Titles" domain, containing <navtitle>, <searchtitle>, and <linktitle>, all as specializations of <titlealt>, to be included in all distributed topic and map types.
Unlike previous versions of DITA, the navigation title is defined as the <titlealt> with title-role="navtitle", rather than the <navititle> element specifically. The <navtitle> element will specify title-role="navtitle" by default, but authors may choose to specify the navigation title in combination with other alternative titles via a compound @title-role attribute, or via a different specialization of <titlealt>, so long as it specifies title-role="navtitle". As in current versions of DITA, a topic's <title> is used for its navigation title if neither the topic or the map specify a <navtitle> element.
Similarly, Search Title will be redefined as the <titlealt> with title-role="searchtitle", rather than the <searchtitle> element specifically. Again, <searchtitle> will specify title-role="searchtitle" by default. Processor expectations for search titles are unchanged.
Link Title will be redefined as the <titlealt> with title-role="linktitle", rather than the <linktext> element. The new <linktitle> element will specify title-role="linktitle" by default.
The title role of "hint" is reserved, and indicates that processors must ignore the alternate title that carries it.
A new base element, <keytext>, will be available for use when specifying the text to use for key references to the enclosing <topicref>. The link title may still be used to specify keyref text, but <keytext> is the preferred element for this purpose, and takes precedence.
When a <topicref> without a <keytext> element carries a key reference to a <topicref> element that does specify <keytext>, that key text is inherited by the referencing <topicref>.
With the exception of "navtitle", "searchtitle", and "hint", no special processing or output presentation is prescribed for <titlealt> roles. Processors should ignore them by default.
Remove @locktitle from the base map vocabulary.

Backwards compatibility

In current versions of DITA, <navtitle> in a map is essentially ignored unless @locktitle is set to "yes". Since @locktitle will be removed, and the new behavior will be for a map's alternate titles, including navigation titles, to take precedence over those in the topics, many - possibly most - existing uses of <navtitle> in maps will likely prove problematic unless they are modified.

The recommended migration solution is to add title-role="hint" to non-locked <navtitle> elements, since that is often the actual role being served by the element - as information for map authors without having to open the topic, but ignored for purposes of publication. Since this would override the default @title-role of the element, it's no longer a navigation title as far as DITA processors are concerned, and will be ignored.

Any <linktext> elements in maps will need to be renamed <linktitle>. Those inside <topicref> elements that define keys should also copy the element to <keytext>.

The DITA 1.x rules for key-base text will be replaced with the following simplified algorithm for finding text for empty key references:

The <keytext> element, if present.
The link title (<linktitle> or <titlealt> with a @title-role including "linktitle"), if present.
Normal title discovery.

If the contents of the <keytext> or link title contain markup invalid in context of the key reference, processors SHOULD remove those elements that would not be legal.

The specialization hierarchy of <navtitle> and <searchtitle> will be changed, to "- topic/titlealt altTitles-d/navtitle " and "- topic/titlealt altTitles-d/searchtitle ", respectively. This will require any existing specializations or constraints involving those elements to be updated to be compatible with DITA 2.0.

Migration plan

For <navtitle> elements in maps:

Existing maps containing <navititle> with locktitle="yes" remain unchanged except for the removal of @locktitle.
Other occurrences of <navititle> in maps should be given an explicit @title-role attribute specifying a role appropriate to the particular case.

For <linktext> elements in maps:

The element should be renamed <linktitle>.
An additional <keytext> element with the same contents should be generated when the enclosing <topicref> specifies @keys.

Uses of <keyword> to specify key text in maps will need to be modified such that the contents of the first keyword are copied to a new <keytext> element. Other ways of specifying key text - e.g. using matching elements - will require manual cleanup.

Any @locktitle attributes must be removed.

Any instances of content with explicit @class attributes will need to be modified with the new specialization hierarchy of <navtitle> and <searchtitle>.

Processors will need to tweak <navtitle>, <searchtitle>, and <linktext> handling as well as implementing generic <titlealt> handling and merging. Processors will need to implement support for <keytext>.

Existing map specializations that use other mechanisms for alternative titles - such as <ph> specializations inside <title> - may choose to modify their content model for alternate titles to take advantage of this feature, but existing approaches will also continue to work (and be a burden on processors).

Costs

Maintainers of the grammar files

The alternative titles domain will be a new grammar module that needs to be maintained.

Editors of the DITA specification

Â New topics:

o Container topic for alternative titles domain.

o New language reference topic for <titlealt>.

o Architectural specification topic describing <titlealt> processing, specifically merging of alternative titles between topicrefs and topics, with examples.

o New language reference topic for <keytext>.

o Update to the topic Processing key references to generate text or link text to discuss <keytext> and describe the new, simpler algorithm.

Â Updates to existing topics:

o The language reference topic for <titlealts> will likely need to be updated.

o The language reference topics for <navtitle>, and <searchtitle> will need to be moved to the alternative titles domain and updated.

o The topic Metadata in maps and topics will need to be updated to discuss <titlealt>.

o Likewise Reconciling topic and map metadata elements will need to be updated to discuss <titlealt>.

Vendors of tools

Processors will need to implement <titlealt> reconciliation between topics and maps, as well as updating <navtitle> handling. They will also need to modify the algorithm used for determining text for empty key references.

DITA community-at-large

Â Will this feature add to the perception that DITA is becoming too complex?

Not by much, and possibly the reverse. It may seem more complex to those of us inured to the idiosyncrasies of the current markup, but I hope the opposite is true. The reconciliation of topicref and topic alternate titles involves simple concatenation and first-wins precedence. This proposal will vastly simplify, and make explicit, the mechanism for alternative titles in maps, making it trivial for tools to determine map titles without having to treat <booktitle> as a special-case. Finally, it will remove the counter-intuitiveness inherent in the @locktitle attribute.

The new algorithm for key reference text determination is much simpler than the existing one, and so will reduce complexity.

Will it be simple for end users to understand?

Yes.

Producing migration instructions or tools

As noted above, many existing <navtitle> elements in map will likely require explicit @title-role attributes to avoid undesired navigation title behavior, and @locktitle attributes must be removed.

Certain

Example: Navigation titles

Consider the following series of topicrefs:

<topicref href="">

<topicref href="">

  <topicmeta>

    <navtitle>Topic Two (Map navtitle)</navtitle>

  </topicmeta>

</topicref>

<topicref href="">

  <topicmeta>

    <navtitle title-role="hint">Topic Three (Map navtitle hint)</navtitle>

  </topicmeta>

</topicref>

<topicref href="">

  <topicmeta>

    <titlealt title-role="navtitle">Topic Four (Map navtitle)</titlealt>

  </topicmeta>

</topicref>

Here is the ditabase document containing those three topics:

<dita>

  <topic id="one">

    <title>Topic One</title>

  </topic>

  <topic id="two">

    <title>Topic Two</title>

    <titlealts>

      <navtitle>Topic Two (Topic navtitle)</navtitle>

    </titlealts>

  </topic>

  <topic id="three">

    <title>Topic Three</title>

    <titlealts>

      <navtitle>Topic Three (Topic navtitle)</navtitle>

    </titlealts>

  </topic>

  <topic id="four">

    <title>Topic Four</title>

  </topic>

</dita>

The resulting navigation structure would look like this:

Topic One
Topic Two (Map navtitle)
Topic Three (Topic navtitle)
Topic Four (Map navtitle)

The first topic's navigation title is pulled from the title of the topic, since neither the map nor the topic specify a navigation title.

The second topic's navigation title comes from the map, as its navigation title takes precedence over that in the topic.

The navigation title for Topic Three comes from the topic because the entry in the map specifies title-role="hint", overriding the default value of "navtitle", thus nullifying its use as a navigation title.

Finally, the fourth topic's navigation title comes from the <titlealt title-role="navtitle"> in the map. Even though the element is not a <navtitle>, it is the @title-role that matters when determining the role of the alternate title, not the tag name or @class attribute.

Example: Custom Alternative Title Types

The content architect described under 'Use Cases' could create a Topic specialization with custom title elements.

<helpTopic id="topic167">

  <title>Doing the Thing in the Place where the Stuff Is</title>

  <titlealts>

    <windowtitle>Doing Things</windowtitle>

    <breadcrumbtitle>Doing the Thing</breadcrumbtitle>

  </titlealts>

They could also allow their map authors to overrule these alternative titles.

<topicref href="">

  <topicmeta>

    <breadcrumbtitle>Thing Doing</breadcrumbtitle>

  </topicmeta>

</topicref>

Example: Map Alternative Titles

A certain unnamed standards committee produces their specification document as a DITA map with a large number of alternative titles. Currently, in DITA 1.3, they use the Bookmap <pubtitlealt> element with @outputclass. For example:

<booktitle outputclass="specificationTitles">

 <mainbooktitle outputclass="specificationTitle">Darwin Information Typing Architecture (DITA)

  Version 1.3 Part 0: Overview</mainbooktitle>

 <booktitlealt outputclass="specificationSubtitle1"><keyword keyref="specification-level"/></booktitlealt>

 <booktitlealt outputclass="specificationLevel">0</booktitlealt>

 <booktitlealt outputclass="specificationApproved"><keyword keyref="approval-date"/></booktitlealt>

 <booktitlealt outputclass="specificationShorttitle">DITA Version 1.3 Specification</booktitlealt>

 <booktitlealt outputclass="specificationScope">part0-overview</booktitlealt>

</booktitle>

This is problematic for all sorts of reasons, but with this change they could rewrite this as follows:

<title>Darwin Information Typing Architecture (DITA) Version 1.3 Part 0: Overview</title>

  <bookmeta>

   <titlealt title-role="specificationSubtitle1"><keyword keyref="specification-level"/></titlealt>

   <titlealt title-role="specificationLevel">0</titlealt>

   <titlealt title-role="specificationApproved"><keyword keyref="approval-date"/></titlealt>

   <titlealt title-role="specificationShorttitle">DITA Version 1.3 Specification</titlealt>

   <titlealt title-role="specificationScope">part0-overview</titlealt>

   <!-- other metadata -->

  </bookmeta>

Example: Reconciling Map and Topic Alternate Titles

A <topicref> says:

<topicref href="">

  <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 says:

<titlealts>

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

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

</titlealts>

During processing, the two sets of elements will be concatenated together, 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 alternate 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 like this:

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

<titlealt title-role="flipbookTitle">Stuff</titlealt>

<titlealt title-role="breadcrumbTitle">Doin' Stuff</titlealt>

<titlealt title-role="longTitle">That thing you do when there's stuff that needs doing.</titlealt>

Example: Specifying Key Reference Text

The following element specifies the text to use for empty key references using the <keytext> element.

<keydef keys="companyName">

  <topicmeta>

    <keytext>Acme, Inc.</keytext>

  </topicmeta>

</keydef>

Example: Multiple Titles and Key Text and their Uses

The following topicref contains a number of alternate titles as well as key text.

<topicref keys="about" href="">

  <topicmeta>

    <navtitle>About the Product</navtitle>

    <linktitle>About This Product</linktitle>

    <searchtitle>About</searchtitle>

    <titlealt title-role="hint actual">About the Acme TextMax 5000</titlealt>

    <keytext>the "about" page</keytext>

  </topicmeta>

</topicref>

The <navtitle> will be used when rendering the table of contents.
The <linktitle> will be used when generating parent/child/sibling and relationship table-based related links to this topic.
The <searchtitle> will be used to provide the title in systems that support dynamic content searches.
The <titlealt> with the roles of "hint" and "actual" describes the actual title of the topic for the benefit of map authors, but will not be used in output by default. Custom processing may make use of the "actual" role for some purpose, but the DITA standard prescribes no special processing for it.
The <keytext> is used for empty key references to the "about" key.

Example: Alternate Titles and Key Text in Topicref Key References

The following topicref carries a key reference to the topicref in the previous example. It also provides some alternate key text and titles.

<topicref keyref="about">

  <topicmeta>

    <navtitle>About, Again</navtitle>

    <keytext>the alternate "about" page</keytext>

  </topicmeta>

</topicref>

The <navtitle> replaces the navigation title from the "about" key definition. The other alternate titles from that key definition are inherited by this topic reference. The other alternate titles from the "about" key definition are inherited by this <topicref>.
The <keytext> overrides that on the "about" key definition. If this <topicref> had not specified a <keytext>, it would have inherited the one from the "about" key definition.

dita message

Stage two: #16 Improvements to <titlealts>