DITA 2.0 proposed feature #29
The goal of the redesign is to remediate problems but avoid breaking backward compatibility.
Modify bookmap design
- Proposal version
- 1.1
- Completion date
- March 27, 2018
- Champion of the proposal
- Eric Sirois
- Initial Suggestion
- https://lists.oasis-open.org/archives/dita/201703/msg00019.html
- Links to minutes where this proposal was discussed at stage 1 and moved to stage 2
- https://lists.oasis-open.org/archives/dita/201705/msg00091.html
- GitHub Issue
- https://github.com/oasis-tcs/dita/issues/29
Original requirement or use case
Overall the bookmap DTD has not been updated as part general DITA releases for a couple
releases. It is missing some convenient key features that were added as part of DITA 1.2 and
1.3. The proposal will make it easier to make use of <ditavalref>
at
the root level and make it easier to create and maintain keydefs.
Use cases
- A writer wants to create a keydefs for a map in a convenient location in the
map.
The current version of the DITA Bookmap does allow keydefs to be created, but you need to do it inside one of the main top-level elements. like
<frontmatter>
. But it's not convenient because it's buried in an unrelated element. - A writer wants to specify a ditaval used for the whole map via a
<ditavalref>
.The current version of the DITA Bookmap does not allow
<ditavalref>
as an immediate child of<bookmap>
. Creating them inside one of the child elements of<bookmap>
, like<frontmatter>
, then the<ditavalref>
only applies to the children of that element. - A writer wants to indicate a list of
<amendments>
in the<frontmatter>
of a book. - A writer wants to use
<glossref>
to reference a glossary topic within<glosslist>
.
Proposed solution
- Add
<ditavalref>
before<frontmatter>
- Create a
<mapresources>
as an element that will allow users to reference elements that are specializations of<topicref>
. - Add
<amendments>
to<frontmatter>
. If<amendments>
contains an@href
, then process as expected. Otherwise, process the content for revision history - Add
<glossref>
to element content model for<glosslist>
.
Benefits
- Authors will benefit from the more intuitive use of keydefs.
- Information architects/developers will benefit being able to add a specialization for custom processing of bookmaps.
- Information architects will be able to use the same bookmap for multiple outputs using different set of conditions
Technical requirements
This change is adding two elements, that already supported in DITA 1.3, to the root content
model of the bookmap DTD and as such, will have essentially no technical
impact. There will be
an impact for implementing the logic to support change-history from
<amendments>
- DTD and Schema modifications.
-
- New domain
-
- Map resources
- Add a domain specializations that will allow the definition of a
wrapper element to define
<keydefs>
in a<bookmap>
or other strictly constrained publication maps. This domain is based on<mapresources>
- Add a domain specializations that will allow the definition of a
wrapper element to define
- Map resources
- New element
-
<mapresources>
- This element is a container that allows specializations of
<topicref>
to be available in a bookmap. The element is defined as resource-only element. The element also allows @keyscope. - The element is optional after the
<ditavalref>
.
- This element is a container that allows specializations of
- Add existing DITA elements to content models in bookmap
-
<ditavalref>
- This is an existing element that is available in the base
<map>
. We are simply making it available in the top level portion of<bookmap>
- The element is optional after the
<bookmeta>
.
- This is an existing element that is available in the base
<glossref>
- This is an existing element that is available in the base
<map>
. We are simply making it available in the top level portion of<bookmap>
- The element is optional after the
<glosslist>
.
- This is an existing element that is available in the base
<amendments>
- This is an existing element that is available in
<backmatter>
. We are simply making it available in<frontmatter>
and adding behaviour on the processing side. - The element is optional in
<frontmatter>
- This is an existing element that is available in
- Processing impact
-
<ditavalref>
and<glossref>
are already supported features of DITA 1.3. And<mapresources>
is a specialization of topicref as a resource-only element.For
<amendments>
, if the element does not have a reference to a topic, then process the content in the map as revision history when<change-historylist>
element exist.
- Overall usability
- Current DITA users and current document type shells will be unaffected. Usability of authoring will ultimately be improved due to better management of keydefs and use of ditavalrefs in the bookmap.
Costs
- The main bookmap files need to be updated with the addition of a new domain file to support the solution for this proposal.
- A new topic for documenting the domain and the container element. As well as an update to the bookmap topic.
- Since we are adding elements that are already supported in DITA 1.3, there is no impact to processors and XML tools.
- Adding functionality in the base PDF processing to treat
<amendments>
without an@href
to auto-generate a revision history, based on the<change-historylist>
.
Examples
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA 2.0 BookMap//EN" "bookmap.dtd">
<bookmap>
<booktitle>
<mainbooktitle>Test</mainbooktitle>
</booktitle>
<ditavalref href=""/>
<mapresources>
<keydef keys="test" href=""></keydef>
</mapresources>
</bookmap>
<!ENTITY % bookmap.content
"((%title; | %booktitle;)?,
(%bookmeta;)?,
(%ditavalref;)*,
(%mapresources;)*,
(%frontmatter;)?,
(%chapter;)*,
(%part;)*,
((%appendices;)? |
(%appendix;)*),
(%backmatter;)?,
(%reltable;)*)"
>
<!ENTITY % mapresources "%mapresources-d-mapresources;
">
Domain definition:
<!ENTITY % mapresources
"mapresources" >
<!-- ============================================================= -->
<!-- ELEMENT DECLARATIONS -->
<!-- ============================================================= -->
<!ENTITY % mapresources.content
"(%topicref;)*"
>
<!ENTITY % mapresources.attributes
"outputclass
CDATA
#IMPLIED
keyscope
CDATA
#IMPLIED
processing-role
CDATA
'resource-only'
%univ-atts;"
>
<!ELEMENT mapresources %mapresources.content;>
<!ATTLIST mapresources %mapresources.attributes;>
<!ATTLIST mapresources %global-atts; class CDATA "+ map/topicref mapresources-d/mapresources ">
Domain entity definition:
<!ENTITY % mapresources-d-mapresources
"mapresources"
>
<!ENTITY mapresources-d-att
"(map mapresources-d)"
>
Adding
amendments to frontmatter
<!-- LONG NAME: Front Matter -->
<!ENTITY % frontmatter.content
"(%amendments; |
%bookabstract; |
%booklists; |
%colophon; |
%dedication; |
%draftintro; |
%notices; |
%preface; |
%topicref;)*"
>
<!-- LONG NAME: Glossary List -->
<!ENTITY % glossarylist.content
"((%topicmeta;)?,
(%topicref;|
%glossref;)*)"
>