DITA Proposed Feature #38--Bookmap

Add book-level processing to DITA based upon revised bookmap demo.


Representative:

Don Day for the bookmap subgroup

Longer description

The DITA community has pointed out the need for a native DITA mechanism for producing books from DITA topics. In particular, we need

The book model must rigorously separate all information about the layout and presentation of the book from the actual content so the content can be reused in other contexts and so multiple layout styles can be applied to the same book.

The book model should provide enough information so that an XSLT transform could generate a good XSL-FO representation of a book. An XSL-FO processor such as FOP could then convert the generated XSL-FO to PDF.

Since their introduction two years ago as a demo capability intended to meet the original requirements, the bookmap and bkinfo specializations have become more widely used within the user community. As a basic concept, they have received a high acceptance. Due to the wide use of the bookmap, a list of additional requirements to the existing bookmap/bkinfo has come in from different companies like IBM, Nokia, and KONE. In addition, current DITA 1.1 proposals offer the possibility for elegantly refining the original design. This proposal is based on these requirements and other contingent TC proposals.

Feature Owner(s)

Nancy Harrison (IBM), Chris Kravogel (Seicodyne), JoAnn Hackos (Comtech), Don Day (IBM), Jennifer Linton (Comtech)

Requirements gathered from:
  • Chris Kravogel (representing KONE)
  • Indi Liepa (Nokia)
  • Simcha Gralla, Nancy Harrison (IBM)
  • Jennifer Linton (Comtech)

Scope

Assumptions:

The proposal is based on the existing "dita132" version of the bookmap demo DTD in the DITA Open Toolkit. The bkinfo specialized topic for metadata is deprecated, and the topicmeta child of bookmap is specialized to contain structured metadata (based on bkinfo and also new requirements) based on the new <data> element.

Several proposed features will actually inherit into bookmap from ditamap and topic metadata if some dependent other features are approved for 1.1, therefore they are listed here as related, but are not addressed in the scope of this proposal:
  • #9 Specialize new DATA element from keyword http://www.oasis-open.org/apps/org/workgroup/dita/download.php/14073/Issue9.html
  • #41 Expanded content for shortdesc (applies to Indi's requirement for transitional text--specialize the shortdesc in topicmeta in map to keep "connective text" in the structural context, not in topics)
  • #48 Support change history and annotations in prolog (not accepted for 1.1 scope, but the requirement seems to be covered already in the revised "bookmeta" element)
  • #14 Specialize glossary entry and definition elements
  • #45 (family of sub-items) Indexing elements (See, See Also)
Some best practices are to be observed where applicable:
  • #4 Use subset of OASIS xNAL standard for addresses

Note: The rest of the discussion in this section are design notes that did not fit elsewhere in to the proposal template.

The general constraints for the proposal were to review existing practice to discover any book structures that were not already in the bookmap definition, and to generally clean up the book metadata scattered in several locations. We found the general book structure to be basically okay except for the additional design work needed to finish up the "booklist " structures for collected data.

Upon review of the existing bookmap specialization as used in the DITA Open Toolkit's demo/book directory, and of the known requirements, it was clear that all requirements could be met through a series of mostly backwards-compatible updates to new element definitions and content model additions. The deltas provide broader base capability that companies can specialize in order to constrain behaviors to their requirements (versus creating "parameter-driven" designs that introduce style into the design).

The main change from the original bookmap design is the consolidation of book metadata that had been previously spread across three different parts of markup into a unified book metadata design fully contained within the bookmap structure itself, making use of the new "data" element.

The lists requirement deals with how to specify both the location and content of special chapter-like constructs that generally have content derived by query during processing, such as a Table of contents, or lists of terms or endnotes. The balance here was for the design to allow author flexibility to specify which lists are important for a deliverable while leaving the ordering and location of these parts up to the policies of the house style (enforced by the transforms). The solution is a specialized topicgroup (booklists) at the start of the bookmap that has specialized topicrefs that represent the various booklist types. Authors can insert 0 or more of these "markers" into the booklists parent, where they represent instructions to the formatter to generate the appropriate content in the house style. A general override transform can offer call-templates that can be arranged in different order or commented out to effect a house policy for layout of such affordances. This increases the portability of the base bookmap between different processors.

