iSiloX Logo iSiloX
home | support
external document linking example 1

External document linking support is a new feature of iSiloX version 4.1 and iSilo™ version 4.1. Previously, links within a document could only link to pages within the same document. With external document linking as of version 4.1, links within a document can link to locations in another document. A given document can link to any number of other documents.

This tutorial uses a simple contrived example set of files to simplify understanding of the concepts.

To follow this tutorial, you should have a basic understanding of how to use iSiloX and also a basic understand of how hyperlinks are specified within HTML files.

the source file set

file set structure
For this tutorial, we will use a set of files with the following structure, where names in brackets denote directories:

You can download a zip file containing the entire directory structure and set of files by clicking ExtDocABC.zip. In this tutorial, we assume that the entire directory structure and files are in the C:\ExtDoc\ directory.

source file contents
The content of the files is relatively simple and the table below lists each file's contents. The DocumentA/index.htm file has links to all the other files so if you view that file, you can jump to any of the other files.

File Contents
DocumentA/index.htm 
<html>
<head>
<title>Document A</title>
</head>
<body>
<h1>Document A</h1>
<ul>
<li><a href="../DocumentB/index.htm">Document B</a>
<ul>
<li><a href="../DocumentB/index.htm#TOC">Table of contents</a>
<li><a href="../DocumentB/pages/Page1.htm">Page 1</a>
<li><a href="../DocumentB/pages/Page2.htm">Page 2</a>
<li><a href="../DocumentB/appendix.htm">Appendix</a>
</ul>
<li><a href="../DocumentC/index.htm">Document C</a>
<li><a href="SubDoc/index.htm">Sub-Document</a>
</ul>
</body>
</html>
DocumentA/SubDoc/index.htm 
<html>
<head>
<title>Sub-Document</title>
</head>
<body>
<h1>Sub-Document</h1>
This document should be placed in a directory named SubDoc relative
to the directory containing <a href="../../DocumentA/index.htm">Document A</a>.
</body>
</html>
DocumentB/index.htm 
<html>
<head>
<title>Document B</title>
</head>
<body>
<h1>Document B</h1>
<a name="TOC">
<h3>Table of contents</h3>
<ul>
<li><a href="pages/Page1.htm">Page 1</a>
<li><a href="pages/Page2.htm">Page 2</a>
<li><a href="appendix.htm">Appendix</a>
</ul>
Back to <a href="../DocumentA/index.htm">Document A</a>
</body>
</html>
DocumentB/appendix.htm 
<html>
<head>
<title>Document B: Appendix</title>
</head>
<body>
<h1>Document B: Appendix</h1>
</body>
</html>
DocumentB/pages/Page1.htm 
<html>
<head>
<title>Document B: Page 1</title>
</head>
<body>
<h1>Document B: Page 1</h1>
</body>
</html>
DocumentB/pages/Page2.htm 
<html>
<head>
<title>Document B: Page 2</title>
</head>
<body>
<h1>Document B: Page 2</h1>
</body>
</html>
DocumentC/index.htm 
<html>
<head>
<title>Document C</title>
</head>
<body>
<h1>Document C</h1>
</body>
</html>

file division overview
From the above file set, we will create four documents.

  1. DocumentA: This document will be converted from the single source file DocumentA/index.htm and will have external document links to the other three documents. Notice that the DocumentA/index.htm file has both links to individual pages of the other documents as well as a link to the #TOC fragment in the DocumentB/index.htm file.
  2. SubDoc: This document will be converted from the single source file DocumentA/SubDoc/index.htm and will be used specifically to demonstrate how we can have an external document link to a document that is in a different directory.
  3. DocumentB: This document will contain all the pages from the DocumentB directory.
  4. DocumentC: This document will contain the single source file in the DocumentC directory.
In iSiloX, the way we specify which links are external is via a simple match on the prefix of the URLs, so when creating a set of source files for conversion into multiple documents that can link externally to one another, you should create a directory for each document and place each document's source files in its own directory. By doing so, you make your source files compatible with conversion to an iSilo™ document as well as for viewing with a browser.
document A

