<LinkOptions>

Full element example

    <LinkOptions>
      <MaximumDepth             value="1"/>
      <FollowOffsite            value="yes"/>
      <MaximumOffsiteDepth      value="1"/>
      <SubDirOnly               value="no"/>
      <UnresolvedDetail         value="include"/>
      <Exclude>
        <Pattern>RE::table[1-9].jpg</Pattern>
        <Pattern>WC::figures*plant?blue</Pattern>
      </Exclude>
      <Include>
        <Pattern>RE:C:Table8</Pattern>
      </Include>
      <ExternalDocuments>
        <Specification>
          <Path>DocumentB</Path>
          <Prefix>DocumentB</Prefix>
          <KeepPrefix             value="no"/>
          <MapFile>c:\Docs\DocumentB\DocumentB.map</MapFile>
          <Lookup                 value="ByID"/>
        </Specification>
      </ExternalDocuments>
    </LinkOptions>

Sub-element summary

Sub-element descriptions

  <MaximumDepth             value="3"/>

  <MaximumDepth             value="0"/>

  <FollowOffsite            value="yes"/>

  <FollowOffsite            value="no"/>

  <MaximumOffsiteDepth      value="2"/>

  <MaximumOffsiteDepth      value="0"/>

In many cases, websites are structured hierarchically within folders and sub-folders. And in such cases, it is also probably the case that the URLs referencing the pages of such a site are also orgznied as such, with slashes separating the different levels of folders. For example, the iSiloX.com website has all support pages within a folder named "support". Within the support folder, there are sub-folders for different categories of support, such as a sub-folder named "manual" where the manuals are located. However, such sub-folder pages may also have links to pages outside of the folder. If you want to limit followed links to only sub-folders of the root source pages then you can set the value attribute of the SubDirOnly element to the value yes. If you do, then iSiloX only follows links which match up to the last slash of any of the root source URLs.

As an example, if you wanted to get all the support pages from the iSiloX.com website, you might specify http://www.iSiloX.com/support/index.htm as the root source URL and set the value attribute of the SubDirOnly element to the value yes. The page http://www.iSiloX.com/support/index.htm has a reference to the home page of the site http://www.iSiloX.com. However, because you have set the value attribute of the SubDirOnly element to the value yes, that link will not be followed. However, a link such as http://www.iSiloX.com/support/faq.htm to the frequently asked questions page will be followed.

Examples
This example specifies that only links to targets within subdirectories should be followed.

  <SubDirOnly               value="yes"/>

  <SubDirOnly               value="no"/>

  <UnresolvedDetail         value="include"/>

  <UnresolvedDetail         value="exclude"/>

The format of a pattern string is:

  type:options:pattern

A pattern can be either a wildcard pattern or a regular expression pattern:

• wildcard: A wildcard pattern provides a simple way to specify simple patterns. In such a pattern, the character '*' matches zero or more of any mix of characters and the character '?' matches exactly one of any character. A URL matches against a wildcard pattern if the pattern appears anywhere in the URL.
• regular expression: Regular expression patterns use a powerful pattern matching language. This implementation uses the PCRE (Perl Compatible Regular Expressions) library, version 3.9. For more information about PCRE and the syntax for regular expressions, you can consult the PCRE website. In particular, follow the link there labeld "PCRE man page" and then go to the section with the heading "REGULAR EXPRESSION DETAILS".

  <Exclude>
    <Pattern>RE::table[1-9].jpg</Pattern>
    <Pattern>WC::figures*plant?blue</Pattern>
  </Exclude>

• Table1.jpg
• http://www.acme.org/table3.jpg
• c:\My Documents\table5.jpg
• /home/acme/docs/TABLE9.jpg

• Table1.gif
• http://www.acme.org/table0.jpg
• c:\My Documents\table5
• /home/acme/docs/tables.htm

• http://blueflowers.com/figures/plantablue.htm
• http://blueflowers.com/figuresplant1blue.htm

• http://blueflowers.com/figures/plantabblue.htm
• http://blueflowers.com/figuresplantblue.htm

  <Include>
    <Pattern>RE:C:Table8</Pattern>
  </Include>

  <Path>DocumentB</Path>

  <Path>../Main Index.pdb</Path>

  <Path>Classics/The Art of War</Path>

  <Path>"Gulliver's Travels" "Gulliver_s_Travels.pdb" "Gul. Travels"</Path>

  <Prefix>DocumentB</Prefix>