Two requirements (transitional text between topics and limited nesting) were felt to be examples of further specialization that an organization can impose/infuse into local practice. Transitional text can be effected by specializing a topicref so that its topicmeta/shortdesc is available for "inline" discourse between other topicrefs in a map. Nesting limits can be effected locally by specializing topics down to a cutoff depth, as with DocBook's numbered sections, or by creating XSLT that counts the levels and generates a report of out-of-bound nesting.

Use Cases

{Describe this feature's use, as if ideally implemented.}

Use Case 1: First Contact with Bookmap
At the first contact with bookmap/bkinfo it looked as a promising specialization. However it became difficult to understand the meaning of a couple of elements and structures. Any guidance of how to use them was missing. An language reference guide would help a lot.
Use Case 2: Unlimited Nesting
Bookmap allows unlimited nesting of topics. This degree of freedom results in poor linear documents. More control or constraints would help.
Use Case 3: Authoring book metadata
As the author opens a new bookmap, the specialized topicmeta element for the specialized map offers a set of specialized sections for the book metadata. All information that was formerly spread across three locations is now consolidated in a single location for ease of maintenance, less duplication of effort, and simpler documentation.
Use Case 4: Print on demand booklets
Users reading at a Web-based Information Center will select some articles and arrange the desired sequence, then submit the collection for printing on demand. The topics are actually aggregated by bookmap and processed into PDF that has a basic cover, ToC, all collected copyright attributions and terms of use, and "chapters" of content. The PDF is returned within seconds to the user either by URL or in email.

Technical Requirements

The current collection of bookmap-only requirements that inform on the proposed design are:

Implementing these updates to the existing bookmap base (DTDs, Schemas, tools) will generally require:
  1. Addition of some new elements into existing content models (backwards compatible)
  2. Introduction of a new domain element (backwards compatible)
  3. Modifying one element from PCDATA to contain structured title content.
  4. Using the newly defined <data> element as the archetype for extending new metadata structures in the bookmap's topicmeta to consolidate and enrich the book metadata structures.

Costs

Benefits

The use of the consolidated bookmap would allow users to create a cohesive linear document out of their topics. They would be able to surround their current DITA topics with the information required by their organizations for published materials.

The bookmap proposal enables existing maps of information to be conrefed into bookmap structures, making it faster to produce a book based largely on existing ditamaps.

Time Required

Structures


Table 1. bookmeta, booklists, notices
New structurenaming influenceslegacy fragmentproposed declarationcontent model
bookmetaafter "topicmeta for books"bkinfo, prolog, bkbasicinfospecialized topicmeta, first in bookmapThe structures that follow!
booklistsafter "lists for books"not previously implementedspecialized topicgroup, first in bookmap following bookmeta, populated with specialized topicrefs.Toc, figures, tables, glossary terms, etc.. Zero or more occurance (empty parent is okay). No @href means generate the content; provided @href means use that content.
special noticespeer to edition notices; contains terms and other legal/policy info.not previously implementedspecialized topicrefhref to any topic type



Table 2. Author information
New structurenaming influenceslegacy fragmentproposed declarationContent model
Author Information.none - containerbookmeta/authorInformation(person | organization)*, contact*
personDITA, DocBook, IBMIDDocbkinfo/bkinfobody/bkhistory/bkauthored/personbookmeta/authorInformation/personhonorific?, givenname*, middlename*, familyname*, lineage?, address*, phone*, resource*, summary?, affiliations?, otherinfo*
organization.bkinfo/bkinfobody/bkhistory/bkauthored/organizationbookmeta/authorInformation/organizationorgname?, address*, phone*, resource*, summary?, otherinfo*
contact..bookmeta/authorInformation/contact(person | organization)*
phoneDITA, DocBook, IBMIDDocperson/phone, organization/phonebookmeta/person/phone, bookmeta/organization/phoneoffice*, fax*, cellular*, URL*


Note: This leaves out the "Contact department" request. I am not sure where to list that - should it be part of the <person> model? An addition to <contact>?

Note: Unsure how to set the model of the phone element - how to identify the different types? Different numbers, or should there be a marker (such as <cellular/>) inside the phone element?

Note: The content model for person, organization, and elements within those is the same in the original bkinfo and in this new proposal.


Table 3. Publisher information
New structurenaming influenceslegacy fragmentproposed declarationContent model
Publisher Information.none - containerbookmeta/publisherInformation(person | organization)*, bkprintloc*, bkpublished*, colophon?
bkpublished.bkinfo/bkinfobody/bkhistory/bkpublishedbookmeta/publisherInformation/bkpublishedsame as in bkinfo
colophon..bookmeta/publisherInformation/colophonempty - this would be a reference to the topic that describes the colophon


Note: The bkpublished information moved from bkhistory in the original bkinfo.


Table 4. Book History
New structurenaming influenceslegacy fragmentproposed declarationContent model
book change historyDITAbkinfo/bkinfobody/bkhistorybookmeta/bkChangeHistory(*(%bkreviewed;) | (%bkedited;) | (%bktested;) | (%bkapproved;) | (%bkevent;))*


Title Information / Book Identification


Table 5. Title Information
New structurenaming influenceslegacy fragmentproposed declarationcontent model
BookTitleDITA, IBMIDDoc, DocBookNo global containerbkbooktitle.
Book LibraryDITA, IBMIDDoc, DocBookbkinfo/bkid/bkvolume/bklibrarybkbooktitle/bklibrary.
Book TitleDITA, IBMIDDoc, DocBookbkinfo/titlebkbooktitle/bktitle.
Short/Abbreviated TitleDocbook (titleabbrev); IDDoc (stitle)bkinfo/bktitlealts/bktitleabbrevbkbooktitle/bktitlealt.



Table 6. Book Identification
New structurenaming influenceslegacy fragmentproposed declarationcontent model
Book identificationDITA, IBMIDDoc, DocBookbkinfo/bkidbookmeta/bkid.
Book/document NumberDITA, IBMIDDoc, DocBookbkinfo/bkid/bknumbookmeta/bkid/bknum.
ISBNDITA, IBMIDDoc, DocBookbkinfo/isbnbookmeta/bkid/isbn.
Part number.bkinfo/bkpartnobookmeta/bkid/bkpartno.
Volume number.bkinfo/bkid/bkvolume/bkvolidbookmeta/bkid/bkvolume.


Copyright


Table 7. Copyrights
New structurenaming influenceslegacy fragmentproposed declarationcontent model
bkrightsDITA, IBMIDDoc, DocBookbkinfo/bkrightsbookmeta/bkrights.


Bookmap map

A specialization of map to control the aggregation of topics. In much the same way that map currently organizes topics for an online deliverable, the bookmap defines the hierarchical structure for topics in a book.

Bookmeta structures

A specialization of topicmeta to provide the details about the book.

Booklist topics

Specializations of topic to provide listings that cannot or might not be generated from the book information alone.

Appendix: Migration survey

A note was appended to dita-users inviting comment by current users of bookmap to gather an understanding of expected migration issues.


The following information will be augmented as new results come in, and will be rolled up in a migration discussion in the pending Design document for the bookmap proposal (to describe some migration scenarios and suggest some best practices for migration implementors (vendors, users).

David Cramer

I've implemented a dita-based system for a small shop that uses the bookmap demo stuff for pdfs.

I'm not too worried about changes to the bookmap content model because I figure conversion can be done programmatically and invisibly (i.e. have it check to see if you're using the demo bookmap and if so, convert it to the new boomap before processing).

I should think supplying a simple demo2release.xsl for the bookmap would be enough.

Mark Poston (Mekon)

I was considering whether to support bookmaps directly in the FrameMaker adapter we are working on. This would be for a future release of the adapter.

In addition, bookmaps would be more appropriate to users who are working in FrameMaker. We are also considering developing a FrameMaker authoring DITA solution and my thoughts were that bookmaps might be the way to go.

Indi Liepa (Nokia)

IBM bookmap plays a key role in our DITA-based environment at Nokia...

We have been waiting for the bookmap design to stabilise before we migrate to OASIS 1.0 so that we can take the new bookmap design into account and only carry out one major migration effort rather than two. We have planned and budgeted for conversion and migration to formalised OASIS bookmap processing in 2006. This move is timed to coincide with formal OASIS DITA support in the content management system we are using.

We have specialised bookmap to meet very specific needs and user group requirements. We do not have a huge amount of DITA IBM bookmap legacy data to migrate or convert - somewhere around 700 masters in our production environment. The most challenging area is re-educating authors who have become familiar with our current specialised bookmap and how it is processed.