Home > Single-sourcing with DocBook

Single-sourcing with DocBook


15 November 2005  
 

1  

Linking Outside the Box 
 

Cross referencing between XML documents 
 

Bob Stayton

Sagehill Enterprises 
 

http://www.sagehill.net 
email: bobs@sagehill.net 
831-566-8239


Linking Outside the Box

15 November 2005  
 

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).

 


Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

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> 

 


Linking Outside the Box

15 November 2005  
 

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.

 


Linking Outside the Box

15 November 2005  
 

6  

XML 1.0 linking 

  • ID attribute type creates a target.
  • IDREF creates a link.
  • Parser validates the link.
  • Stylesheet formats the link.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

8  

What about XLink? 

  • W3C Recommendation 27 June 2001.
  • xlink namespace linking attributes.
  • Bidirectional links.
  • Separate link bases.

Linking Outside the Box

15 November 2005  
 

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

Linking Outside the Box

15 November 2005  
 

10  

XLink mechanism 

  • Simple xlink using href attribute.
  • Link to XML file and ID target:
 

<xref xlink:href="../ug/book.xml#UseMouse"/>


Linking Outside the Box

15 November 2005  
 

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?

Linking Outside the Box

15 November 2005  
 

12  

Practical solution in DocBook 

  • Link to rendered documents.
  • Use the stylesheet to resolve links.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

14  

Use the XSL stylesheet 

  • No separate XLink processor.
  • Resolve and format.
  • Collect target data with same stylesheet that rendered it.
    • Includes any customizations.

 


Linking Outside the Box

15 November 2005  
 

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.

 


Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

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

 


Linking Outside the Box

15 November 2005  
 

20  

Olink attributes 

  • targetdoc - document identifier.
  • targetptr - ID attribute in the document.
  • xrefstyle - optional styling hint.

 


Linking Outside the Box

15 November 2005  
 

21  

Document identifier 

  • Not a filename.
  • Abstract reference.
  • Resolved at runtime.
    • Version, profile.
    • Output format (HTML, PDF).
    • Language.

Linking Outside the Box

15 November 2005  
 

22  

Database setup 

  • Define scope.
  • Assign document identfiers.
  • Create database framework file.
  • Generate target data files for each doc.

Linking Outside the Box

15 November 2005  
 

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>


Linking Outside the Box

15 November 2005  
 

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.

 


Linking Outside the Box

15 November 2005  
 

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>


Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

28  

Managing olinks 

  • Dependencies between documents!
  • When update a document:
    • Render it.
    • Regenerate target data at same time.
  • Manage releases.

 


Linking Outside the Box

15 November 2005  
 

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/">


Linking Outside the Box

15 November 2005  
 

30  

New DocBook capabilities 

  • Modular XML files.
  • Asynchronous processing.
  • Links to open source doc.
  • Language fallback.

Linking Outside the Box

15 November 2005  
 

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.

Linking Outside the Box

15 November 2005  
 

32  

Asynchronous processing 

  • Separate linking data.
  • Process one document, not all.
  • Departments feed into central database.
  • Manage target data updates.
  • Link to previous releases.

Linking Outside the Box

15 November 2005  
 

33  

Links to open source doc 

  • Open source DocBook doc.
  • Generate olink data file.
  • Assign targetdoc identifier.
  • Create olinks to it from your docs.

Linking Outside the Box

15 November 2005  
 

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" 

 


Linking Outside the Box

15 November 2005  
 

35  

In conclusion 

  • Olinks are easy to author.
  • Olinks are maintainable.
  • Customizable stylesheet processing.
  • Olinking widely used in DocBook today.

Linking Outside the Box

15 November 2005  
 

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/

Linking Outside the Box

Search more related documents:Single-sourcing with DocBook

Set Home | Add to Favorites

All Rights Reserved Powered by Free Document Search and Download

Copyright © 2011
This site does not host pdf,doc,ppt,xls,rtf,txt files all document are the property of their respective owners. complaint#nuokui.com
TOP