ixl(5)

NAME
.ixl - file format for iSiloXC(1)

DESCRIPTION
.ixl is the file extension convention for a conversion list file. A conversion list file is a file in XML format that holds document conversion specifications for .ixl. XML provides a human-readable conventional file format for structured data that can be easily edited with a simple text editor. For more about XML, visit the W3C (http://www.w3c.org/).

Top-level structure
The first line of the file should specify that the file contains XML:

    <?xml version="1.0"?>

Next, should be the document list element that contains the document specifications. The document list element begins with the following tag:

    <iSiloXDocumentList>

Within the document list element should be one or more document elements. A document element specifies how to create a document and begins with the following tag:

      <iSiloXDocument>

Each document element generally consists of several container elements that specify the information needed in order to create the document, such as the URLs and file paths of the source content and settings for options.

Full document list element example
This example is a list with one document that shows all of the possible elements explicitly specified.

XML conventions used
The following explanation of conventions should help you in understanding the .ixl file format.

  Data types
The .ixl file uses the following three general types of data:

value
    When a field takes a numeric value or a string from a limited set, then the tag uses an attribute named value to specify that value. An example of a field that takes a numeric value is the MaximumWidth element:

          <MaximumWidth             value="144"/>

    An example of a field that takes a string from a limited set is the FollowOffsite element. This element takes a value string that is equal to either yes or no :

          <FollowOffsite            value="yes"/>

    Note that all such elements are of the following form:

          <tag                      value="value"/>

    In the above, tag is the name of the element's tag, and value is the value to assign to the element. Note that a slash (e.g., '/') terminates the element since the element has no content.

string
    When a field takes an arbitrary string value, the string value is enclosed as content within the element between the start tag and the end tag of the element. An example is the Title element:

          <Title>My Document</Title>

    Note that that all such elements are of the following form:

          <tag>content</tag>

    In the above, tag is the name of the element's tag, and content is the string value.

multi-string
    When a field takes an arbitrary number of strings, the strings are enclosed as content within sub-elements of the containing element for the field. An example is the Sources element, which specifies the source URLs and file paths of the content comprising the document:

          <Sources>
            <Path>http://www.iSilo.com</Path>
            <Path>http://www.iSiloX.com</Path>
          </Sources>

    Note that that all such elements are of the following form:

          <tag>
            <subTag>content</subTag>
            <subTag>content</subTag>
            ...
            <subTag>content</subTag>
          </tag>

    In the above, tag is the name of the element's tag, subTag is the name of the tag for the sub-elements, and content is the string value for a sub-element.

  Default values
Most elements have default values. If you create a .ixl file, you do not have to explicitly specify values for every single possible element because the default value will be used in those cases. In the detailed element descriptions, the default value is provided for reference. For example, in the LinkOptions container element, if you do not provide a MaximumDepth element, it defaults to one.

Document sub-element summary
This table summarizes the option groups within the document element. Click on the tag of an option group to see details about the elements in the corresponding group.

<Source>
    Specifies the URLs and file paths of the source content used to create the document. In addition, the Source element specifies the user name and password for accessing web sites that utilize the HTTP Basic Authentication mechanism.

<Destination>
    Specifies the document title, HotSyncR destinations, and file destinations for the converted document.

<LinkOptions>
    Specifies options for handling hyperlinks.

<ImageOptions>
    Specifies options for handling images.

<TableOptions>
    Specifies options for handling tables.

<ColorOptions>
    Specifies options for handling background and text color.

<MarginOptions>
    Specifies options for handling margins.

<SecurityOptions>
    Specifies settings for securing the content of a document. .ixl add indicators to the converted document so that conforming applications that utilize the document can determine what types of actions to allow on the document.

<TextOptions>
    Specifies settings that apply to the conversion of plain text files. Examples of plain text files include files with the extension .txt and Palm Doc files.

<DocumentOptions>
    Miscellaneous options for the document.

<Bookmarks>
    Specifies settings for adding predefined bookmarks to a document.

<LastConversion>
    Stores information about the last conversion.

Multiple document element example
This example is a list with two document elements. Notice that most elements are missing. Missing elements take default values. This simplifies manual creation of a conversion list.

    <?xml version="1.0"?>
    <iSiloXDocumentList>
      <iSiloXDocument>
        <Source>
          <Sources>
            <Path>http://www.iSilo.com</Path>
          </Sources>
        </Source>
        <Destination>
          <Title>iSilo Website</Title>
          <HotSync>
            <Path>John Doe</Path>
          </HotSync>
        </Destination>
      </iSiloXDocument>
      <iSiloXDocument>
        <Source>
          <Sources>
            <Path>/home/john/Pictures/birthday.jpg</Path>
            <Path>http://www.johndoe.com/hiking.gif</Path>
          </Sources>
        </Source>
        <Destination>
          <Title>Personal Pictures</Title>
          <Files>
            <Path>/home/john/Pictures.pdb</Path>
          </Files>
        </Destination>
        <ImageOptions>
          <ResizeLargeImages        value="no"/>
        </ImageOptions>
        <SecurityOptions>
          <CopyBeam                 value="disallow"/>
        </SecurityOptions>
      </iSiloXDocument>
    </iSiloXDocumentList>

<Source> ELEMENT
The Source element specifies the URLs and file paths of the source content used to create the document. In addition, the Source element specifies the user name and password for accessing web sites that utilize the HTTP Basic Authentication mechanism.

  Full element example

        <Source>
          <Sources>
            <Path>http://www.iSilo.com</Path>
            <Path>http://www.iSiloX.com</Path>
          </Sources>
          <UserName>Joe</UserName>
          <Password>Joe's Password</Password>
        </Source>

  Sub-element summary
Tag | Type | Default | Description
<Sources> | multi-string | n/a | Source URLs and file paths
<UserName> | string | n/a | Authentication user name
<Password> | string | n/a | Authentication password

  Sub-element descriptions

<Sources>

    Description
    Within the <Sources> start tag and the </Sources> end tag, specify one or more Path elements. Each Path element consists of the source URL or file path string enclosed within the <Path> start tag and the </Path> end tag.

    Examples
    This example specifies the iSilo.com web site as the source content.

          <Sources>
            <Path>http://www.iSilo.com</Path>
          </Sources>

<UserName>

    Description
    If the source web site requires a user name and password, use this tag to specify the user name. Note that iSiloXC(1) only support the HTTP Basic Authentication mechanism. You can usually tell that a web site uses this mechanism if when you access the site, your browser pops up a dialog asking for your user name and password. You can usually tell that a web site does not use this mechanism if when you access the site, you get a page with a form for you to enter your user name and password.

    Examples
    This example specifies that the user name for authentication is Joe.

          <UserName>Joe</UserName>

<Password>

    Description
    If the source web site requires a user name and password, use this tag to specify the password.

    Also see the notes for the <UserName> tag.

    Examples
    This example specifies that the password for authentication is appleTree12.

          <Password>appleTree12</Password>

<Destination> ELEMENT
The Destination element specifies the document title, HotSyncR destinations, and file destinations for the converted document.

  Full element example

        <Destination>
          <Title>My Document</Title>
          <HotSync>
            <Path>John Doe</Path>
            <Path>Jane Doe:</Path>
          </HotSync>
          <Files>
            <Path>/home/john/documents/my_document.pdb</Path>
            <Path>/home/john/backup/my_document.pdb</Path>
          </Files>
        </Destination>

  Sub-element summary
Tag | Type | Default | Description
<Title> | string | n/a | Document title
<Files> | multi-string | n/a | File destinations

  Sub-element descriptions

<Title>

    Description
    The Title element is mandatory. Its content is a string up to 31 characters in length. The title is also used for constructing the default file name of the destination document.

    Examples
    This example specifies the title for the document to be "Short Stories of Yore".

          <Title>Short Stories of Yore</Title>

<Files>

    Description
    Use the Files element to specify one or more file destinations. A file destination results in the converted document being written to a file. If you do not want the converted document written to a file then do not specify the Files element.

    Within the <Files> start tag and the </Files> end tag, specify one or more Path elements. Each Path element consists of the path to a destination file or directory/folder enclosed within the <Path> start tag and the </Path> end tag.

    To specify a destination directory or folder, end the path string with the path separation character. The file name will be composed of the title as given by the <Title> tag and the extension .pdb.

    Examples
    This example results in the converted document being written to the ~/Docs folder under the file name news.pdb.

          <Files>
            <Path>~/Docs/news.pdb</Path>
          </Files>

    This example results in the converted document being written to the ~/Stories folder. Notice that the path to the folder below ends with a slash. If the title was specified as Horror, then the resulting file name would be Horror.pdb.

          <Files>
            <Path>~/Stories/</Path>
          </Files>

<LinkOptions> ELEMENT
The LinkOptions element specifies options for handling hyperlinks.

  Full element example

        <LinkOptions>
          <MaximumDepth             value="1"/>
          <SubDirOnly               value="no"/>
          <FollowOffsite            value="yes"/>
          <UnresolvedDetail         value="include"/>
        </LinkOptions>

  Sub-element summary
Tag | Type | Default | Description
<MaximumDepth> | value | 1 | Maximum link depth to follow
<SubDirOnly> | value | no | Whether to limit followed links to subdirectories.
<FollowOffsite> | value | yes | Whether to follow offsite links
<UnresolvedDetail> | value | include | Whether to include unresolved URLs

  Sub-element descriptions

<MaximumDepth>

    Description
    Provide a positive integer in the value attribute of the MaximumDepth element to specify how far to follow hyperlinks. If you do not specify the MaximumDepth element, it defaults to one. The root source files are considered to be at a depth of zero. Files to which they link are at a depth of one. Files to which those files link are at a depth of two, and so on.

    If you are creating a document based on a Web site, you are recommended to use a maximum depth value of one because each additional increment in depth beyond one will likely cause an exponential increase in the size of the document. For example, at a link depth of one, if the converted document is one megabyte in size, at a link depth of two, it might be ten megabytes, and at a link depth of three, it could be 100 megabytes.

    Examples
    This example specifies a maximum depth value of three, which results in all content up to a link depth of three being included in the converted document.

          <MaximumDepth             value="3"/>

    This example specifies a maximum depth value of zero, which results in no additional content other than the root source file content being included in the converted document.

          <MaximumDepth             value="0"/>

<SubDirOnly>

    Description
    In the value attribute of the SubDirOnly element, specify the value yes to limit followed links to those matching the subdirectory of the root source path. Specify the value no to allow all links to be followed.

    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 iSiloXC(1) 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"/>

    This example specifies that even links to targets outside of the root subdirectories can be followed.

          <SubDirOnly               value="no"/>

<FollowOffsite>

    Description
    In the value attribute of the FollowOffsite element, specify the value yes to follow off-site links or provide the value no to not follow off-site links.

    An off-site link is defined as a link to a target in a different domain. iSiloXC(1) treat all file paths as belonging to the same domain. For URLs, they treat the the protocol (e.g., http://) and the hostname as comprising the domain. To tell iSiloXC(1) to not follow links to targets in different domains, set the value attribute of the FollowOffsite element to no. This is useful to limit the amount of irrelevant content brought into the document.

    iSiloXC(1) perform the off-site link check anew for each root source file. What this means is that you can have root source files in different domains. For example, you can have two root source files, one with the URL <http://www.iSilo.com> and another with the URL <http://www.palm.com>. Assuming that you have set the value attribute of the FollowOffsite element to no, then when iSiloXC(1) convert the content at <http://www.iSilo.com>, only links from there with target URLs that begin with <http://www.iSilo.com> are followed. When either converts the content at <http://www.palm.com>, only links from there with target URLs that begin with <http://www.palm.com> are followed. If the content at <http://www.palm.com> had a link to <http://www.iSilo.com/whatsnew.htm>, the link will not be followed.

    Examples
    This example specifies that off-site links should be followed.

          <FollowOffsite            value="yes"/>

    This example specifies that off-site links should not be followed.

          <FollowOffsite            value="no"/>

<UnresolvedDetail>

    Description
    In most cases, since you can tell iSiloXC(1) to only follow links up to a given maximum depth and to not follow off-site links, you end up with a document that has hyperlinks to content not brought into the document. These hyperlinks are referred to as unresolved links. You can choose whether to include the target URLs of these unresolved links in the document or not by setting the value attribute of the UnresolvedDetail element to either include or exclude, respectively.

    If you choose to include the unresolved link detail, iSiloXC(1) create a document with an additional page at the end that lists the URLs of all unresolved links. The target of each unresolved link in the document jumps to its corresponding target URL on this last page. This is useful for later reference and for finding broken hyperlinks.

    If you choose not to include the unresolved link detail, the unresolved hyperlinks essentially have no target. When viewing the document within a reader and attempting to follow such a hyperlink, the reader will tell you that the hyperlink was unresolved, but gives no indication of the target URL.

    The most common sources of unresolved links are the following:

    •   Links that are at a depth greater than that specified by the MaximumDepth element.

    •   Links that are outdated and thus are broken because the target has moved.

    •   Links whose targets are specified incorrectly.

    Examples
    This example specifies that unresolved link detail should be included.

          <UnresolvedDetail         value="include"/>

    This example specifies that unresolved link detail should not be included.

          <UnresolvedDetail         value="exclude"/>

<ImageOptions> ELEMENT
The ImagesOptions element specifies options for handling images.

  Full element example

        <ImageOptions>
          <AltText                  value="exclude"/>
          <Images                   value="include"/>
          <ResizeLargeImages        value="yes"/>
          <MaximumWidth             value="144"/>
          <MaximumHeight            value="144"/>
          <ImproveContrast          value="yes"/>
          <Dither                   value="yes"/>
          <Compress                 value="yes"/>
          <BitDepth1                value="exclude"/>
          <BitDepth2                value="exclude"/>
          <BitDepth4                value="include"/>
          <BitDepth8                value="exclude"/>
          <BitDepth16               value="include"/>
        </ImageOptions>

  Sub-element summary
Tag | Type | Default | Description
<AltText> | value | exclude | Whether to include the alternative text of images
<Images> | value | yes | Whether to include images
<ResizeLargeImages> | value | yes | Whether to resize large images
<MaximumWidth> | value | 144 | Maximum image width
<MaximumHeight> | value | 144 | Maximum image height
<ImproveContrast> | value | yes | Whether to improve the image contrast
<Dither> | value | yes | Whether to dither images
<Compress> | value | yes | Whether to compress images
<BitDepth1> | value | exclude | Whether to include 1-bit versions of images
<BitDepth2> | value | exclude | Whether to include 2-bit versions of images
<BitDepth4> | value | include | Whether to include 4-bit versions of images
<BitDepth8> | value | exclude | Whether to include 8-bit versions of images
<BitDepth16> | value | include | Whether to include 16-bit versions of images

  Sub-element descriptions

<AltText>

    Description
    Set the value attribute of the tag to include or exclude to respectively include or exclude the alternative text of images.

    In an HTML file, references to images often also include alternative text that can be used in place of the image. If you choose not to include images, you are recommended to include the alternative text of images so that images that serve as hyperlinks can still be utilized.

    Examples
    This example specifies that the alternative text of images should be included.

          <AltText                  value="include"/>

    This example specifies that the alternative text of images should not be included.

          <AltText                  value="exclude"/>

<Images>

    Description
    Set the value attribute of the tag to include or exclude to respectively include or exclude images.

    This setting applies to root source file images, images referenced through HTML <img> tags, and images that are hyperlink targets. If you include images, you can also set various options for them.

    Examples
    This example specifies that images should be included.

          <Images                   value="include"/>

    This example specifies that images should not be included.

          <Images                   value="exclude"/>

<ResizeLargeImages>

    Description
    Set the value attribute of the tag to yes or no to respectively enable or disable resizing of images larger than the specified maximum width or height as given by the MaximumWidth and MaximumHeight elements.

    Examples
    This example specifies that images should be included.

          <ResizeLargeImages        value="include"/>

    This example specifies that images should not be included.

          <ResizeLargeImages        value="exclude"/>

<MaximumWidth>

    Description
    Set the value attribute of the tag to a positive integer that specifies the maximum width in pixels for images. The value only has an effect on images if image resizing is enabled as specified by the ResizeLargeImages element, in which case, images with a width greater than the specified maximum width are resized so that their resulting width is no greater than the specified maximum width.

    Examples
    This example specifies a maximum width of 144 pixels for images.

          <MaximumWidth             value="144"/>

    This example specifies a maximum width of 304 pixels for images.

          <MaximumWidth             value="304"/>

<MaximumHeight>

    Description
    Set the value attribute of the tag to a positive integer that specifies the maximum height in pixels for images. The value only has an effect on images if image resizing is enabled as specified by the ResizeLargeImages element, in which case, images with a height greater than the specified maximum height are resized so that their resulting height is no greater than the specified maximum height.

    Examples
    This example specifies a maximum height of 144 pixels for images.

          <MaximumHeight            value="144"/>

    This example specifies a maximum height of 304 pixels for images.

          <MaximumHeight            value="304"/>

<ImproveContrast>

    Description
    Set the value attribute of the tag to yes to improve the contrast for black and white and grayscale images. Set the value attribute of the tag to no to leave the contrast as it is.

    Examples
    This example specifies that black and white and grayscale images should have their contrast improved.

          <ImproveContrast          value="yes"/>

    This example specifies that the contrast of images should not be changed.

          <ImproveContrast          value="no"/>

<Dither>

    Description
    Set the value attribute of the tag to yes or no to respectively enable or disable dithering of images.

    Dithering improves the look of an image when converting it to a lower color bit depth by diffusing the error introduced in lowering the number of colors available for use. Dithering has no effect when the image only consists of colors from the target color bit depth.

    Examples
    This example specifies that images should be dithered.

          <Dither                   value="yes"/>

    This example specifies that images should not be dithered.

          <Dither                   value="no"/>

<Compress>

    Description
    Set the value attribute of the tag to yes or no to respectively enable or disable compression of images. Compressing images generally reduces the space required to store the images, resulting in smaller document sizes.

    Examples
    This example specifies that images should be compressed.

          <Compress                 value="yes"/>

    This example specifies that images should not be compressed.

          <Compress                 value="no"/>

<BitDepth1> <BitDepth2> <BitDepth4> <BitDepth8> <BitDepth16>

    Description
    Set the value attribute of each tag to include or exclude to respectively include or exclude versions of images at the corresponding bit depth.

    If you are creating a document for use on different devices with different types of displays and different versions of Palm OSî, then you may need to include images at more than one color bit depth. If you are creating a document for use on only one device, then it is usually sufficient for you to include images at only one color bit depth. You can include images at the following bit depths:

    •   1-bit (black and white)

    •   2-bit (four shades of gray)

    •   4-bit (16 shades of gray)

    •   8-bit (the websafe palette, 256 colors)

    •   16-bit (64K colors)

    Each additional bit depth you include generally increases the size of the resulting document, but not always, because iSiloXC(1) always try to use the lowest possible maximum color bit depth possible for a given image. So even if you include 16-bit images but all your images are pure black and white 1-bit images, iSiloXC(1) will only store 1-bit versions of those images.

    The following table lists the Palm OSî versions and the maximum image color bit depths supported.
    Palm OS version | Maximum depth | Notes
    3.0/3.1/3.2 | 4-bit | None
    3.5 | 4-bit/8-bit/16-bit | Non-color devices display images at a maximum color depth of 4-bit. The only color device running Palm OS 3.5 that can display images with 16-bit color is the Visor Prism.
    4.0 | 4-bit/16-bit | Non-color devices display images at a maximum color depth of 4-bit.

    The above table may help you decide which color bit depths to include in a document if your audience is wide. One thing you can be sure of is that 1-bit images work across all devices.

    On any supported device, regardless of the color depths supported and regardless of what bit depths are included for the images, iSiloXC(1) will still display each image by either choosing the highest supported bit depth of the image or using the closest available colors to display each color of the image. No dithering is applied in the latter case, so the image may not appear as good, but the effect is usually usable.

    Examples
    This example specifies that only 4-bit and 16-bit versions of images should be included.

          <BitDepth1                value="exclude"/>
          <BitDepth2                value="exclude"/>
          <BitDepth4                value="include"/>
          <BitDepth8                value="exclude"/>
          <BitDepth16               value="include"/>

    This example specifies that only 2-bit versions of images should be included.

          <BitDepth1                value="exclude"/>
          <BitDepth2                value="include"/>
          <BitDepth4                value="exclude"/>
          <BitDepth8                value="exclude"/>
          <BitDepth16               value="exclude"/>

<TableOptions> ELEMENT
The TableOptions element specifies options for handling tables.

  Full element example

        <TableOptions>
          <IgnoreTables             value="no"/>
          <AddSeparators            value="no"/>
          <UseMinimumDepth          value="no"/>
          <MinimumDepth             value="1"/>
          <UseMaximumBottomReach    value="no"/>
          <MaximumBottomReach       value="1"/>
          <UnfoldFullPageTables     value="no"/>
          <IgnorePixelWidths        value="no"/>
        </TableOptions>

  Sub-element summary
Tag | Type | Default | Description
<IgnoreTables> | value | no | Whether to ignore table formatting
<AddSeparators> | value | no | Whether to add horizontal borders separating cells.
<UseMinimumDepth> | value | no | Whether to only include tables at a minimum depth
<MinimumDepth> | value | 1 | Minimum depth of tables to include
<UseMaximumBottomReach> | value | no | Whether to only include innermost tables
<MaximumBottomReach> | value | 1 | Maximum innermost table level to include
<UnfoldFullPageTables> | value | no | Whether to unfold full-page top-level tables
<IgnorePixelWidths> | value | no | Whether to table pixel width specifications

  Sub-element descriptions

<IgnoreTables>

    Description
    Set the value attribute of the tag to yes to exclude all table formatting data. The rows and cells of all tables unfold so that the content of each cell outputs to a new line.

    Set the value attribute of the tag to no to enable table formatting.

    Examples
    This example specifies that table formatting should be ignored.

          <IgnoreTables             value="no"/>

    This example specifies that table formatting should be included.

          <IgnoreTables             value="yes"/>

<AddSeparators>

    Description
    Set the value attribute of the tag to yes to add horizontal borders separating table cells when ignoring table formatting as specified by the <IgnoreTables> element. This option does nothing if table formatting is not ignored. Otherwise, if set to yes, thick horizontal borders are added at the top and bottom of the table, medium borders are added between rows, and thin borders are added between cells so that you can more easily see where one cell ends and another begins.

    Set the value attribute of the tag to no to not add horizontal borders between cells when ignoring table formatting.

    Examples
    This example specifies that separators should not be added between table cells.

          <AddSeparators            value="no"/>

    This example specifies that separators should be added between table cells.

          <AddSeparators            value="yes"/>

<UseMinimumDepth> <MinimumDepth>

    Description
    Set the value attribute of the <UseMinimumDepth> tag to yes to include only tables at a minimum depth as specified by the value attribute of the <MinimumDepth> tag. Set the value attribute of the <UseMinimumDepth> tag to no to not exclude tables based on a minimum depth.

    A table not embedded in any other table (e.g., an outermost table) is also called a top-level table and is considered to be at a depth of zero. Each additional embedding level adds one to a table's depth. Formatting for tables at levels less than the minimum depth will be excluded.

    This option is particularly useful for the case where the outermost set of tables up to a given depth are used only for layout.

    Examples
    The following shows a top-level table (Table A) with embedded tables. Tables B and C are embedded within Table A, while Table D, at a depth of two, is embedded within Table C.

        +----------------------------------------------------------+
        | Table A (depth: 0)                                       |
        +------------------------+---------------------------------+
        |                        | +-----------------------------+ |
        | +--------------------+ | | Table C (depth: 1)          | |
        | | Table B (depth: 1) | | +-----------------------------+ |
        | +---------+----------+ | | +--------------------+ +--+ | |
        | | B1      | B2       | | | | Table D (depth: 2) | |  | | |
        | +---------+----------+ | | +---------+----------+ |C2| | |
        |                        | | | D1      | D2       | |  | | |
        |                        | | +---------+----------+ +--+ | |
        |                        | +-----------------------------+ |
        +------------------------+---------------------------------+

    If you specify a minimum depth of one for converting the above table, the result will look like what is shown here below. Notice that the content of the outermost table is no longer formatted in tabular format.

          <UseMinimumDepth          value="yes"/>
          <MinimumDepth             value="1"/>

    Table A (depth: 0)

        +--------------------+
        | Table B (depth: 1) |
        +---------+----------+
        | B1      | B2       |
        +---------+----------+
        +-----------------------------+
        | Table C (depth: 1)          |
        +-----------------------------+
        | +--------------------+ +--+ |
        | | Table D (depth: 2) | |  | |
        | +---------+----------+ |C2| |
        | | D1      | D2       | |  | |
        | +---------+----------+ +--+ |
        +-----------------------------+

    This example specifies no table exclusions based on minimum depth.

          <UseMinimumDepth          value="no"/>

<UseMaximumBottomReach> <MaximumBottomReach>

    Description
    Set the value attribute of the <UseMaximumBottomReach> tag to yes to only include table formatting for the given number of innermost levels of tables as specified by the value attribute of the <MaximumBottomReach> tag. Set the value attribute of the <UseMaximumBottomReach> tag to no to not exclude tables based on innermost table level.

    One use for this option is in the case where it is only important for the innermost tables to be displayed in tabular format.

    Examples
    The following shows a top-level table (Table A) with embedded tables. Tables B and C are embedded within Table A, while Table D, at a depth of two, is embedded within Table C.

        +----------------------------------------------------------+
        | Table A (depth: 0)                                       |
        +------------------------+---------------------------------+
        |                        | +-----------------------------+ |
        | +--------------------+ | | Table C (depth: 1)          | |
        | | Table B (depth: 1) | | +-----------------------------+ |
        | +---------+----------+ | | +--------------------+ +--+ | |
        | | B1      | B2       | | | | Table D (depth: 2) | |  | | |
        | +---------+----------+ | | +---------+----------+ |C2| | |
        |                        | | | D1      | D2       | |  | | |
        |                        | | +---------+----------+ +--+ | |
        |                        | +-----------------------------+ |
        +------------------------+---------------------------------+

    If you specify a reachable depth of one for converting the above table, the result will look like what is shown here below. Notice that only Tables B and D retain their tabular formatting.

          <UseMaximumBottomReach    value="yes"/>
          <MaximumBottomReach       value="1"/>

    Table A (depth: 0)

        +--------------------+
        | Table B (depth: 1) |
        +---------+----------+
        | B1      | B2       |
        +---------+----------+

    Table C (depth: 1)

        +--------------------+
        | Table D (depth: 2) |
        +---------+----------+
        | D1      | D2       |
        +---------+----------+
        C2

    This example specifies no table exclusions based on innermost level.

          <UseMaximumBottomReach    value="no"/>

<UnfoldFullPageTables>

    Description
    Set the value attribute of the tag to yes to enable automatic determination of whether or not a given table is a full-page top-level table, and if so, to exclude its formatting information. A full-page top-level table is an outermost table that occupies the entire page. Set the value attribute of the tag to no to disable this check.

    Oftentimes, when a top-level table occupies the entire page, the tabular formatting is used only for layout. Furthermore, in such cases, the layout is oftentimes meant for display on suitably large screens. When such content is viewed on a smaller screen, it usually results in the need for frequent horizontal scrolling. The option to unfold full-page top-level tables can be used to help address the issue.

    Examples
    This example specifies that full-page top-level table formatting should be ignored.

          <UnfoldFullPageTables     value="yes"/>

    This example specifies no checking for full-page top-level tables.

          <UnfoldFullPageTables     value="no"/>

<IgnorePixelWidths>

    Description
    Set the value attribute of the tag to yes to disregard any widths specified in pixels for tables. Set the value attribute of the tag to no to respect any specified pixel widths. Usually, when a table has pixel widths specified, it was designed for display on a screen of a certain size. For smaller screens, such pixel width specifications often result in the need to scroll horizontally to view the content.

    Examples
    This example specifies that table pixel widths should be ignored.

          <IgnorePixelWidths        value="yes"/>

    This example specifies that table pixel widths should be respected.

          <IgnorePixelWidths        value="no"/>

<ColorOptions> ELEMENT
The ColorOptions element specifies options for handling background and text color.

  Full element example

        <ColorOptions>
          <BackgroundColors         value="keep"/>
          <TextColors               value="keep"/>
        </ColorOptions>

  Sub-element summary
Tag | Type | Default | Description
<BackgroundColors> | value | keep | Whether to keep or ignore background colors
<TextColors> | value | keep | Whether to keep or ignore text colors

  Sub-element descriptions

<BackgroundColors>

    Description
    Set the value attribute of the tag to one of the following values to specify whether to keep or ignore background colors:

    •   keep: Keep all background colors.

    •   ignore: Ignore all background colors.

    •   IgnoreBody: Ignore the background color specified for the entire body of a page. In this case, sub-blocks of content within a page retain their individual background colors.

    The default background color is white.

    Examples
    This example specifies that all background colors should be kept.

          <BackgroundColors         value="keep"/>

    This example specifies that all background colors should be ignored.

          <BackgroundColors         value="ignore"/>

    This example specifies that only colors specified for the page body background should be ignored.

          <IgnoreColors             value="IgnoreBody"/>

<TextColors>

    Description
    Set the value attribute of the tag to keep to keep all text colors or to ignore to ignore all text colors. The default text color is black.

    Examples
    This example specifies that all text colors should be kept.

          <TextColors               value="keep"/>

    This example specifies that all text colors should be ignored.

          <TextColors               value="ignore"/>

<MarginOptions> ELEMENT
The MarginOptions element specifies options for handling margins.

  Full element example

        <MarginOptions>
          <LeftRightMargins         value="keep"/>
        </MarginOptions>

  Sub-element summary
Tag | Type | Default | Description
<LeftRightMargins> | value | keep | Whether to keep or ignore left and right margins

  Sub-element descriptions

<LeftRightMargins>

    Description
    Set the value attribute of the tag to one of the following values to specify whether to keep or ignore left and right margins:

    •   keep: Keep all left and right margins.

    •   ignore: Ignore all left and right margins.

    •   IgnoreBody: Ignore left and right margins specified for the entire body of a page. In this case, blocks of content within a page retain their individual left and right margins.

    •   IgnoreBDP: Ignore only the left and right margins specified for the entire body of a page and for any blocks marked as divisions or paragraphs. Any other blocks of content within a page retain their individual left and right margins.

    The default left and right margins are zero.

    Examples
    This example specifies that all left and right margins should be kept.

          <LeftRightMargins          value="keep"/>

    This example specifies that all left and right margins should be ignored.

          <LeftRightMargins          value="ignore"/>

    This example specifies that only left and right margins specified for the entire body of a page should be ignored.

          <LeftRightMargins          value="IgnoreBody"/>

    This example specifies that only left and right margins specified for the entire body of a page and for blocks marked as divisions or paragraphs should be ignored.

          <LeftRightMargins          value="IgnoreBDP"/>

<SecurityOptions> ELEMENT
The SecurityOptions element specifies settings for securing the content of a document. iSiloXC(1) add indicators to the converted document so that conforming applications that utilize the document can determine what types of actions to allow on the document.

  Full element example

        <SecurityOptions>
          <CopyBeam                 value="allow"/>
          <CopyAndPaste             value="allow"/>
          <Modify                   value="allow"/>
          <Convert                  value="allow"/>
          <Print                    value="allow"/>
        </SecurityOptions>

  Sub-element summary
Tag | Type | Default | Description
<CopyBeam> | value | allow | Whether to allow copying and beaming of the document
<CopyAndPaste> | value | allow | Whether to allow copying of content to the clipboard
<Modify> | value | allow | Whether allow modification of the document
<Convert> | value | allow | Whether to allow conversion to other formats
<Print> | value | allow | Whether to allow printing of the document.

  Sub-element descriptions

<CopyBeam>

    Description
    Set the value attribute of the tag to allow or disallow to respectively allow or disallow copying and beaming of the document.

    Examples
    This example specifies that copying and beaming should be allowed.

          <CopyBeam                 value="allow"/>

    This example specifies that copying and beaming should not be allowed.

          <CopyBeam                 value="disallow"/>

<CopyAndPaste>

    Description
    Set the value attribute of the tag to allow or disallow to respectively allow copying of content from the document to the system clipboard or disallow the operation so that content can not be copied and pasted elsewhere.

    Examples
    This example specifies that copying to the clipboard should be allowed.

          <CopyAndPaste             value="allow"/>

    This example specifies that copying to the clipboard should not be allowed.

          <CopyAndPaste             value="disallow"/>

<Modify>

    Description
    Set the value attribute of the tag to allow or disallow to respectively allow or disallow modification of the document. This includes modification of the document's global and document bookmarks.

    Examples
    This example specifies that the document can be modified.

          <Modify                   value="allow"/>

    This example specifies that the document may not be modified.

          <Modify                   value="disallow"/>

<Convert>

    Description
    Set the value attribute of the tag to allow or disallow to respectively allow or disallow conversion of the document to other formats. Saving the content of a document to a text file is also considered a conversion of the document to another format.

    Examples
    This example specifies that the document can be converted to other formats.

          <Convert                  value="allow"/>

    This example specifies that the document may not be converted to other formats.

          <Convert                  value="disallow"/>

<Print>

    Description
    Set the value attribute of the tag to allow or disallow to respectively allow or disallow printing of the document. Though at this time you can not directly print a document from all platforms for which iSilo is available, it may become possible to do so in the future. If you know now that you do not want to allow printing regardless of the case, set the value attribute of this tag to disallow.

    Examples
    This example specifies that the document can be printed.

          <Print                    value="allow"/>

    This example specifies that the document may not be printed.

          <Print                    value="disallow"/>

<TextOptions> ELEMENT
The TextOptions element specifies settings that apply to the conversion of plain text files. Examples of plain text files include files with the extension .txt and Palm Doc files.

  Full element example

        <TextOptions>
          <ProcessLineBreaks        value="yes"/>
          <ConvertSingleLineBreaks  value="no"/>
          <TabStopWidth             value="8"/>
          <Preformatted             value="no"/>
          <UseMonospaceFont         value="no"/>
          <MonospaceFontSize        value="10"/>
        </TextOptions>

  Sub-element summary
Tag | Type | Default | Description
<ProcessLineBreaks> | value | yes | Whether to interpret line breaks
<ConvertSingleLineBreaks> | value | no | Whether to remove single line breaks
<TabStopWidth> | value | 8 | The tab stop width to use
<Preformatted> | value | no | Whether to interpret the text as preformatted
<UseMonospaceFont> | value | no | Whether to use a monospace font for the text
<MonospaceFontSize> | value | 10 | The monospace font size to use

  Sub-element descriptions

<ProcessLineBreaks>

    Description
    Set the value attribute of the tag to yes so that line breaks are processed or no to leave line break characters as they are.

    The iSilo document format uses linefeed characters (ASCII 10) to indicate line breaks. If you set the value attribute of the ProcessLineBreaks tag to yes, which is recommended, iSiloXC(1) correctly convert line breaks in text files that utilize either carriage return characters (ASCII 13) alone as line breaks or carriage return and linefeed characters in pairs as line breaks. If you set the value attribute to no, the resulting document may display incorrectly.

    Examples
    This example turns line break processing on.

          <ProcessLineBreaks        value="yes"/>

    This example turns line break processing off.

          <ProcessLineBreaks        value="no"/>

<ConvertSingleLineBreaks>

    Description
    Set the value attribute of the tag to <code>.It Em yes</b></code> to remove single line breaks or no to leave single line breaks as they are.

    Some text files are formatted with a given screen size in mind, such as an 80 column wide screen and line breaks occur on each line before column 80. When such a file is displayed on a narrower screen, the reader needs to scroll horizontally to read the part of the line that is wider than the screen. Moreover, if the application that displays the content does not have the ability to provide horizontal scrolling, the text will likely look like it is ill-formatted. As an example, consider the following block of text formatted for a 60 column screen:

        Some text files are formatted with a given screen size in
        mind, such as an 80 column wide screen and line breaks
        occur on each line before column 80.
        When such a file is displayed on a narrower screen, the
        reader needs to scroll horizontally to read the part of the
        line that is wider than the screen.

    When the content is displayed on a 40 column wide screen with no horizontal scrolling, the output may look like this:

        Some text files are formatted with a
        given screen size in
        mind, such as an 80 column wide screen
        and line breaks
        occur on each line before column 80.
        When such a file is displayed on a
        narrower screen, the
        reader needs to scroll horizontally to
        read the part of the
        line that is wider than the screen.

    Oftentimes, in such files, paragraphs will be double-spaced with respect to one another. In this case, you can set the value attribute of the ConvertSingleLineBreaks tag to yes and iSiloXC(1) will replace the single line breaks within a paragraph to spaces so that the document can be reflowed evenly for a screen of any width. The above example would then look like this on a 40 column wide screen:

        Some text files are formatted with a
        given screen size in mind, such as an
        80 column wide screen and line breaks
        occur on each line before column 80.
        When such a file is displayed on a
        narrower screen, the reader needs to
        scroll horizontally to read the part of
        the line that is wider than the screen.

    Examples
    This example specifies that single line breaks should be removed.

          <ConvertSingleLineBreaks  value="yes"/>

    This example specifies that single line breaks should not be removed.

          <ConvertSingleLineBreaks  value="no"/>

<TabStopWidth>

    Description
    Within text files, tab characters are often used to align text. Set the value attribute of the TabStopWidth tag to the tab stop width for which the text file was written.

    Examples
    This example specifies that the tab stop width should be eight.

          <TabStopWidth             value="8"/>

    This example specifies that the tab stop width should be four.

          <TabStopWidth             value="4"/>

<Preformatted>

    Description
    Set the value attribute of the tag to <code>.It Em yes</b></code> to interpret the text as preformatted or no to not.

    If a text file is preformatted, it means that the content should not be reflowed and that the position of line breaks should not be modified. Performing either of these operations may mess up the original desired appearance of the content. In this case, you want to set the value attribute of the Preformatted tag to yes so that iSiloXC(1) honors the preformatting.

    Examples
    This example specifies that the text should be treated as being preformatted.

          <Preformatted             value="yes"/>

    This example specifies that the text should not be treated as being preformatted.

          <Preformatted             value="no"/>

<UseMonospaceFont>

    Description
    Set the value attribute of the tag to <code>.It Em yes</b></code> to have the text displayed using a monospace font or no to not.

    The text file may have been designed to be displayed using a monospace font as opposed to a proportional font. Using a monospace font makes it possible to align text along columns and to create tabular data (e.g., tables). Set the value attribute of the UseMonospaceFont tag to yes and specify a desired font size using the MonospaceFontSize tag.

    Examples
    This example specifies that the text should be displayed using a monospace font.

          <UseMonospaceFont         value="yes"/>

    This example specifies that the text should be displayed using a proportional font.

          <UseMonospaceFont         value="no"/>

<MonospaceFontSize>

    Description
    Set the value attribute of the tag to a positive integer in the range from 1 to 255 for the desired monospace font size in points for displaying the text.

    This setting only has an effect when the value attribute of the UseMonospaceFont tag is set to yes. Note that the value you provide is only a desired setting. The actual display device may or may not be able to honor the given font size you set.

    Examples
    This example specifies a desired monospace font size of 10 points.

          <MonospaceFontSize        value="10"/>

    This example specifies a desired monospace font size of 14 points.

          <MonospaceFontSize        value="14"/>

<Bookmarks> ELEMENT
The Bookmarks element specifies settings for adding predefined bookmarks to a document.

  Full element example

        <Bookmarks>
          <Document>
            <UseFile                value="no"/>
            <Path>~/docs/bookmarks.htm</Path>
            <UseNamedAnchors        value="no"/>
            <NamedAnchorType        value="WordWebPage"/>
            <UseIncludeFilter       value="no"/>
            <IncludePrefix>bm</IncludePrefix>
            <UseExcludeFilter       value="no"/>
            <ExcludePrefix>bm_</ExcludePrefix>
          </Document>
        </Bookmarks>

  Sub-element summary
Tag | Type | Default | Description
<Document> | container | n/a | Specifies document bookmarks to add to the document.

  <Document> sub-element summary
The elements in the <Document> container element specify the document bookmarks to add to a document. A document may have up to 1024 bookmarks. The bookmarks you specify in this element are also known as predefined bookmarks. Predefined bookmarks may be generated from hyperlinks in an HTML file and/or from the named anchors in the document source files. If both are specified, bookmarks specified in the HTML file are added before those from named anchors in the document source files.
Tag | Type | Default | Description
<UseFile> | value | no | Whether to create bookmarks from hyperlinks in an HTML file
<Path> | string | n/a | Path to HTML file containing hyperlinks to use as bookmarks
<UseNamedAnchors> | value | no | Whether to create bookmarks from named anchors
<NamedAnchorType> | value | WordWebPage | Types of named anchors to use for bookmarks
<UseIncludeFilter> | value | no | Whether to apply named anchor inclusion filtering
<IncludePrefix> | string | n/a | Inclusion prefix for named anchor filtering
<UseExcludeFilter> | value | no | Whether to apply named anchor exclusion filtering
<ExcludePrefix> | string | n/a | Exclusion prefix for named anchor filtering

  <Document> sub-element descriptions

<UseFile> <Path>

    Description
    Set the value attribute of the <UseFile> tag to yes and provide the path to an HTML file in the Path element to add the hyperlinks in the file as bookmarks to the document. Each hyperlink in the file adds a bookmark to the document in the same order as the hyperlinks appear in the file. The hyperlink text (e.g., the content between the opening target tag and the closing tag) serves as the bookmark name.

    Set the value attribute of the <UseFile> tag to no to not create bookmarks from the hyperlinks of an HTML file.

    Examples
    This example specifies that the bookmarks are to be created from the hyperlinks in the file whose path is ~/docs/bookmarks.htm.

          <UseFile                value="yes"/>
          <Path>~/docs/bookmarks.htm</Path>

    This example specifies that no bookmarks are to be created from a file. In this case, the Path element is ignored, so it is not shown nor needed.

          <UseFile                value="no"/>

<UseNamedAnchors> <NamedAnchorType>

    Description
    Set the value attribute of the <UseNamedAnchors> tag to yes to generate bookmarks based on named anchors (e.g., anchorName > tags in HTML source files) from the document source files. Then set the value attribute of the <NamedAnchorType> tag to one of the following values to specify which named anchors to add:

    •   WordWebPage : If the document source files were generated using Microsoft Word and saved in Web Page format, then use this value. In this case, only named anchors that do not begin with an underscore character (e.g., '_') are added as bookmarks. The anchor names serve as the bookmark names.

    •   all : All named anchors are added as bookmarks and the anchor names serve as the bookmark names.

    •   filtered : All named anchors are added as bookmarks subject to optional inclusion and/or exclusion filtering criteria. See the descriptions for <UseIncludeFilter> and <UseExcludeFilter> for how to specify the inclusion and exclusion filters, respectively.

    Set the value attribute of the <UseNamedAnchors> tag to no to not create bookmarks from the named anchors of the document source files.

    Examples
    This example specifies that bookmarks are to be created from named anchors that match the format of bookmarks in a Microsoft Word Web Page file.

          <UseNamedAnchors        value="yes"/>
          <NamedAnchorType        value="WordWebPage"/>

    This example specifies that bookmarks are to be created from all named anchors from all document source files.

          <UseNamedAnchors        value="yes"/>
          <NamedAnchorType        value="all"/>

    This example specifies that no bookmarks are to be created from named anchors.

          <UseNamedAnchors        value="no"/>

<UseIncludeFilter> <IncludePrefix>

    Description
    Set the value attribute of the <UseIncludeFilter> tag to yes to generate bookmarks from only those named anchors that begin with the prefix given in the IncludePrefix element. For each named anchor having the given prefix, a bookmark is added, with the anchor name minus the prefix serving as the bookmark name.

    Note that the UseIncludeFilter and IncludePrefix elements have effect only if the value attribute of the <NamedAnchorType> tag is set to filtered.

    Set the value attribute of the <UseIncludeFilter> tag to no to not use an inclusion filter.

    Examples
    This example specifies that only named anchors beginning with the two character sequence 'bm' should be used as bookmarks.

          <UseNamedAnchors        value="yes"/>
          <NamedAnchorType        value="filtered"/>
          <UseIncludeFilter       value="yes"/>
          <IncludePrefix>bm</IncludePrefix>

<UseExcludeFilter> <ExcludePrefix>

    Description
    Set the value attribute of the <UseExcludeFilter> tag to yes to prevent the generation of bookmarks from named anchors that begin with the prefix given in the ExcludePrefix element.

    Note that the UseExcludeFilter and ExcludePrefix elements have effect only if the value attribute of the <NamedAnchorType> tag is set to filtered.

    Set the value attribute of the <UseExcludeFilter> tag to no to not use an exclusion filter.

    Examples
    This example specifies that all named anchors except those beginning with the underscore character (e.g., '_') should be used as bookmarks.

          <UseNamedAnchors        value="yes"/>
          <NamedAnchorType        value="filtered"/>
          <UseExcludeFilter       value="yes"/>
          <ExcludePrefix>_</ExcludePrefix>

    This example specifies that only named anchors beginning with the two character sequence 'bm' should be used as bookmarks. However, named anchors beginning with the three character sequence 'bm_' should not be used as bookmarks.

          <UseNamedAnchors        value="yes"/>
          <NamedAnchorType        value="filtered"/>
          <UseIncludeFilter       value="yes"/>
          <IncludePrefix>bm</IncludePrefix>
          <UseExcludeFilter       value="yes"/>
          <ExcludePrefix>bm_</ExcludePrefix>

<LastConversion> ELEMENT
The LastConversion element stores information about the last conversion.

  Full element example

        <LastConversion>
          <Date>2002/08/01 08:12:02</Date>
          <Size value="123456789"/>
          <Status>Conversion successful</Status>
        </LastConversion>

  Sub-element summary
Tag | Type | Default | Description
<Date> | string | n/a | Date of last conversion
<Size> | value | n/a | Converted file byte size
<Status> | string | n/a | Readable last conversion status result

  Sub-element descriptions

<Date>

    Description
    The content of the Date element is a string in the form YYYY/MM/DD HH:MM:SS that indicates the time of the last conversion. YYYY/MM/DD is the year, month, and day and HH:MM:SS is the hour minute and second. The time is generally interpreted as local time.

    Examples
    This example specifies that the last conversion occurred on August 1, 2002 at about 8:12AM.

          <Date>2002/08/01 08:12:02</Date>

    This example specifies that the last conversion occurred on October 10, 2010 at 10:10AM.

          <Date>2010/10/10 10:10:00</Date>

<Size>

    Description
    The value attribute of the Size tag holds the size in bytes of the resulting document from the last conversion.

    Examples
    This example specifies that the last conversion resulted in a file with a size of 492132 bytes.

          <Size value="492132"/>

    This example specifies that the last conversion resulted in a file with a size of 4356 bytes.

          <Size value="4356"/>

<Status>

    Description
    The Status element provides a short textual description of the result of the last conversion.

    Examples
    This example specifies that the last conversion was successful.

          <Status>Conversion successful</Status>

    This example specifies that the last conversion was cancelled.

          <Status>Conversion cancelled</Status>

SEE ALSO
iSiloXC(1)

AUTHORS
ISilo are copyright DC & Co. For more information about iSilo, and to download the Palm Pilot reader for iSilo format documents, go to http://www.iSilo.com/.

This manual page was written by Sergey Skvortsov <skv@FreeBSD.org>.