+++ /dev/null
-New olink prototype README
----------------------------------
-Version 1.0
-4 October 2001
-
-The file archive olinktest.tar.gz contains
-a prototype implementation
-of a new way to use olink for creating cross references
-between DocBook documents using Norm Walsh's XSL
-stylesheets. The new olink scheme is described in
-http://www.sagehill.net/OlinkExtended.html.
-
-The archive have four directories under olinktest/:
-
-tools - contains the stylesheet customization layers
- and DTDs.
-
-docsrc - the XML documents to be linked and processed.
-
-docroot - the output location for the HTML (initially empty)
-
-archive - results of my build, for comparison.
-
-
-This prototype sets up two documents with olink
-cross references to each other. The two documents
-in docsrc are 'userguide.xml' and 'ref.xml'.
-The Makefile uses xsltproc to generate the cross
-reference database and then process the documents
-to produce HTML with the links resolved.
-
-To run the prototype:
-
-1. Install xsltproc, or you will have to change
-the processing commands in the Makefile.
-
-2. Edit these files in tools to correct the pathnames to
-the DocBook 1.44 stylesheets on your system:
- custom.xsl
- targets.xsl
- chunkcustom.xsl
- chunkedtargets.xsl
-
-3. Edit tools/newolink.dtd to correct the path location
-to the DocBook XML 4.1.2 DTD.
-
-4. cd to docsrc and run the Makefile:
- make all
-
-This should result in a collection of
-HTML files under two directories
-under 'docroot'. Under 'archive' you'll find the results
-of my build to compare to.
-
-The Makefile first generates the files ugtargets.xml
-and reftargets.xml, which contain the cross reference
-target information for the respective documents.
-It uses the targets.xsl customization layer on
-userguide.xml (non-chunked document), and it uses
-chunkedtargets.xsl on ref.xml (which will be chunked).
-
-The individual document target files
-are referenced by the master targetdb.xml
-document. It uses a simple 'href' attribute to
-point to each individual datafile.
-
-The Makefile then processes each document again for HTML output.
-It uses custom.xsl for userguide.xml, and
-customchunked.xsl for ref.xml (chunked output).
-Each is passed the name of the master database file
-'targetdb.xml' as a parameter.
-
-Both stylesheets include newolink.xsl, which redefines
-the behavior of olink if it uses a type="stylesheet"
-attribute. The template first uses the document() function to
-open the master database file. Then it
-finds the <document> element identified by the 'targetdoc'
-attribute in the olink, finds that <document>'s
-href attribute, and uses the document() function again to open
-the individual data file. Using the specific data file,
-it looks up the targetid of the olink, and gets the
-necessary data to resolve the link.
-
-The href is prefixed with the <document>'s
-baseuri attribute value in targetdb.xml (something you
-have to set if you add another document).
-That permits cross referencing between documents
-that land in different directories.
-
-Since the sample olinks are empty, the hot text
-is generated from the target data set. It also
-adds 'in Blah Blah' to indicate that this link
-is to another document.
-
-The prototype has only three olinks, so you will have
-to look for them in the source and the output.
-
-It may seem inefficient to keep opening the same data files
-for each olink, but in fact it isn't. XSL processors
-keep an opened document open in memory, and each new
-opening of the same uri returns the already opened
-node set. By only opening the datasets that are
-called for by olinks, you can avoid having to read
-an entire large collection of target data. Also,
-each individual data file can be updated separately
-when its document is edited. This modular setup
-works well with make files.
-
-If anyone tries this out, I'd be happy to respond
-to questions or comments. Remember, it is just
-a first prototype. I plan to clean it up
-and write more doc for it.
-
-bobs
-Bob Stayton 400 Encinal Street
-Publications Architect Santa Cruz, CA 95060
-Technical Publications voice: (831) 427-7796
-Caldera International, Inc. fax: (831) 429-1887
- email: bobs@caldera.com
-