The goal of the redesign is to remediate problems but avoid breaking backward
compatibility.
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 company wants to create a custom cover page for their PDF documents and they need more
metadata in the bookmap
The current version of DITA Bookmap does not support <ditavalref> at
the root level. The first instance where <keydefs> can be defined is in
<frontmatter>.
- 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 children of
<bookmap>, then the <ditavalref> only
applies to the children of that element.
Proposed solution
The purpose of the proposal is to add some enhancements to bookmap, with a minimal amount of
impact at the processing end of the pipeline but will make things a bit easier for the end user.
- Add
<ditavalref> before <frontmatter>
- Create a placeholder or anchor element that will allow users to create specializations to
extend bookmap markup functionality
- Create a domain specialization to group
<keydefs> prior to
<frontmatter>.
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.
Provide a detailed description of how the solution will work. Be sure to include the following details:
- DTD and Schema modifications.
-
- New domain
-
- Bookmap Keydefs
- 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
<bookmapresources>
- New element
-
<bookmapresources>
- This element is a placeholder that would allow specializations of
<topicref> to be available in a bookmap.
- The element is optional after the
<bookmeta>.
<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
<bookmapresources> and
before <frontmatter>.
<bookmakers>
- This element will be used to define
<keydefs>
for <bookmap>.
- Processing impact
-
None. <keydefs> and <ditavalref> are already
supported features of DITA 1.3.
- 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 files to
support the solution for this proposal.
- A new topic for documenting the domain and the placeholder 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.
Examples
Sample usage in a bookmap:
<?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>
<bookmapkeydefs>
<keydef keys="test" href=""></keydef>
</bookmapkeydefs>
<ditavalref href=""/>
</bookmap>
Element definition in the bookmap DTD:
<!ENTITY % bookmap.content
"((%title; | %booktitle;)?,
(%bookmeta;)?,
(%bookmapresources;)?,
(%ditavalref;)?,
(%frontmatter;)?,
(%chapter;)*,
(%part;)*,
((%appendices;)? |
(%appendix;)*),
(%backmatter;)?,
(%reltable;)*)"
>
Element
override in the bookmap
shell:
<!ENTITY % bookmapresources "%bookmapkeydefs-d-bookmapresources;
">
