Cross%20referencing%20between%20XML%20documents

1
Linking Outside the Box

• Cross referencing between XML documents
• Bob Stayton
• Sagehill Enterprises

http//www.sagehill.netemail bobs_at_sagehill.net8
31-566-8239
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).

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.

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
• ltxsltemplate match"emphasis_at_role
  'sqlsyntax'"gt
• ltfoinline font-variant"small-caps"gt
• ltxslapply-templates/gt
• lt/foinlinegt
• lt/xsltemplategt

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.

6
XML 1.0 linking

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

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.

8
What about XLink?

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

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

10
XLink mechanism

• Simple xlink using href attribute.
• Link to XML file and ID target
• ltxref xlinkhref"../ug/book.xmlUseMouse"/gt

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?

12
Practical solution in DocBook

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

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.

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

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.

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.

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.

19
Easy for authors

• Two attributes on empty olink element
• For more information, see ltolink
  targetdoc"tdg" targetptr"custom"/gt.
• Resolves to
• For more information, see Chapter 5,
  "Customizing DocBook" in DocBook The Definitive
  Guide.

20
Olink attributes

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

21
Document identifier

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

22
Database setup

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

23
Database framework olinkdb.xml

• lt?xml version"1.0"?gt
• lt!DOCTYPE targetset
• lt!ENTITY uglinks SYSTEM "userguide/target.db"gt
• lt!ENTITY admin SYSTEM "admin/target.db"gt gt
• lttargetsetgt
• ltdocument targetdoc"ug"gt
• uglinks
• lt/documentgt
• ltdocument targetdoc"ag"gt
• admin
• lt/documentgt
• lt/targetsetgt

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.

25
Target data

• ltdiv element"book" targetptr"dbdefguide"
  href"dbdefguide"gt
• ltttlgtDocBook Definitive Guidelt/ttlgt
• ltxreftextgtDocBook Definitive Guidelt/xreftextgt
• ltdiv element"chapter" targetptr"custom"
  number"5" href"custom"gt
• ltttlgtCustomizing DocBooklt/ttlgt
• ltxreftextgtChapter 5, "Customizing
  DocBook"lt/xreftextgt
• ltobj element"figure" number"5.1"gt...lt/objgt
• ltdiv element"section" number""gt...lt/divgt
• lt/divgt
• lt/divgt

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.

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.

28
Managing olinks

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

29
Manage destinations

• Use baseuri for each target doc.
• Prefixed to each rendered olink.
• ltdocument targetdoc"ag"
• baseuri"file///doc/admindoc/"gt
• ...
• ltdocument targetdoc"progref" baseuri"http//myco
  mpany/doc/"gt

30
New DocBook capabilities

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

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.

32
Asynchronous processing

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

33
Links to open source doc

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

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"

35
In conclusion

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

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/