Important Iliad configuration files

File associations

The main configuration file for the reader's features is /mnt/settings/registry/registry.xml. There is also a template configuration file, /etc/registry/registry.xml, which lacks some data, such as the owner's name and language setting, and which is not used by the content lister. Both contain information about file associations, i. e. how to open files with specific file name extensions. They are located at the path /iLiadRegistry/applications in the XML files.

Each application is represented by a application tag at that path, such as the following for the browser:

<application type="BROWSER">
    <appCategory>viewer</appCategory>
    <argMask>_MANIFEST_ _FILENAME_</argMask>
    <execute>/usr/bin/browser</execute>
    <supportFormat>
        <extName>html</extName>
        <extName>htm</extName>
        <extName>xhtml</extName>
    </supportFormat>
    <xResourceName>browser</xResourceName>
    <ipcChannel>1</ipcChannel>
    <appIconPath>browser.png</appIconPath>
</application>

This gives an application type ID (which is used in the separate extension infos, see below), the path to the viewer executable and how to call it, and its associated file extensions. The appCategory is either "viewer" (for display programs) or "setup" (for programs setting preferences or network profiles). The argMask tag gives the command line arguments the application is to be called with. _FILENAME_ and _MANIFEST_ refer to the document and metadata files, respectively. Fixed command-line arguments such as options can also be given. The ipcChannel may once have selected a channel for inter-process communication, but seems to be unused now. The order of the tags is not important, it differs slightly between different entries.

In addition to the application tags, partly redundant information is kept in extensionInfo tags at the XML path /iLiadRegistry/extensionInfos. Their primary purpose is to define how different files are displayed in the content lister. Files which have no extensionInfo tag can be viewed if an application tag indicates support for them. One of the more interesting extensionInfo entries is the following:

<extensionInfo>
    <associateApp>BROWSER</associateApp>
    <associateOrder>10</associateOrder>
    <extName>txt</extName>
    <extIcon>/usr/share/contentlister/Icon_documents.png</extIcon>
</extensionInfo>

It gives the icon to use for .txt files and associates the browser (application type ID BROWSER) with it, even though its application info does not list txt as one of its supported extensions. The interesting bit is the associateOrder tag, which defines the priority with which this application is used for this file type. Immediately above the entry shown here, there is another entry for txt with associated application MOBIPOCKET and associateOrder 1, so the Mobipocket reader is always used for plain text files. Finally, the extIcon tag defines the icon to display for the given file extension.

These file associtation entries are also the means by which shell access is enabled by the iDS package you can request from iRex: An application entry is simply added which associates the shell /bin/sh with the file extension sh.

Directory appearance and main menu

By default, the content lister displays files and directories using an icon corresponding to their type, and the file name and size. The icons are located in the directory /usr/share/contentlister/ and are associated with specific file extensions by the extensionInfo tags in the file /mnt/settings/registry/registry.xml, see above. All the standard icons are 69 x 93 greyscale PNG images with 8 bits per pixel. They are superimposed on top of the image /usr/share/contentlister/Iconbar.png, which is a solid black rounded rectangle. The easiest way to customise the appearance of your Iliad is to substitute different icons, either by replacing the images in /usr/share/contentlister/ or by modifying registry.xml.

But the content lister is more flexible than just assigning icons by file extension. If a directory contains an XML file named manifest.xml, its content determines how it is displayed. As far as I have seen, it can contain the following metadata:

Note that putting a startfile in manifest.xml hides all other files (unless the viewer program itself traverses the directory). This is used by software installers, which give an installer shell script as the startfile. When the user clicks on the package directory, the installer is started (assuming shell access is enabled), but the directory contents are not displayed, which would not be helpful anyway. One of the entries /package/metadata/y-metadata/startpage, /package/directory/content or /package/storage/Identifier has to be present, or the Iliad will not know what to open. For example, I put a title icon on a directory containing a web serial novel using the following (complete) manifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<package>
  <metadata>
    <dc-metadata>
      <Title>title</Title>
      <Description>author name</Description>
    </dc-metadata>
    <y-metadata>
      <image>icon.png</image> 
    </y-metadata>
  </metadata>
  <directory>
    <content>.</content>
  </directory>
</package>

Giving the author name as the description prints it underneath the title. The icon.png is located in the directory. The /package/directory/content tag is necessary so the directory is displayed as normal.

The PDF reader program ipdf "converts" a PDF document into a subdirectory when it first opens it: A directory with the same name (including the extension .pdf) is generated, the document is moved into it, and a manifest.xml is created in the directory which associates the directory with the document via the /package/metadata/y-metadata/startpage entry. This change is completely invisible to the user: Because of the startpage entry, the directory is displayed with the same icon as PDF files, and the actual PDF file is opened; after the viewer is closed, the content lister again displays the higher-level directory.

