OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Scenario for cross-deliverable referencing

Here are the markup examples I owed to Eliot:

Assuming A.ditamap contains references to topics in B.ditamap:

Starting input:

        <topicref keys="a1" href=""a1.dita"/>
        <mapref processing-role="resource-only" href=""b.ditamap"/>"        <!--gets keys to allow a1.dita to reference b1.dita via keyref-->

        <topicref keys="b1" href=""b1.dita"/>

        Hey here's a cross ref: <xref keyref="b1"/> <!--resolves to b1.dita at authoring time-->

Add map shells to pull in deliverable-specific key mappings, and build out pdf/b.ditamap:

        <mapref processing-role="resource-only" href=""pdf/b.ditamap"/>" <!--overrides keys to make b1 key go to a pdf bookmark
        <mapref href=""A.ditamap"/>

        <topicref keys="b1" href=""B.pdf#b1"/>"        

        Hey here's a cross ref: <xref keyref="b1"/> <!--now resolves to B.pdf#b1 at build time-->

Some additional thoughts

The map shells and the deliverable-specific key mappings are really build-specific items, like a ditaval. We could consider simplifying the construction by eliminating the map shell and just make key definition files be something we can either produce or consume as part of the build, the way we consume ditavals today.

My fundamental concern is that the mappings for a given deliverable can only be known at the time of build for the given deliverable - issues like output filename, chunking options, ditaval usage, etc.  will all affect what is available to be linked to in the deliverable. That's why I keep focusing on a method that will allow the build for a deliverable to define the key mappings to be used when building another deliverable that links to it.

The question of key scoping to avoid conflicts remains, but is equally important to both the cross-deliverable and same-deliverable use cases.

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

From: Michael Priestley/Toronto/IBM@IBMCA
To: dita@lists.oasis-open.org
Date: 09/06/2011 10:21 AM
Subject: [dita] Scenario for cross-deliverable referencing

This was my todo from last week's mtg - sorry I'm leaving it to the wire.

This describes a solution that can be implemented today - I still think there more work to be done, including:

-  a general solution for key scoping (but not deliverable-based scoping since the boundaries of deliverables are mutable, as I'm trying to show here).

- a standardized approach for cross-deliverable referencing - if we want to encourage this approach, for example, or propose an alternative - but we should be providing some guidance to vendors on how to implement so that the solution is cross-vendor compatible


- we need to produce PDFs for each chapter of a book, as well as a single big PDF that contains all chapters

- the chapters contain cross-references to content in other chapters, which needs to be resolved as a cross-deliverable link in the single-chapter PDFs but as a local link in the single big PDF case

- each chapter is represented by a separate map

- each topicref in the map has a uniquely addressable key (using whatever general scoping mechanism we choose to implement)
- the book as a whole is represented by a master map that pulls in the others

solution for individual chapter case:

- for each chapter, execute a partial PDF build, which does not transform the content but does preprocess the map to turn each topicref href into a form appropriate for the deliverable being produced (ie, including the filename of the PDF being produced, with appropriate anchor syntax)

       this results in a deliverable-specific set of key mappings

- for each chapter, create a master map that includes the chapter being built and then resource-only inclusions of the deliverable-specific maps for all other chapters

- for each chapter's master map, execute a full PDF build

       this results in a chapter-level PDF with all links to other chapter resolved correctly

solution for whole book case:

- build normally

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]