15 November 2005Linking Outside the Box1 Cross referencing between XML documents Bob Stayton Sagehill Enterprises

15 November 2005Linking Outside the Box2 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 2005Linking Outside the Box3 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 2005Linking Outside the Box4 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:

15 November 2005Linking Outside the Box5 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 2005Linking Outside the Box6 XML 1.0 linking ► ID attribute type creates a target. ► IDREF creates a link. ► Parser validates the link. ► Stylesheet formats the link.

15 November 2005Linking Outside the Box7 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 2005Linking Outside the Box8 What about XLink? ► W3C Recommendation 27 June ► xlink namespace linking attributes. ► Bidirectional links. ► Separate link bases.

15 November 2005Linking Outside the Box9 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 2005Linking Outside the Box10 XLink mechanism ► Simple xlink using href attribute. ► Link to XML file and ID target:

15 November 2005Linking Outside the Box11 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 2005Linking Outside the Box12 Practical solution in DocBook ► Link to rendered documents. ► Use the stylesheet to resolve links.

15 November 2005Linking Outside the Box13 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 2005Linking Outside the Box14 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 2005Linking Outside the Box15 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 2005Linking Outside the Box16 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 2005Linking Outside the Box17 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 2005Linking Outside the Box18 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 2005Linking Outside the Box19 Easy for authors ► Two attributes on empty olink element: For more information, see. ► Resolves to: For more information, see Chapter 5, "Customizing DocBook" in DocBook: The Definitive Guide.

15 November 2005Linking Outside the Box20 Olink attributes ► targetdoc - document identifier. ► targetptr - ID attribute in the document. ► xrefstyle - optional styling hint.

15 November 2005Linking Outside the Box21 Document identifier ► Not a filename. ► Abstract reference. ► Resolved at runtime. Version, profile. Output format (HTML, PDF). Language.

15 November 2005Linking Outside the Box22 Database setup ► Define scope. ► Assign document identfiers. ► Create database framework file. ► Generate target data files for each doc.

15 November 2005Linking Outside the Box23 Database framework olinkdb.xml <!DOCTYPE targetset [ ]> &uglinks; &admin;

15 November 2005Linking Outside the Box24 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 2005Linking Outside the Box25 Target data DocBook: Definitive Guide Customizing DocBook Chapter 5, "Customizing DocBook"...

15 November 2005Linking Outside the Box26 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 2005Linking Outside the Box27 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 2005Linking Outside the Box28 Managing olinks ► Dependencies between documents! ► When update a document: Render it. Regenerate target data at same time. ► Manage releases.

15 November 2005Linking Outside the Box29 Manage destinations ► Use baseuri for each target doc. ► Prefixed to each rendered olink. <document targetdoc="ag" baseuri="file:///doc/admindoc/">...

15 November 2005Linking Outside the Box30 New DocBook capabilities ► Modular XML files. ► Asynchronous processing. ► Links to open source doc. ► Language fallback.

15 November 2005Linking Outside the Box31 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 2005Linking Outside the Box32 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 2005Linking Outside the Box33 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 2005Linking Outside the Box34 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 2005Linking Outside the Box35 In conclusion ► Olinks are easy to author. ► Olinks are maintainable. ► Customizable stylesheet processing. ► Olinking widely used in DocBook today.

15 November 2005Linking Outside the Box36 Resources ► DocBook XSL: The Complete Guide ► DocBook: The Definitive Guide ► DocBook SourceForge project: