Now covers XSL-based olink processing.

diff --git a/website/example/olink.xml b/website/example/olink.xml
index bfbea4aaa0f3872ac523c7dc9e14e00671e5b3b7..f41ce70e0118bccf40bc107eecc7aa13bd0e2466 100644 (file)
--- a/website/example/olink.xml
+++ b/website/example/olink.xml
@@ -7,67 +7,140 @@
 <titleabbrev>Linking</titleabbrev>
 <summary>Linking across Pages</summary>
 </head>
-
-<para>In Website, the website pages are different XML documents so it
-is no longer possible to use <sgmltag>link</sgmltag> to make links
+<para>In Website, the website pages are separate XML documents, so it
+is not possible to use <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag> to make links
 between them.  Instead, you must use <sgmltag>olink</sgmltag><footnote>
 <para>It's also possible to use <sgmltag>ulink</sgmltag> and make links
 directly to the generated HTML pages, but that's a bad idea; if you change
 the hierarchy or rename a page, the link will become stale. With
-<sgmltag>olink</sgmltag> this won't happen.</para></footnote>.</para>
+<sgmltag>olink</sgmltag> this won't happen.</para></footnote>.</para> 
+<para><sgmltag>Olink</sgmltag> differs from other linking elements because it requires two attributes: one to locate the document and one to locate an ID value within that document. Here is an example of an <sgmltag>olink</sgmltag>:</para> 
+<programlisting>&lt;olink targetdoc="home" targetptr="whatsnew"/&gt;</programlisting>
+<itemizedlist>
+<listitem>
+<para>The <sgmltag class="attribute">targetdoc</sgmltag> attribute identifies the document that contains the target of the link. In Website, the <sgmltag>id</sgmltag> attribute value on the <sgmltag class="element">webpage</sgmltag> element used as the document identifier since it must be unique. Its value should be used in the <sgmltag class="attribute">targetdoc</sgmltag> attribute of an <sgmltag class="element">olink</sgmltag>.</para>
+</listitem>
+<listitem>
+<para>The <sgmltag class="attribute">targetptr</sgmltag> attribute must match an <sgmltag>id</sgmltag> attribute value on an element within that document. If you want to link to the top of the page, then the <sgmltag class="attribute">targetptr</sgmltag> is the same as the <sgmltag class="attribute">targetdoc</sgmltag> value.</para>
+</listitem>
+<listitem>
+<para>If an <sgmltag class="element">olink</sgmltag> has no content, then the stylesheet generates content in a manner similar to an <sgmltag class="element">xref</sgmltag>. The content comes from a website database document that the stylesheets can create. If an <sgmltag class="element">olink</sgmltag> element has content, then that is used instead of the generated content.</para>
+</listitem>
+<listitem>
+<para>Once you enter olinks in your webpages, you need to make sure the right parameters are set to process them.</para>
+</listitem>
+</itemizedlist> 
+<section>
+<title>Olinks with XSLT build method</title>
+<para>Here is how you process a website with olinks using  the <olink targetdoc="buildmake" targetptr="buildmake">XSLT build</olink> method.</para>
+<orderedlist>
+<listitem>
+<para>Create your <filename>layout.xml</filename> file the same as before.</para>
+</listitem>
+<listitem>
+<para>Process your <filename>layout.xml</filename> file as before with the <filename>autolayout.xsl</filename> stylesheet to create the <filename>autolayout.xml</filename> file.</para>
+</listitem>
+<listitem>
+<para>Process your <filename>autolayout.xml</filename> file as before with either the <filename>chunk-tabular.xsl</filename> or <filename>chunk-website.xsl</filename> stylesheet. But set the parameter <literal>collect.xref.targets</literal> to the value <quote><literal>yes</literal></quote>. That will generate a database file named <filename>website.database.xml</filename> in the current directory, and use that to resolve olinks.</para>
+</listitem>
+</orderedlist>
+</section>
+<section>
+<title>Olinks with Make method</title>
+<para>Here is how you process a website with olinks using  the <olink targetdoc="buildmake" targetptr="buildmake">Makefile</olink>  method.</para>
+<orderedlist>
+<listitem>
+<para>Create your <filename>layout.xml</filename> file the same as before.</para>
+</listitem>
+<listitem>
+<para>Do the <literal>autolayout.xml</literal> and <literal>depends</literal> processing steps as before.</para>
+</listitem>
+<listitem>
+<para>Generate the website database file by processing your <filename>autolayout.xml</filename> file with the <filename>website-targets.xsl</filename> stylesheet, saving the output to a file named <filename>website.database.xml</filename>.</para>
+</listitem>
+<listitem>
+<para>Process your website as you would normally (usually by typing <command>make website</command>).</para>
+</listitem>
+</orderedlist>
+<para>Here is a sample <filename>Makefile</filename> using xsltproc and XML catalogs:</para>
+<programlisting>
+PROC = XML_CATALOG_FILES=../catalog.xml  xsltproc
 
