Description of new olinking prototype.

diff --git a/contrib/xsl-custom/newolink/README b/contrib/xsl-custom/newolink/README
new file mode 100644 (file)
index 0000000..d7c2b0e
--- /dev/null
+++ b/contrib/xsl-custom/newolink/README
@@ -0,0 +1,120 @@
+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
+