# Linking Pages

Linking
Linking across 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` It's also possible to use `ulink` 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 `olink` this won't happen..

`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 XSLT build method.

1. Create your `layout.xml` file the same as before.

2. Process your `layout.xml` file as before with the `autolayout.xsl` stylesheet to create the `autolayout.xml` file.

3. 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.

# Olinks with Make method

Here is how you process a website with olinks using the Makefile method.

1. Create your `layout.xml` file the same as before.

2. Do the `autolayout.xml` and `depends` processing steps as before.

3. 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`.

4. 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.

1. 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).

2. 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.

3. 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.