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 executes the installation for all the doc presentation systems. 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
  

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.

• In addition to the above fields, a .directory metadata file that identifies a category can have the following fields:

  
  X-COL-Type=[group|catagory]

  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/UnixWare/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

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