We are now ready to create the entry in iSiloX for converting the documents, starting with Document A. Follow these steps:
  1. Start iSiloX.
  2. In the Document menu, click Add.
  3. Enter Document A as the title for the document, check Go to the document properties dialog next, then click Next.

  4. In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the DocumentA/index.htm file as the single root source file.

  5. Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\ExtDoc\ directory as the destination. If you want, you can also add other destinations.

  6. Click the Links tab. The options shown immediately here do not matter really for this document since there is only one source file. However, we do need to add external document specifications for the links to the other documents, so click External Documents.

  7. In the External Documents dialog, in the External Document Specification box, do the following:
    1. For the Document name field, enter Document B. This is the name we will give to the document we will create from the files in the DocumentB directory.
    2. For the Link prefix, enter DocumentB. Any link that starts with DocumentB will be considered a link to the external document named Document B.
    3. Leave the Keep prefix option unchecked. Named targets are relative to the first source file, so since every file in Document B will be relative to the index.htm file in the DocumentB directory, we don't want the directory name to be included in the link name.
    4. Set the Lookup by option to Name. All documents in this example will export their targets by name (e.g., relative URL), so the linking document must include the names (e.g., URLs).
    5. Click Add. This adds the specification to the list.
    After following the above steps, the dialog should look like this:

  8. In both the Document name field and the Link prefix field, change the B to a C and then click Add. This adds the external document specification for Document C. The list should now have two entries and look like this:

  9. Next we add the external document specification for the document that we will place in a sub-directory to show that a document can link to an external document that is in a different directory. Do the following:
    1. For the Document name field, enter SubDoc/Sub-Document. After conversion, we will place the document named "Sub-Document" in a sub-directory named "SubDoc" relative to where Document A is.
    2. For the Link prefix, enter SubDoc. Any link that starts with SubDoc will be considered a link to the external document "SubDoc/Sub-Document".
    3. Leave the Keep prefix option unchecked.
    4. Set the Lookup by option to Name.
    5. Click Add. This adds the specification to the list.
    After following the above steps, the dialog should look like this:

  10. Click OK to dismiss the External Documents dialog.
  11. Back in the New Document Properties dialog, click the Targets tab and do the following:
    1. In the Export box, select the option All targets. This makes all pages and all targets on all pages (e.g., specified with <a name=...>) linkable from other documents.
    2. In the Target lookup box, select Name for the Lookup by option. Since the external document links in our document set will specify the name of the target, we need to have the target document identify its targets by name.
    After doing the above, the dialog should look like this:

  12. Click OK to accept the settings you have made to the new document properties.

document B

Document B has only a single link back to Document A. Follow these steps to create the conversion entry for Document B:
  1. In the Document menu, click Add.
  2. Enter Document B as the title for the document, check Go to the document properties dialog next, then click Next.

  3. In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the DocumentB/index.htm file as the single root source file.

  4. Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\ExtDoc\ directory as the destination. If you want, you can also add other destinations.

  5. Click the Links tab and set the Maximum link depth value to one and the remaining options as shown here:

  6. Click External Documents to go to the the External Documents dialog. In the External Document Specification box, do the following:
    1. For the Document name field, enter Document A.
    2. For the Link prefix, enter DocumentA. Any link that starts with DocumentA will be considered a link to the external document named Document A.
    3. Leave the Keep prefix option unchecked. Named targets are relative to the first source file, so since every file in Document A will be relative to the index.htm file in the DocumentA directory, we don't want the directory name to be included in the link name.
    4. Set the Lookup by option to Name. All documents in this example will export their targets by name (e.g., relative URL), so the linking document must include the names (e.g., URLs).
    5. Click Add. This adds the specification to the list.
    After following the above steps, the dialog should look like this:

  7. Click OK to dismiss the External Documents dialog.
  8. Back in the New Document Properties dialog, click the Targets tab and do the following:
    1. In the Export box, select the option All targets. This makes all pages and all targets on all pages (e.g., specified with <a name=...>) linkable from other documents.
    2. In the Target lookup box, select Name for the Lookup by option. Since the external document links in our document set will specify the name of the target, we need to have the target document identify its targets by name.
    After doing the above, the dialog should look like this:

  9. Click OK to accept the settings you have made to the new document properties.

document C

