External Document Linking Example 2

iSiloX

external document linking example 2

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 an example HTML file set to show how you might convert a given source file set into two individual documents, whereas previously, the whole file set would need to go into a single document. This facility is especially useful for the scenario where breaking a document into smaller parts makes it more manageable where storage space is limited, such that a given user could selectively choose the sub-documents that he needs rather than having to store entire document.

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
document 1: a to m
document 2: n to z
convert the documents
test the documents

the source file set

For this tutorial, we will use the 2004 edition of the The World Factbook available from the CIA website.

download the file set
To download the file set used in this example, following these steps:

Go to <http://www.cia.gov>.
In the left column, under Library & Reference, click the link labeled The World Factbook.
On The World Factbook page, click the link labeled Download This Publication.
On the Download Page, read the instructions, then under the section titled The World Factbook 2004, go to the sub-section titled II. Two-file .Zip set for high-bandwidth users: and download the file named factbooka2004.zip.
Unzip the downloaded file factbooka2004.zip. Assuming you unzip with directories, all the files in the zip file will be unzipped to a directory named factbook automatically. In this tutorial, we have unzipped to the root of the C: drive, so all the files will be in C:\factbook as shown in File Explorer here:

Note that the above steps for downloading the file set were current as of the time of this writing (July 2004) and may subsequently require updating.

file structure
In this tutorial, we will create a two-document set for the country pages listed in the file C:\factbook\countrylisting.html. Each link in the list is to a file in the print subdirectory (e.g., C:\factbook\print\) and the file name takes the form of two letters with an extension of .html. For example, the link for the United States entry is to the file us.html in the print subdirectory (e.g., C:\factbook\print\us.html).

For most of the entries, the first letter of the country name is the same as the first letter part of the file name to which it links as in the United States example just mentioned. An example for which this does not hold is the British Virgin Islands, for which the file is vi.html. There are a number of additional such exceptions as well.

file division overview
In iSiloX, the way we specify which links are external is via a simple match on the prefix of the URLs, so what we will do is place all country files that begin with any of the first 13 letters of the alphabet (e.g., A-M) in one document and country files that begin with any of the last 13 letters (e.g., N-Z) in the second document. Both documents will have the countrylisting.html file as its root source file and with a maximum link depth of one.

With the above setup, if we open any of the two documents, and go to the first page, that first page in both documents will be the country listing page. From that country listing page of either document, we can click or tap on any link and it will automatically take us to the proper country page, whether that page is in the current document or in the other document.

document 1: a to m

We are now ready to create the entry in iSiloX for converting the first document, which will contain the country files that begin with any of the letters from a to m. To do so, follow these steps:

Start iSiloX.
In the Document menu, click Add.
Enter Countries A to M as the title for the document, check Go to the document properties dialog next, then click Next.
In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the countrylisting.html file as the single root source file.
Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\factbook\ directory as the destination. If you want, you can also add other destinations.
Click the Links tab and set the Maximum link depth value to one and the remaining options as shown here:
Now click External Documents so that we can specify which links are to the other document.
In the External Documents dialog, in the External Document Specification box, do the following:
1. For the Document name field, enter Countries N to Z. This is the name we will give to the other document.
2. For the Link prefix, enter print/n. Any link that starts with print/n is considered a link to an external document.
3. Check the Keep prefix option. Named targets are relative to the first source file, so we need to keep the prefix we specified above in the link that is used to identify the target in the external document.
4. Set the Lookup by option to Name. Both documents 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:
In the Link prefix field, change the n to an o and then click Add. The list should now have two entries and look like this:
Continue adding specifications for the remaining letters up to z after which, the list should have 13 entries and look like this:
Click OK to dismiss the External Documents dialog.
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:
Click OK to accept the settings you have made to the new document properties.

document 2: n to z

We are now ready to create the entry in iSiloX for converting the second document, which will contain the country files that begin with any of the letters from n to z. To do so, follow these steps:

In the Document menu, click Add.
Enter Countries N to Z as the title for the document, check Go to the document properties dialog next, then click Next.
In the New Document Properties dialog, click the Source tab and then click Add URL/File to add the countrylisting.html file as the single root source file.
Click the Destination tab, remove any existing destinations, and then click Folder to add the C:\factbook\ directory as the destination. If you want, you can also add other destinations.
Click the Links tab and set the Maximum link depth value to one and the remaining options as shown here:
Now click External Documents so that we can specify which links are to the other document.
In the External Documents dialog, in the External Document Specification box, do the following:
1. For the Document name field, enter Countries A to M. This is the name we gave to the first document.
2. For the Link prefix, enter print/a. Any link that starts with print/a is considered a link to an external document.
3. Check the Keep prefix option. Named targets are relative to the first source file, so we need to keep the prefix we specified above in the link that is used to identify the target in the external document.
4. Set the Lookup by option to Name. Both documents 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:
In the Link prefix field, change the a to a b and then click Add. The list should now have two entries and look like this:
Continue adding specifications for the remaining letters up to m after which, the list should have 13 entries and look like this:
Click OK to dismiss the External Documents dialog.
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:
Click OK to accept the settings you have made to the new document properties. You should now have entries for both documents:

convert the documents

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

The conversion may take a couple of minutes, depending on the speed of your system.

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 two documents to the internal storage memory of our Palm OS® device.

Open the Countries A to M document. The first page is the content from the countrylisting.html source file.

Tap the letter C link to jump to the list of countries that begin with the letter C.

Tap the Canada link to jump to the page for Canada. Notice that the title bar still shows Countries A to M.

Tap the Country List link at the top of the Canada page to return to the country listing page. Then scroll down to the list of countries that begin with the letter S and tap the link for Saudi Arabia.

Notice that the title bar has changed from Countries A to M to Countries N to Z, meaning that the Saudi Arabia link in the first document was an external link to the Saudi Arabia page in the second document.

Tap the Country List link at the top of the Saudi Arabia page to return to the country listing page. Notice that the title bar still shows Countries N to Z because we also have the country listing page as the first page of the second document.

Tap the letter N link to jump to the list of countries that begin with the letter N and then tap the New Zealand link.

Notice that the title bar remains as Countries N to Z because the New Zealand page is also in the second document.

Tap the Country List link at the top of the New Zealand page to return to the country listing page. Scroll down to the list of countries that begin with the letter G and tap the Germany link.

After jumping to the Germany page, notice that the title bar has now changed to Countries A to M because the Germany page is in the first document.

Congratulations on having created two documents that link externally to one another.