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:

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''.