Embed Size (px)
Citation preview
15 November 2005 Linking Outside the Box 1
Linking Outside the Box
Cross referencing between XML documents
Bob Stayton
Sagehill Enterprises
http://www.sagehill.netemail: [email protected]
15 November 2005 Linking Outside the Box 2
Cross referencing for readers
►Hypertext has arrived!►Active links in HTML and PDF.►Author creates links.►Richer reader experience.
• Follow your interest.• Details if needed.• Instant gratification (maybe).
15 November 2005 Linking Outside the Box 3
Cross referencing for authors
►Good fit for modular content.• Connect to larger context.• Avoid tangents.
►Write once, refer many.►Simpler than reuse.►Single source for maintenance.►Lower translation costs.
15 November 2005 Linking Outside the Box 4
Example
"If you also want small caps in your print output, you will need to add something like this to your fo stylesheet customization layer:
<xsl:template match="emphasis[@role = 'sqlsyntax']">
<fo:inline font-variant="small-caps">
<xsl:apply-templates/>
</fo:inline>
</xsl:template>
15 November 2005 Linking Outside the Box 5
Generated text even better
►Chapter/figure number refs updated.►Title changes propagate to references.►Users get more accurate references.►Even less translation (empty element).►Flexible styling.
• Change global styles.• Permit instance variations.
15 November 2005 Linking Outside the Box 6
XML 1.0 linking
►ID attribute type creates a target.►IDREF creates a link.►Parser validates the link.►Stylesheet formats the link.
15 November 2005 Linking Outside the Box 7
XML 1.0 limitations
►Both ID and IDREF must be in same document.
►Forces large documents (sets of books).
►Or vague non-active references.►Modular XML files are invalid.
15 November 2005 Linking Outside the Box 8
What about XLink?
►W3C Recommendation 27 June 2001.►xlink namespace linking attributes.►Bidirectional links.►Separate link bases.
15 November 2005 Linking Outside the Box 9
Whither XLink?
►No general purpose XLink kit.• 4 of 5 W3C references are 404 Not Found.
►XBRL (eXtensible Business Reporting Language)
►Renewed activity:• Extending XLink 1.0, W3C Working Group,
Note 27, January 2005
15 November 2005 Linking Outside the Box 10
XLink mechanism
►Simple xlink using href attribute.►Link to XML file and ID target:
<xref xlink:href="../ug/book.xml#UseMouse"/>
15 November 2005 Linking Outside the Box 11
Resolving XLinks
►Display XML target in browser?►Style target with current stylesheet?
• Or with target's stylesheet?
►Numbered item: process whole document to generate count.
►What about conditional text in target?►Stylesheet parameter options?
15 November 2005 Linking Outside the Box 12
Practical solution in DocBook
►Link to rendered documents.►Use the stylesheet to resolve links.
15 November 2005 Linking Outside the Box 13
Resolve to rendered documents
►Hard to link to XML.►Easy to link to HTML, PDF.►All conditional text already resolved.►All stylesheet parameters were set.►Use ulink? Too fragile.
15 November 2005 Linking Outside the Box 14
Use the XSL stylesheet
►No separate XLink processor.►Resolve and format.►Collect target data with same stylesheet
that rendered it.• Includes any customizations.
15 November 2005 Linking Outside the Box 15
Cross reference design goals
►Make it easy for authors to link.►Minimize maintenance overhead.►Support HTML, PDF, other formats.►Provide styling flexibility.►Permit modular files that validate.
15 November 2005 Linking Outside the Box 16
Cross reference design features
►Link to any document in a collection.►Avoid reprocessing target documents.►Link to previously published content.►Generate accurate link text.►Flag unresolved links.
15 November 2005 Linking Outside the Box 17
Cross referencing in DocBook
►xref - to internal ID, generate text.►link - to internal ID, authored text.►ulink - to external URL.►olink - link between DocBook docs.
15 November 2005 Linking Outside the Box 18
DocBook olink mechanism
►Extract link target info to database.• Info on all potential targets.• As rendered.
►Many documents in the olink database.►Stylesheet reads database.
• Look up target.• Use info to style link.
15 November 2005 Linking Outside the Box 19
Easy for authors
►Two attributes on empty olink element:
For more information, see <olink targetdoc="tdg" targetptr="custom"/>.
►Resolves to: For more information, see Chapter 5, "Customizing
DocBook" in DocBook: The Definitive Guide.
15 November 2005 Linking Outside the Box 20
Olink attributes
►targetdoc - document identifier.►targetptr - ID attribute in the document.►xrefstyle - optional styling hint.
15 November 2005 Linking Outside the Box 21
Document identifier
►Not a filename.►Abstract reference.►Resolved at runtime.
• Version, profile.• Output format (HTML, PDF).• Language.
15 November 2005 Linking Outside the Box 22
Database setup
►Define scope.►Assign document identfiers.►Create database framework file.►Generate target data files for each doc.
15 November 2005 Linking Outside the Box 23
Database framework olinkdb.xml
<?xml version="1.0"?>
<!DOCTYPE targetset [
<!ENTITY uglinks SYSTEM "userguide/target.db">
<!ENTITY admin SYSTEM "admin/target.db"> ]>
<targetset>
<document targetdoc="ug">
&uglinks;
</document>
<document targetdoc="ag">
&admin;
</document>
</targetset>
15 November 2005 Linking Outside the Box 24
Collect target data
►For each document:
saxon userguide.xml docbook.xsl
collect.xref.targets="yes"
►Generates target.db data file.►Each doc's data is updated separately.►Framework always reads latest update.
15 November 2005 Linking Outside the Box 25
Target data
<div element="book" targetptr="dbdefguide" href="#dbdefguide">
<ttl>DocBook: Definitive Guide</ttl> <xreftext>DocBook: Definitive Guide</xreftext> <div element="chapter" targetptr="custom"
number="5" href="#custom"> <ttl>Customizing DocBook</ttl> <xreftext>Chapter 5, "Customizing
DocBook"</xreftext> <obj element="figure" number="5.1">...</obj> <div element="section" number="">...</div> </div></div>
15 November 2005 Linking Outside the Box 26
Processing olinks
►Pass reference to framework file:
saxon adminguide.xml docbook.xsl
target.database.document="olinkdb.xml"
►Stylesheet locates targetdoc. ►Stylesheet gets info for targetptr.►Assembles text and styles it.
15 November 2005 Linking Outside the Box 27
Assembling link text
►Default: xref from target stylesheet.►Option to use current stylesheet.►Optional xrefstyle attribute:
• named styles in current stylesheet.• select components (title, number).• style template.
►Add book title.
15 November 2005 Linking Outside the Box 28
Managing olinks
►Dependencies between documents!►When update a document:
• Render it.• Regenerate target data at same time.
►Manage releases.
15 November 2005 Linking Outside the Box 29
Manage destinations
►Use baseuri for each target doc.►Prefixed to each rendered olink.
<document targetdoc="ag"
baseuri="file:///doc/admindoc/">
...
<document targetdoc="progref" baseuri="http://mycompany/doc/">
15 November 2005 Linking Outside the Box 30
New DocBook capabilities
►Modular XML files.►Asynchronous processing.►Links to open source doc.►Language fallback.
15 November 2005 Linking Outside the Box 31
Modular XML files
►Use XInclude instead of system entity.• Add DOCTYPE for validation.
►Use olink between modules instead of xref.
►Each module is valid mini document.
15 November 2005 Linking Outside the Box 32
Asynchronous processing
►Separate linking data.►Process one document, not all.►Departments feed into central database.►Manage target data updates.►Link to previous releases.
15 November 2005 Linking Outside the Box 33
Links to open source doc
►Open source DocBook doc.►Generate olink data file.►Assign targetdoc identifier.►Create olinks to it from your docs.
15 November 2005 Linking Outside the Box 34
Language fallback
►Some docs translated, others not.►Framework supports multiple langs.►Stylesheet can try current lang, and fall
back to another lang if not found.►Stylesheet parameter:
olink.lang.fallback.sequence="de fr en"
15 November 2005 Linking Outside the Box 35
In conclusion
►Olinks are easy to author.►Olinks are maintainable.►Customizable stylesheet processing.►Olinking widely used in DocBook today.
15 November 2005 Linking Outside the Box 36
Resources
► DocBook XSL: The Complete Guide• http://www.sagehill.net/docbookxsl/
► DocBook: The Definitive Guide• http://docbook.org/tdg/en/html/docbook.html
► DocBook SourceForge project:• http://docbook.sf.net/
