 |
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 method
Here is how you process a website with olinks
using the 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 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 entities
The 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.
|
