dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [dita] Scenario for cross-deliverable referencing
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: dita@lists.oasis-open.org
- Date: Tue, 13 Sep 2011 10:57:27 -0400
Here are the markup examples I owed
to Eliot:
Assuming A.ditamap contains references
to topics in B.ditamap:
Starting input:
A.ditamap
<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-->
B.ditamap
<topicref
keys="b1" href=""b1.dita"/>
A1.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:
AtoPDF.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"/>
PDF/B.ditamap
<topicref
keys="b1" href=""B.pdf#b1"/>"
A1.dita
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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
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
scenario:
- 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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]