Manifest files are also used for creating the Iliad main menu. It is located in /usr/share/contentlister/mode/en (and neighbouring directories for languages other than English). There is a subdirectory for each of the main menu entries and storage devices, named 1_setup etc. to fix their order. Each subdirectory contains a manifest.xml and an icon. The setup and profile configuration programs have application ID entries in /mnt/settings/registry/registry.xml and are started via the /package/application/Identifier entry in the manifest. The "Reference Materials" menu entry links to the directory /mnt/free/documents/Reference using a /package/directory/content entry in the manifest. The others use a /package/storage/Identifier entry in the manifest to link to a storage region. Storage regions are directory paths defined in /mnt/settings/registry/registry.xml, in the XML paths /iLiadRegistry/categories/category.

So to customize the main menu (also called the Device Manager), you have to rearrange or modify the subdirectories of /usr/share/contentlister/mode/<your language>. You can change the order of entries by renaming them, substitute icons or add new entries.

Dealing with XML files

Unlike most configuration files on Linux systems, Iliad-specific settings are stored in XML files. While they are more or less human-readable, it is sometimes helpful to use special tools for accessing them. The following programs are not installed on the Iliad, but can be found in Linux distributions for your desktop box.

xmllint

A very useful tool for exploring XML files is xmllint, which comes with the libxml2 library.

An option that is simple but very useful when you need it is --format. It indents the XML file according to its hierarchical structure and allows reading autogenerated XML files like some manifest.xml files on the Iliad, which contain no newlines and indentation.

A more sophisticated use is the following, which gives you an interactive shell:

xmllint --shell file.xml

It allows you to traverse the hierarchical structure of the file, to extract and print parts of it. Unfortunately its shell commands are not well documented. Here is a run-down of the most important commands:

cat [ path ]

Output the tag given by the path and its content.

cd [ path ]

Change current path to the argument or top node.

du

Print the sub-structure at the current path. (Contrary to the documentation, this command does not accept a path argument.)

ls [ path ]

Display the tags and their content at the given path or the current path (if omitted). The output consists of three columns, flags, size and tag name. The first of the flags (t) indicates content or other non-tag text, the second distinguishes tags with attributes but is also set for text, and the third is set for text of more than 8 characters (don't ask me why). The second column is the size. This is the number of characters for text, and the number of sub-objects (text or tag) for tags. The third column gives the tag name or the non-tag text.

Ctrl-D

This keycode exits the shell (as do the quit and exit commands).

Sometimes you may encounter several tags with the same name next to each other. To specify one of them, you have to give its one-based index in square brackets after the name, such as for example for an extensionInfo tag in registry.xml:

cat /iLiadRegistry/extensionInfos/extensionInfo[4]/extName

If you give no index, cat will display the tags for all indices, one after the other.

XMLStarlet

A command-line program for automated processing is XMLStarlet. The xmlstarlet program has a rather terse manual page; usage notes are best obtained by running xmlstarlet --help or xmlstarlet command --help. Depending on your installation, the xml command may be a symbolic link to xmlstarlet, which can save you some typing.

For investigating an XML file, the commands el and sel are most interesting. el prints out the structure of the XML file (similar to the du command of xmllint). For example:

xmlstarlet el -a registry.xml
xmlstarlet el -d2 registry.xml

The first example command prints the structure of the whole file including attributes, the second prints the structure up to a depth of 2 only (top-level tags and their direct sub-tags).

The command sel can be used for extracting information from an XML file. Its syntax is somewhat obscure. The option -t has to be passed always, even though it is not documented at all.

You can print a subtree of the XML file with the -c option (analogous to the cat command of xmllint):

xmlstarlet sel -t -c iLiadRegistry/version registry.xml

The command above prints the version tag and the registry tag it contains, which in turn contains the Iliad version. The argument of the -c option is an XPath. If it is relative, as above, it is taken relative to the root of the file. If a path is ambiguous, you can specify the element you mean by giving an index.

xmlstarlet sel -t -c /iLiadRegistry/extensionInfos/extensionInfo[1] registry.xml

The command above outputs the first file association entry from the Iliad registry. This time, an absolute path is used. If no index had been given, all extensionInfo tags at the given path would have been printed. an XPath also allows searching for tags at arbitrary positions in the XML tree. The following command finds the version tag automatically:

xmlstarlet sel -t -c //version

And this command prints the tag describing the browser application and its subtags:

xmlstarlet sel -t -c "//application[@type='BROWSER']" registry.xml

The option -v used with the sel command outputs the value, that is, the non-tag content, at a path. Both the following commands give you just the Iliad version, without tags (but with differing amount of white space, because effectively different paths are given):

xmlstarlet sel -t -v iLiadRegistry/version/registry registry.xml
xmlstarlet sel -t -v //version registry.xml

The -v option can also be used to count occurrences, with the XPath function count(). The following command counts the number of extensionInfo tags anywhere in registry.xml:

xmlstarlet sel -t -v "count(//extensionInfo)" registry.xml

TOS / Impressum