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
[email protected]
----- Original Message -----
From: "Steve Johnson" <[email protected]>
To: <[email protected]>
Cc: "Docbook Apps Help list" <[email protected]>
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
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
