Linking Pages
In Website, the website pages are separate XML documents, so it
is not possible to use xref or link to make links
between them. Instead, you must use olink[1].
Olink 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 olink:
<olink targetdoc="home" targetptr="whatsnew"/>
-
The targetdoc attribute identifies the document that contains the target of the link. In Website, the id attribute value on the webpage element used as the document identifier since it must be unique. Its value should be used in the targetdoc attribute of an olink.
-
The targetptr attribute must match an id attribute value on an element within that document. If you want to link to the top of the page, then the targetptr is the same as the targetdoc value.
-
If an olink has no content, then the stylesheet generates content in a manner similar to an xref. The content comes from a website database document that the stylesheets can create. If an olink element has content, then that is used instead of the generated content.
-
Once you enter olinks in your webpages, you need to make sure the right parameters are set to process them.
Olinks with XSLT build methodHere is how you process a website with olinks using the XSLT build method.
-
Create your layout.xml file the same as before.
-
Process your layout.xml file as before with the autolayout.xsl stylesheet to create the autolayout.xml file.
-
Process your autolayout.xml file as before with either the chunk-tabular.xsl or chunk-website.xsl stylesheet. But set the parameter collect.xref.targets to the value “yes”. That will generate a database file named website.database.xml in the current directory, and use that to resolve olinks.
Here is how you process a website with olinks using the Makefile method.
-
Create your layout.xml file the same as before.
-
Do the autolayout.xml and depends processing steps as before.
-
Generate the website database file by processing your autolayout.xml file with the website-targets.xsl stylesheet, saving the output to a file named website.database.xml.
-
Process your website as you would normally (usually by typing make website).
Here is a sample Makefile using xsltproc and XML catalogs:
PROC = XML_CATALOG_FILES=../catalog.xml xsltproc
all:
make website
include depends.tabular
autolayout.xml: layout.xml
$(PROC) \
--output $@ \
autolayout.xsl $<
make depends
depends: autolayout.xml
$(PROC) \
--output depends.tabular \
--stringparam output-root htdocs \
makefile-dep.xsl $<
website.database.xml: autolayout.xml
$(PROC) \
--output $@ \
website-targets.xsl $<
%.html: autolayout.xml
$(PROC) \
--output $@ \
--stringparam output-root htdocs
tabular.xsl \
$(filter-out autolayout.xml,$^)
Olinks with system entitiesThe original system for olinks uses SYSTEM entities referenced by a targetdocent attribute instead of a targetdoc attribute. And it uses the localinfo attribute instead of targetptr to locate a reference point within the document. Here is how you process the original kind of olinks with Website.
-
Create an entity declaration that identifies the target
page. For example, to link to this page, I would use the following
declaration:
<!ENTITY linking SYSTEM "olink.xml" NDATA XML>
The name that you use for the entity, linking
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.
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).
-
Make sure the webpage that you are linking
from (you don't have to do anything special to
the page you're linking to) has a “DOCTYPE” declaration with
an internal subset. If your olink entity is the only
thing in it, it should look like something like this:
<!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>
]>
If you want to link to several different pages, you will need an
entity declaration for each of them.
-
Use the targetdocent
attribute of olink to identify the entity of the page
you want to link to:
<olink targetdocent="linking">link text</olink>
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
localinfo attribute to specify the
XML ID.
|
