Using DocView

Adding documentation using metadata

DocView provides a feature to extend the list of documentation available through its server. If you install new documentation that you want to include in DocView's lists, you supply a doc metadata file and execute the doctool configuration script.

Each package installing documentation should install a metadata file in the standard location /usr/share/meta/doc. That metadata file provides information about the documentation as described below. That information is used the DocView configuration program to generate the lists of available documentation.
The postinstall script for a package installing doc should execute the command:
```
   doctool --add pathname/mydoc.desktop
```
The path should be relative to /usr/share/meta/doc, where the metadata file is installed. This program is located in /usr/bin/doctool.
When a package is removed, so is the metadata. The pre removal script should execute the command:
```
   doctool --remove pathname/mydoc.desktop
```

See ``Document example'' for an example of writing and installing metadata file.

If you are installing or removing many .desktop files, the process can be made more efficient with the --metaonly option. This option causes the --add option to install the document metadata into the DocView configuration, but does not regenerate the home pages. Then you run the command without the --metaonly option on the last document to regenerate the home pages.

Metadata files

There are two types of metadata files: .directory files for categories, and bookid.desktop for documents.

Both metadata files use a format of fieldname=value to identify the metadata fields.
For each installed book or guide that has a table of contents to point to, there will be a corresponding bookID.desktop file, where bookID identifies the document.
The .desktop files are arranged in a directory hierarchy that corresponds to the logical hierarchy of the document lists that are presented to the user. Each directory is a category or grouping of documents, and may have subcategories.
The metadata for a category/directory will be in a hidden file named .directory within the directory.
The following fields in the .desktop files are used for generating entries for documentation items in the navigation lists:

Name=Displayed title
This field contains the default title to display in the default language list. The title may include spaces.

Name[xx]=Localized title
Where xx is a language code, indicating that this translated title should be used when the user's language is set to this language code.

DocPath=pathname
The full pathname to the table of contents HTML file for the document. That table of contents file should point to the rest of the document's HTML and image files using relative HREFs.

Comment=Description
The Comment field provides a description of the item. It can also appear many times in the file with localization codes as for the Name field.

X-COL-weight=decimal number
Provides a relative weight to an item indicating where it should appear in its list. Larger weight numbers appear lower on the list (they sink). Items with identical weights in the same list are sorted alphabetically within that value. Items without weights appear after all items with weight values. The use of decimal values permits inserting new entries between existing entries to any degree necessary.

X-COL-rewrite=crossref_name
Use this option when trying to map more than one .desktop to the same directory. This optional field lets you assign a crossref_name to your document. This is the name used in URLs that refer to the document. If not specified, then the prefix of the .desktop file is used.
In addition to the above fields, a .directory metadata file that identifies a category can have the following fields:

X-COL-Type=[group|category]
A directory of type group contains a tightly coupled group of documents, while a directory of type category contains documents fitting into a more general category. See below for processing differences.

X-COL-IntroURI=pathname
Location of text content to be displayed when the category list is displayed.

Document example

This example metadata file OSAdminG.desktop adds a link to the table of contents of the ``System Administration Guide''.

   [Desktop Entry]
   Name=System Administration Guide
   DocPath=/usr/share/doc/OpenServer/en/OSAdminG/CONTENTS.html
   X-COL-Weight=1

The metadata file is installed by its package at /usr/share/meta/doc/OSdoc/OSAdminG.desktop. The post export installation script configures it into the system using this command:

   /usr/bin/doctool --add  OSdoc/OSAdminG.desktop

To remove the file, execute this command in the pre uninstall removal script:

   /usr/bin/doctool --remove OSdoc/OSAdminG.desktop

Directory example

This example metadata file .directory (note the leading dot) adds a group heading Apache Documentation to the main home page.

   [Desktop Entry]
   Name=Apache Documentation
   Type=group
   X-COL-Weight=10

The metadata file is installed by its package at /usr/share/meta/doc/ApacheDoc/.directory. The post export installation script configures it into the system using this command:

   /usr/bin/doctool --add ApacheDoc/.directory

Documents that are to appear under this new group should install their metadata file under /usr/share/doc/meta/ApacheDoc to be included in that group.

To remove the file, execute this command in the pre uninstall removal script:

   /usr/bin/doctool --remove ApacheDoc/.directory