Thout Package Documentation

Thout Package Format 2

Package file structure 2

JAR file [example.jar] 2

XML File [example.xml] 2

Properties File [thout_package.properties] 2

Resource files [images] 2

Package XML structure 3

The Package Tag 3

Outline tags and attributes 3

CSS Development 4

#
Thout Package Format

A Thout package is a volume of content, which is defined in a single XML file. We will call this the package XML file.

## Package file structure

[example.jar]

example.xml

thout_package.properties

stylesheet.css

[images]

image1.gif

image2.gif

### JAR file [example.jar]

A package consist of several files zipped into a jar file.

Note: A true jar file contains a manifest, however a manifest is not required when creating Thout packages. This allows you to simply zip the files and rename the extension from .zip to .jar.

### XML File [example.xml]

A package should include one root .xml file. The name of the file is not currently important. The xml file should be well formed.

### Properties File [thout_package.properties]

A property sheet should be included with each package. For DRM encrypted packages, the property file is not encrypted which allows the package properties to be read without having to decrypt the file. The property file is simply a text file in the following format.

name: Example Package

revision: 1.0

author: John Doe

publisher: Osoft

copyright: regx 2005

license: NA

packaged_by: John Doe

stylesheet: example.css

toc_background_color: #F1F0FF

Currently only the name and revision are required.

### Resource files [images]

A package can include resource files in addition to the package XML file. For instance, it may include Jpeg or .gif graphic files. The relative URL for an included image, as referenced from the package XML file, is the path from the root of the jar file for example <img src="images/image1.gif>.

## Package XML structure

A package XML file always contains a root pkg:package tag. Other tags may be nested inside the content elements of this tag, including tags from the built in "package:" and "books:" namespaces, and HTML tags.

### The Package Tag

The pkg:package tag is required. It's attributes are

• name - Package Name

• revision -identifies version number if there are multiple versions

• xmlns - The xml namespace definition. You should list here all of the schemas for the content type namespaces used in the package, "pkg/package" is required. "html" is implied if there is no namespace prefix.

The package elements are

• author - the package author. There may be more than one

• publisher - the package publisher. There may be more than one

• content - holds the actual package content.

### Outline tags and attributes

The package content are navigated by a table of contents outline that appears in the left hand "browse" panel of the Thout Reader. The Thout Reader builds this table of contents by reading outline tags, which enclose the content pages. Outline tags must contain two attributes - an OutlineName which specifies the text that appears in the outline, and an id, which is a unique id string within the package. The outline id's are used as URL's to identify locations in the text for linking and annotation.

Note: tag names are case sensitive

#### pkg:outlineMarker

This tag defines the table of contents displayed in the browse pane and has the following attributes:

- Required

o OutlineName - the name that will appear in the outline

o ID - an ID string, unique inside the package

- Optional

- render = "true" | "false". The default is true. If false, causes the right content pane to not render the content included in this tag, but to render the content enclosed in the first included outline tag that is not marked 'render="false'". This tag is used on top level outline items that enclose very large content pages which would otherwise render slowly.
- visible = "true" | "false". The default is true. If false, this causes the outline name not to appear in the browse panel. This is useful for creating navigation points that will be referenced by notes, links, or "ioc" entries.
- showpage="ID". This will display the child page "ID" when the outline item is selected and render="false"
- render="parent". This will render the parent node. Usefull if you want to place hidden markers that would show up in a search, but do not know the parent node id. Such as when parsing a name references from HTML. Depending on the method used for parsing the parent node may or may not be easily accessible.
- renderchildren=”false” This will render the current node, but will not render any child nodes.
- copy=”true”|”false” Node content can be copied via the copy icon. This is only needed for encrypted content to allow copying, but is also useful for displaying source code
- closeIcon, openIcon, leafIcon - specify the graphic files that will appear next to the OutlineName in the browse panel. The graphic files in this case are .gif files, in a 16x16 pixel format, that are included as package resources. Example: leafIcon=”images/leaf.gif”

#### Inline HTML

HTML tags can be used in the content inline. HTML tags can have an html: prefix, or they can omit this, as the html: namespace is a default for content in the package.

#### Links and Link URL's

Links can be inserted in content by using the standard HTML link tag, <a href="destination URL">. Currently, the Thout Reader supports two types of link URL's, for Web pages and Thout packages. A standard "http:" URL will invoke a Web browser when the user clicks a link. A URL of the form href="pkg://packagename/ TagID=id" will go to the package and outline ID that is specified. A URL of the form href="id" is a relative package URL, and it links to the specified outline ID in the same package.

### CSS Development

When developing css stylesheets you can overide the stylesheet specified in the package by placing a css named osoft_dev.css in your windows temp directory.