Document C has no links to any of the other documents, so the conversion entry for Document B is a little simpler in that we do not need to add any external document specifications. We only need to have the document export its target names so that other documents can link to it. Follow these steps to create the conversion entry for Document C:
  1. In the Document menu, click Add.
  2. Enter Document C as the title for the document, check Go to the document properties dialog next, then click Next.

  3. In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the DocumentC/index.htm file as the single root source file.

  4. Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\ExtDoc\ directory as the destination. If you want, you can also add other destinations.

  5. Click the Targets tab and do the following:
    1. In the Export box, select the option All targets. This makes all pages and all targets on all pages (e.g., specified with <a name=...>) linkable from other documents.
    2. In the Target lookup box, select Name for the Lookup by option. Since the external document links in our document set will specify the name of the target, we need to have the target document identify its targets by name.
    After doing the above, the dialog should look like this:

  6. Click OK to accept the settings you have made to the new document properties.

sub-document

Just like Document B, the index.htm file in the SubDoc sub-directory of the DocumentA directory has only a single link back to Document A. We create this document specifically to demonstrate how a document can link externally to another document that will be in a different directory. Follow these steps to create the conversion entry for this document:
  1. In the Document menu, click Add.
  2. Enter Sub-Document as the title for the document, check Go to the document properties dialog next, then click Next.

  3. In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the DocumentA/SubDoc/index.htm file as the single root source file.

  4. Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\ExtDoc\ directory as the destination. If you want, you can also add other destinations.

  5. Click the Links tab. The options shown immediately here do not matter really for this document since there is only one source file. However, we do need to add the external document specifications to handle the link that goes back to DocumentA, so click External Documents.

  6. In the External Documents dialog, in the External Document Specification box, do the following:
    1. For the Document name field, enter ../Document A.
    2. For the Link prefix, enter DocumentA. Any link that starts with DocumentA will be considered a link to the external document named Document A that is in the directory above where the Sub-Document document will be.
    3. Leave the Keep prefix option unchecked. Named targets are relative to the first source file, so since every file in Document A will be relative to the index.htm file in the DocumentA directory, we don't want the directory name to be included in the link name.
    4. Set the Lookup by option to Name. All documents in this example will export their targets by name (e.g., relative URL), so the linking document must include the names (e.g., URLs).
    5. Click Add. This adds the specification to the list.
    After following the above steps, the dialog should look like this:

  7. Click OK to dismiss the External Documents dialog.
  8. Back in the New Document Properties dialog, click the Targets tab and do the following:
    1. In the Export box, select the option All targets. This makes all pages and all targets on all pages (e.g., specified with <a name=...>) linkable from other documents.
    2. In the Target lookup box, select Name for the Lookup by option. Since the external document links in our document set will specify the name of the target, we need to have the target document identify its targets by name.
    After doing the above, the dialog should look like this:

  9. Click OK to accept the settings you have made to the new document properties.

convert the documents

Select all four entries you just created and then click the Convert button or go to the Document menu and click Convert.

The conversion will be very quick since there are few files and the files are small.

After conversion is done, the Status column should indicate "Successful conversion".

test the documents

You can open the documents in iSilo™ version 4.1 or later on any supported platform to test the documents. The screenshots in this tutorial are from iSilo™ version 4.1 for Palm OS®.

We have installed the documents to a directory named ExtDoc on a storage card. We placed the files for Document A, Document B, and Document C directly within this directory and created a sub-directory named SubDoc where we placed the file for the Sub-Document document.

The structure of the files and directories should look like this, where the brackets indicate a directory:

The following screenshot shows iSilo™'s document list view after we have navigated to the ExtDoc directory where we placed the files on the storage card.

Tap Document A to open it. All the links in this document are external links to locations in the other documents.

Tap the Document B link. This opens up Document B, as you can see in the title bar, which has changed from showing "Document A" to showing "Document B".

Tap the Document A link at the bottom to return to Document A. Notice that the title bar has changed from showing "Document B" back to showing "Document A".

Now tap the Table of contents link, which takes us to the location of the table of contents section of Document B. Notice again that the title bar has changed from showing "Document A" to showing "Document B".

Tap the Appendix link to jump to the appendix page within Document B. Notice that the title bar still shows "Document B".

Tap the Back button two times to go back to Document A. Back in Document A, tap the Page 2 link to jump to Page 2 of Document B.

Tap the Back button once to go back to Document A. Then in Document A, tap the Document C link to go to Document C. Notice the title bar now shows "Document C".

Tap the Back button once to go back to Document A. Then tap the Sub-Document link, which takes us to the Sub-Document document whose file is in the SubDoc directory of the storage card.

Congratulations on having created a set of four documents that utilize external document linking.
©1999-2017 DC & Co. All rights reserved.