OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] UPDATE: olink basics

Hi Steve,
Olinking is not needed for chunked HTML output.

Actually, I meant document as you use it, as an XML file.  An xref or link element 
uses a linkend attribute whose attribute type is IDREF.  The XML standard says the 
target of an IDREF has to be within the same XML file.  Olinking relaxes that 
requirement and resolves links when the document is processed for output.

The vagueness comes from the two major use cases for olinks:

1.  Modular XML files that are assembled into a larger document, where olinking is 
used to link within the larger document.  When editing an XML module that uses xref to 
link to another module, you get validation errors in your XML editor about unresolved 
IDREFs.  If you use olinks, you don't get those validation errors.

2.  Linking to other XML files not in the same document, as between separately 
published books or articles.

So olinks can be used for both internal and external links.  The stylesheet knows how 
to resolve the output syntax differently for the two cases, by detecting if the target 
of an olink appears in the current XML document (the assembled document).

But olinking is not necessary for chunking an XML document into multiple HTML files. 
Once a document is assembled to be processed, the stylesheet can chunk the output and 
will automatically form proper links between chunks for xref and link elements.

I tend to think of an assembled document as the hub of any modularity features.  On 
the input side, an XML document can be assembled from any combination of modular XML 
documents using XInclude.  On the output side, an XML document can be processed into 
many output chunks.  The input modules and the output chunks have no relationship to 
each other.  That is, your input modules can be at the section level and output chunks 
at the chapter level, or any other combination. Essentially the modularity of the 
input is erased when assembled into a complete XML document for processing, and that 
assembled document can be chunked any number of ways in the output.

Bob Stayton
Sagehill Enterprises

----- Original Message ----- 
From: "Steve Johnson" <stevej@caringo.com>
To: <stevej@caringo.com>
Cc: "Docbook Apps Help list" <docbook-apps@lists.oasis-open.org>
Sent: Tuesday, July 06, 2010 10:14 AM
Subject: [docbook-apps] UPDATE: olink basics

> The more basic question is, should <olink> be used in this case at all?
> The description of olink is: "The olink element is the equivalent for linking 
> outside the current document." (from Bob Stayton's book)
> I think this is an extremely vague way to describe it because "document" is 
> ambiguous and the author uses that term consistently throughout his book. To me, an 
> XML file is a *document* but apparently what the author intends to say is "book" or, 
> more verbosely, "...outside the document after it has been transformed."
> How about if the same book is chunked? Will I then have to replace my <xref>s with 
> <olink>s?
> On 7/5/2010 1:59 PM, Steve Johnson wrote:
>> Currently we are not "chunking" documentation but at some point I would
>> like to be able to do that. To that end, because currently there are no
>> cross-references at all, I want to implement cross-references so they
>> will work whether or not the documents are "chunked" at transformation.
>> I had no luck with <olink> because when I did the transform I always got
>> a failure to resolve the olinks.
>> To start with I wanted to olink between two chapters in a book. I added
>> an xml:id to each <chapter> tag and, because all chapter files are in
>> the same directory, used the following as the olink.db:
>> <?xml version="1.0" encoding="UTF-8"?>
>> <!DOCTYPE targetset
>> SYSTEM "targetdatabase.dtd" [
>> <!ENTITY SDKOverview SYSTEM "SDKOverview.db">
>> ]>
>> <targetset>
>> <document targetdoc="SDKIntroduction"
>> baseuri="CAStorSDKOverview.html">
>> </document>
>> <document targetdoc="SDKEnumeration">
>> </document>
>> </targetset>
>> Question: Does the name of "baseuri" have to correspond to anything?
>> Should it correspond to the name of the chapter (SDKIntroduction) or to
>> the book (CAStorSDKOverview)?
>> Link: <olink targetdoc="SDKEnumeration" targetptr="StartMethod"/>
>> Transform command line:
>> xsltproc --output c:\<filename> /
>> --stringparam collect.xref.targets "yes" /
>> --stringparam target.database.document "olinkdb.xml" /
>> --stringparam current.docid "CAStorSDKOverview" /
>> --xinclude C:\<our-custom-xsl> C:\<book-file>
>> Result:
>> Writing target.db for book(CAStorSDKOverview)
>> Error: unresolved olink: targetdoc/targetptr =
>> 'SDKEnumeration/StartMethod'.
> -- 
> ------------
> Steve Johnson, Senior Content Developer
> Caringo
> stevej@caringo.com
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]