From b66cc0b226ed9303d26050179518dd8506973741 Mon Sep 17 00:00:00 2001 From: Bob Stayton Date: Fri, 5 Oct 2001 08:58:21 +0000 Subject: [PATCH] Description of new olinking prototype. --- contrib/xsl-custom/newolink/README | 120 +++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 contrib/xsl-custom/newolink/README diff --git a/contrib/xsl-custom/newolink/README b/contrib/xsl-custom/newolink/README new file mode 100644 index 000000000..d7c2b0eea --- /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 element identified by the 'targetdoc' +attribute in the olink, finds that '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 '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 + -- 2.40.0