-<para><sgmltag>Olink</sgmltag> is different from the other linking mechanisms
-that you may be familiar with. Instead of using a URI or an IDREF to form
-the link, it uses an XML unparsed entity. If that sounds greek, don't
-worry too much, it's easy to do.</para>
+all:
+        make website
 
-<orderedlist>
-<listitem><para>Create an entity declaration that identifies the target
-page. For example, to link to this page, I would use the following
-declaration:</para>
+include depends.tabular
+
+autolayout.xml:  layout.xml
+        $(PROC) \
+        --output  $@ \
+        autolayout.xsl  $&lt;
+
+        make depends
+
+depends:  autolayout.xml
+        $(PROC) \
+        --output depends.tabular \
+        --stringparam  output-root  htdocs  \
+        makefile-dep.xsl  $&lt;
+
+website.database.xml:  autolayout.xml
+        $(PROC) \
+        --output $@ \
+       website-targets.xsl  $&lt;
 
-<programlisting
-><![CDATA[<!ENTITY linking SYSTEM "olink.xml" NDATA XML>]]></programlisting>
+%.html: autolayout.xml 
+        $(PROC) \
+        --output $@  \
+        --stringparam  output-root  htdocs
+        tabular.xsl  \
+        $(filter-out autolayout.xml,$^)
 
+</programlisting>
+
+</section>
+<section>
+<title>Olinks with system entities</title>
+<para>The original system for olinks uses SYSTEM entities referenced by a <sgmltag class="attribute">targetdocent</sgmltag> attribute instead of a <sgmltag class="attribute">targetdoc</sgmltag> attribute. And it uses the <sgmltag class="attribute">localinfo</sgmltag> attribute instead of <sgmltag class="attribute">targetptr</sgmltag> to locate a reference point within the document. Here is how you process the original kind of olinks with Website.</para>
+<orderedlist>
+<listitem>
+<para>Create an entity declaration that identifies the target
+page. For example, to link to this page, I would use the following
+declaration:</para> 
+<programlisting><![CDATA[<!ENTITY linking SYSTEM "olink.xml" NDATA XML>]]></programlisting>
 <para>The name that you use for the entity, <literal>linking</literal>
 in this case, is irrelevant. The important thing is that the entity
 point to the right page. I've used a system identifier here, but you could
-also use public identifiers if you wanted more flexibility.</para>
-
+also use public identifiers if you wanted more flexibility.</para> 
 <para>Keep in mind that the systen identifier specified here must be
 either an absolute URI or a relative URI that will resolve to the
 target page (in other words, you may need to prefix it with a partial
-path name, if you keep your XML webpages in different directories).</para>
-</listitem>
-
-<listitem><para>Make sure the webpage that you are linking
+path name, if you keep your XML webpages in different directories).</para> 
+</listitem> 
+<listitem>
+<para>Make sure the webpage that you are linking
 <emphasis>from</emphasis> (you don't have to do anything special to
 the page you're linking to) has a <quote>DOCTYPE</quote> declaration with
 an internal subset. If your <sgmltag>olink</sgmltag> entity is the only
-thing in it, it should look like something like this:</para>
-
-<programlisting
-><![CDATA[<!DOCTYPE webpage PUBLIC "-//SF DocBook//DTD Website V2.0//EN"
+thing in it, it should look like something like this:</para> 
+<programlisting><![CDATA[<!DOCTYPE webpage PUBLIC "-//SF DocBook//DTD Website V2.0//EN"
           SYSTEM "http://www.sourceforge.net/docbook/release/website/2.0/website.dtd [
 <!ENTITY linking SYSTEM "olink.xml" NDATA XML>
 ]>]]></programlisting>
-
 <para>If you want to link to several different pages, you will need an
-entity declaration for each of them.</para>
-</listitem>
-
-<listitem><para>Use the <sgmltag class="attribute">targetdocent</sgmltag>
+entity declaration for each of them.</para> 
+</listitem> 
+<listitem>
+<para>Use the <sgmltag class="attribute">targetdocent</sgmltag>
 attribute of <sgmltag>olink</sgmltag> to identify the entity of the page
-you want to link to:</para>
-
-<programlisting
-><![CDATA[<olink targetdocent="linking">link text</olink>]]></programlisting>
-
+you want to link to:</para> 
+<programlisting><![CDATA[<olink targetdocent="linking">link text</olink>]]></programlisting>
 <para>That will link to the correct page in the resulting website. If you
 want to link to a specific anchor in that web page, use the
 <sgmltag class="attribute">localinfo</sgmltag> attribute to specify the
-XML ID.</para>
+XML ID.</para> 
 </listitem>
 </orderedlist>
+</section> 
 
 </webpage>