As an example of a scenario where the prefix should not be included in the lookup, consider two documents, call them document A and document B, that externally link to one another such that each document's content is wholly contained in its own directory. Say that the directory containing document A's content is named DirA and that the directory for document B's content is named DirB. In order for document A to link to document B, for document A, you would specify DirB as the prefix for identifying links as those to document B. For document B, you would specify DirA as the prefix for identifying links as those to document A. The target names within a given document are relative to the first source, which would presumably be some file immediately within the document's directory. Hence, the directory name would not be part of the target name and thus the prefix, which would be the same as the directory name, should not be included for lookup.

As an example of a scenario where the prefix should be included in the lookup, consider two documents, call them document A and document B, that externally link to one another such that each document's content is spread across two directories. Say that the directories containing document A's content are DirA1 and DirA2 and that the directories containing document B's content are named DirB1 and DirB2. Further, say that the directory containing all four directories is named DirAB. In addition, say that an index file immediately within DirAB links to content in all four subdirectories DirA1, DirA2, DirB1, and DirB2. To create the two documents that link externally to one another, for document A, you would specify two external document specifications, both for externally linking to document B. For the first specification, DirB1 would be the prefix. For the second specification, DirB2 would be the prefix. But since the index file is at the same level as those two directories, you would want to keep the prefix.

Examples
This example specifies that the prefix not be included for lookup.

  <KeepPrefix               value="no"/>

  <KeepPrefix               value="yes"/>

When converting the target external document, use the <Targets> element to generate the map file. If two documents link to one another, it is necessary to perform two conversion passes. The first pass generates the map file and the second pass uses the map files for looking up the associated target IDs or offsets.

Examples
This example specifies the full path of a map file on a Windows® based computer.

  <MapFile>c:\Docs\DocumentB\DocumentB.map</MapFile>

• ByName: The part of the URL of the link after the prefix is considered the target name and stored as the value to use to identify the target location within the external document when a jump to the target occurs. In order for the links to the target document to work properly, the target document must have been converted with the value attribute of the <Lookup> tag within its <Targets> element set to ByName.
• ByID: A numeric value, also known as the target ID, that uniquely identifies the target is stored and used to identify the target location within the external document when a jump to the target occurs. A map file for the external document is needed to lookup the target ID values of the external document during conversion.
• ByOffset: A numeric value, also known as the target offset, that represents the location of the target in the external document is stored and used when a jump to the target occurs. A map file for the external document is needed to lookup the target offset values of the external document during conversion.

The lookup methods each have their own individual advantages and disadvantages.

For the document storage space tradeoffs among the methods, the ByName method requires the largest amount of storage space in the linking document as well as in the targeted external document unless the number of target names are very few and short in length. The ByID and ByOffset methods require approximately the same amount of storage space as each other in the linking document. In the targeted external document, the ByOffset method requires no additional storage space, while the ByID method requires an amount of storage space that is generally less than the ByName method.

In terms of the speed of performing the lookup when a jump occurs to an external document, the difference perceived by the user is probably negligible. But the ByName method requires the most amount of processing. The ByID method comes next, while the ByOffset method requires the least amount of processing for lookup.

The other important tradeoff among the methods concerns synchronization between a document and the external documents to which it links. For the purposes of this discussion, let us say that we have a document named DocSource that has links to an external document named DocTarget and that DocTarget is updated indepedent of DocSource. The content and targets in DocTarget change periodically such that content and targets may be added and removed. Assume though that the targets to which DocSource links to in DocTarget are always there, though the specific location of the targets within the content of DocTarget may change.

Given the scenario just described, if the lookup method is ByName, even though DocTarget may undergo many changes and DocSource stays the same, the links from DocSource to DocTarget will always work.

If the lookup method is ByID this may not be the case. The IDs assigned to each target within DocTarget depend to some extent on all other external targets within DocTarget. If DocTarget gets a new target or one is removed, the target IDs for the other targets may change. As a result, the target IDs stored in DocSource for the targets in DocTarget may become invalid. However, if only the content in DocTarget changes, the target IDs will still be valid.

If the lookup method is ByOffset, then neither the content nor the targets in DocTarget may change if the links from DocSource to DocTarget are to remain valid.

The ByName lookup method, though requiring the most storage space, is the best method to use for documents that can change independent of one another. The ByOffset lookup method requires the least amount of storage space and is a good method to use for documents that will change together. The ByID lookup method generally requires only a modest amount of storage space compared to the ByName method and is a good method to use when only changes to the content, such as minor corrections, are expected to occur in an external document.

Examples
This example specifies that the target lookup be by name.

  <Lookup                   value="ByName"/>

  <Lookup                   value="ByID"/>

  <Lookup                   value="ByOffset"/>