[Inso Home Page] [Home] [Collection] [Book] [Expand] [Collapse] [Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] [Preferences] [Print] [Help]

 inside  Expand Search


 3. Overview of DynaWeb Configuration Files   [Table of Contents]  5. Modifying The DynaWeb Interface

DynaWeb Publishers Guide

[-] 4. Managing DynaWeb Collections

4. Managing DynaWeb Collections

Introduction to DynaWeb Collections

DynaWeb collections are valid DynaText collections that typically contain a dynaweb.wv stylesheet in their styles directory and are identified as a servable collection in DynaWeb's collects.dwc configuration file.

The collects.dwc Configuration File

The collects.dwc file lists the collections available to the DynaWeb server module. The collects.dwc file supplied with the DynaWeb server module looks like this:

## Comments Omitted ##
  dwCollectionList {
    dwebdoc    dwCollection
  }
  dwCollection dwebdoc {
    title      "DynaWeb Documentation"
    location   /dynaweb/ebt_books/dwebdoc
    type       EbtCollection   
  } 

Note: Always use forward slashes when indicating a directory or file path, even on DOS and Windows platforms. The proper substitutions will be made automatically by DynaWeb.

Adding Collections to the DynaWeb Server Module

Introduction

In order for the DynaWeb Server Module to recognize the DynaText collection you want to serve, you must specify it in the collects.dwc configuration file.

The dwCollectionList Command

Summary

The dwCollectionList command lists the collections that will be served out by DynaWeb.

Syntax

dwCollectionList {
  collection_alias    collection_location
  collection_alias    collection_location
}

Parameters

dwCollectionList takes a list of name-value pairings: collection_alias and collection_location.

collection_alias

collection_alias is an alias for the collection. It will appear in the URL of any requests for that collection. The value of collection_alias cannot contain spaces, and as a result is limited to one word. Typically, you might use the directory name of the collection as the collection_alias. For example, a collection of sample books in the /pro/collections/sampdoc directory might be listed in the dwCollectionList command as:

dwCollectionList {
    sampdoc     /pro/collections/sampdoc
}

collection-location

The collection_location parameter can have one of three values:

a collection filepath
List the absolute path to the collection.
mycoll /pro/dynaweb/collections/mycollection
a configuration file filepath
You can also point to other configuration files using the dwCollectionList command. Merely fill in the path to the configuration file you want DynaWeb to look in. Configuration files that are referenced through other configuration files are called nested configuration files.
mycoll /pro/dynaweb/collections/mycollection.dwc
dwCollection
A value of dwCollection means that the collection has to be further defined (with a dwCollection command). This is the most common value for collection_location, since the dwCollection command is the only place where the collection may be given a title. For more information on collection titles and the dwCollection command, see the section entitled "The dwCollection Command."
mycoll dwCollection

The dwCollection Command

Summary

If you need to provide additional information about a specific collection, use a dwCollection command.

Any collection whose location is specified in the dwCollectionList command as a dwCollection must be further defined using the dwCollection command. The syntax of the dwCollection command is described in the next section.

Syntax

dwCollection collection_alias {
   title          "Title Of Collection"
   location       /absolute/path/to/collection
   type           collection_type
   encoding       collection_encoding 
}

The value of collection_alias must be the same as the value of the collection_alias parameter from the original dwCollectionList command.

Parameters

dwCollection takes four parameters; title, location, type, and encoding. The only parameter that is required is location - the others are optional.

Title

The title parameter allows the publisher to specify a name that is displayed when the collection title is requested. The title parameter is not limited to one word, and may be omitted if desired. The title must be surrounded by quotation marks. If a title is not specified, then the value of collection_alias in the dwCollectionList command is used in its place.

Location

The location parameter defines the location of the target in the collection directory structure.

The value of the location parameter must be the absolute path to the collection or configuration file.

Example:

location    /usr/local/collections/mybooks

The path should end with the name of the collection directory.

If the dwCollection command is pointing to a configuration file, the path should end with the name of the configuration file.

Example:

location    /usr/local/collections/dynaweb.dwc

Nested configuration files are often used to group DynaText collections under a common identifier.

For more information on the purpose and contents of a nested configuration file, please see the "Grouping Collections In DynaWeb" section later in this chapter.

Type

The type parameter allows publishers to distinguish between the two types of targets for the dwCollection parameter. Currently, the type can be only one of two values, either an EbtCollection or a DwConfigFile. An EbtCollection is a valid DynaText collection. A DwConfigFile identifies the target as a configuration file.

Encoding

The encoding parameter is used for nested collections. It specifies the encoding of the .dwc file pointed to by the dwCollection parameter. It must be a valid encoding as specified by the pls.map file in the data directory of your installation.

Grouping Collections in DynaWeb

Introduction

DynaWeb allows publishers to group their collections through the use of nested configuration files. This is useful for setting up collections to easily share a common layout or functionality of the server. You can group collections under a common heading by adding a collection to the dwCollectionList that points to another configuration file instead of an actual collection. This secondary configuration file (referred to as a nested configuration file) contains its own dwCollectionList command. This dwCollectionList command specifies the names and locations of the collections that will be listed as members of the group.

Collections may belong to more than one group. In this manner, a single source book may have different routes of access that result in a different display or organization, depending on the configuration files accessed by the request. This will be explained in more detail later in this chapter.

Example of Nested Configuration Files

Here is a hypothetical example to explain the idea behind nested collections.

You have a group of DynaText collections that will be accessed by both children and adults. You decide that you want some of your collections in a "Adults" section and the other books in a "Children" section. You also have some collections that you want to display in both sections.

The Children section will feature books with bright blue backgrounds and a prominent Help button. The Adults section, on the other hand, uses plain white backgrounds; but you want your readers to be able to search the collections for related information.

To accomplish this, you can set up your main configuration files to point users to different configuration files depending on which section they want to view. Each nested configuration file is then modified to add or hide the features each collection should possess. The nested configuration files also determine which collections are viewable. See the illustration below for an overview of this example:

Figure 4-1: Example of Nested Configuration Files

raster

Using Nested Configuration Files

Nested configuration files are files located at different levels of the collection structure. Configuration files that modify the layout or the behavior of the server module only affect collections and books that reside below them in the configuration hierarchy. The main configuration files affect all of the books and collections served by the server module, since they are considered to be at the "top" of the hierarchy.

Configuration File Hierarchy

Configuration files in DynaWeb have their own system of authority. In loose terms, the closer a configuration file is to the book or collection being served, the more control that file exerts. As you advance through the configuration file hierarchy and the power of a configuration file increases, its scope, or range of authority, decreases.

At one end of the scale are the main configuration files. They control the layout and behavior for all of the collections and books served out by DynaWeb. But if a collection or a book has a specific configuration file that has been modified, it will override the main configuration file and set its own behavior. The main configuration files have the greatest scope, but the least authority.

At the other end of the scale are book-level configuration files. Their scope is extremely limited, as they can only affect the specific book they reside in. However, their authority is unmatched, because they are able to override any other configuration files that attempt to modify their behavior.

As DynaWeb constructs a response to a request, it constructs a list of the configuration files it touches during the path to its destination. After the requested information's location is determined, DynaWeb constructs a response by revisiting each configuration file it has placed in the list and determining which ones have authority. The table below shows the general makeup of the configuration files a request might encounter and what the relative authority and scope of those configuration files might be.

Configuration File

Location

Scope

Authority

Main Configuration Files

/data/config directory

All collections and books

Cannot override any other .dwc file.

Nested Configuration Files

no set location

Any collection included in local dwCollectionList command

Can override main .dwc files and any other .dwc files cached before the current one.

Collection-Level Configuration Files

Placed at the level of the books directory inside a collection.

Can modify all books inside collection

Can override any .dwc file except book-level .dwc files.

Book-Level Configuration Files

Placed at the level of the ebt, figures, and index directories inside the book.

Only modifies the book it resides in.

Can override any other configuration file

Creating a Nested Configuration File

Placing Configuration Files

Unattached Configuration Files

Configuration files do not have to be attached to a specific collection or book. You can use a nested configuration file to provide a specific "look and feel", or to restrict searches to a specific subset of collections without actually placing the configuration file with the collection(s). By using absolute paths when referring to the configuration file and the nested collections, the nested configuration file does not need to reside with the collections it modifies.

Collection-Level

For collection-level configuration files, the file is placed in the collection directory. If you modify any templates or scripts in a collection-level configuration file, the changes will only affect the books contained in the collection. The configuration file can take the name of the collection (i.e., dwebdoc.dwc) or can remain dynaweb.dwc.

Book-Level

When placing a configuration file in a book, the file is placed inside the book's directory, at the same level as the ebt, figures, and index directories. Unlike collection-level configuration files, the name of the file must be dynaweb.dwc.

Configuration files placed at the book level only affect the book. The contents of the book-level configuration file override any other configuration files.

Referencing a Nested Configuration File

Nested configuration files are registered with the server module by including them in a dwCollectionList command in the main configuration file. The dwCollection command's location parameter for the nested configuration file needs to end with the name of the configuration file. The type parameter, if included, must have a value of DwConfigFile.

Example:

dwCollection group1 {
   title          "Medical Collections"
   location       /pro/dynaweb/collections/medical.dwc
   type           DwConfigFile
}

Enabling Collection Level Search Forms

DynaWeb already enables search forms at the book level automatically by picking up the existence of a search form (*.qrs file) and enabling the Search Forms button on the button bar. Now you can enable search forms at the collection level or even the root level by modifying the configuration files. Once you enable search forms at a certain level, all levels below that level inherit the search form. Placing a search form at the root level, for example, would apply that search form to all of the collections on the server.

Adding Search Forms at the Root Level

To enable the search forms at the root level, simply place the following line in the dynaweb.dwc file in the /data/config directory of your server.

dwSetParam QueryForms [filename]

Replace [filename] with the path to a search forms file you wish to use for the collection. So, to use a search form from the Client Guide, for example, the line would look like this:

dwSetParam QueryForms /server/path/client/books/client/client.qrs

Adding Search Forms at the Collection Level

If you are serving collections with different DTDs, you may want to specify each collection's search forms individually. To do this, you must place the search form at the collection level (the directory containing the booklist.txt file) and name it dynaweb.qrs. DynaWeb will then activate the search forms button in the button bar when displaying that collection.

Adding Search Forms to Nested Collections

To enable the search forms for a nested collection, simply place the following line in the collection's .dwc file.

dwSetParam QueryForms [filename]

Replace [filename] with the path to a search forms file you wish to use for the collection. So, to use a search form from the Client Guide, for example, the line would look like this:

dwSetParam QueryForms /server/path/client/books/client/client.qrs

Caution

When implementing search forms at a high level, such as the Root level, remember that not all of your books may share the same DTD. Books and collections that use different DTD could return hits that you weren't expecting. For example, you have a search form that searches for words in a title element. You know that you will return hits from the titles in your books. However, if one collection uses the <title> tag to represent something different, such as a book's title in a bibliography, you may get hits that you weren't intending on using.

The Collection Manager

DynaWeb 4.1 includes a new administrative tool called the Collection Manager. This tool allows publishers to manage their booklist.txt files through a user interface. The Collection Manager allows publishers to update their booklist.txt files by adding books to and deleting books from existing collections, modifying indexing behavior, and modifying the attributes of existing books. The Collection Manager also provides the publisher with a method for updating the server to include the newly added and modified books. A set of new Tcl commands has been added to implement the Collection Manager's functionality. However, no knowledge of the Tcl commands is required to use the Collection Manager. This section provides a basic overview of the capabilities of the Collection Manager.

Accessing the Collection Manager

The Collection Manager is an administrative tool and as such is not reachable through the button bar. The Collection Manager can be accessed through the following URL:

scheme://server:port/dynaweb/@Generic__CMView

In addition, the Collection Manager takes advantage of basic HTTP authentication to restrict access to itself.

Note: You must enable authentication in order for the Collection Manager's access restriction to work. In addition, you must have write access to the booklist.txt file and its directory.

See the "Setting Authentication on the DynaWeb Internet Server" section for instructions on how to enable authentication for your server. For instructions on enabling authentication for supported web servers, consult the appropriate server documentation.

Using the Collection Manager

There are three sections to the Collection Manager, corresponding to three sections of the booklist.txt file. The three sections are the Collection Definitions, the Group Definitions, and the Book Definitions. Each section allows you to modify the settings for the appropriate tags in the booklist.txt file. Note that you cannot modify group definitions.

The Collection Manager shows a list of the available collections in the TOC pane. When one of the collections is selected, the information contained in that collection's booklist.txt file is accessed and displayed in the Content pane using HTML forms. This allows the information in the booklist.txt file to be modified to suit the publisher's needs. Once all of the necessary changes have been made, you can activate the Update Server button to save your changes and make the changes visible to someone accessing the server. To cancel all changes, reload the browser page (do not select the Update Server button before reloading the browser page).

The following sections detail the changes you can make to your booklist.txt file.

Collection Element Definitions

The first section deals with the <COLLECTION> tag inside the booklist.txt file. You can modify two attributes, Sorted and Validation.

Sorted

The Sorted attribute determines whether the books in the collection are shown in alphabetical order or not. If Sorted is set to "false", the books appear in the order they are listed in the booklist.txt file. When set to "true" the books appear in alphabetical order in the Content pane.

Validation

The Validation attribute determines whether the books in a collection are checked for validity when the collection is accessed in the Collection pane. Setting Validation to "off" can speed up book access time.

Group Element Definitions

You cannot modify the Group Element Definitions section using the Collection Manager, but the publisher can see what groups are available in the file and what tag definitions are applied to each group. To add a book to one of the groups, modify the Group setting in the Book Attributes Definitions section.

Groups

The Group tag allows a set of books in a collection to share common indexing options. For example, you can take all of your title-bearing elements (LABEL, TITLE, TOPIC, etc.) and group them all under a single tag called <TITLES>. This provides a shorthand methods for typing in long, involved queries. Using the example stated in the last sentence, the following queries would be identical in their results:

browser inside (<label> or <title> or <topic>)
browser inside <titles>

Indices

The Index entries show the details of the specified group. The list shows the tags included in the group, while the details on the right show the tag name and what common name it is being indexed under.

Book Element Definitions

This section details all of the attributes assigned to your books in the booklist.txt file. You can modify any of the fields available in this section, although you should act with caution while doing so. An error can cause a book to be hidden or removed from the booklist.txt file.

List of Books

The books listed in the booklist.txt file are listed here in the order in which they appear in the file. Selecting a book from this field brings up the associated information into the fields on the right hand side.

Name

The name field is the string DynaWeb uses to find the book directory inside the collection. Warning: Changing the name of the book will cause the book to no longer be found in the collection. You will receive error messages when you try to access the book through the collection unless you change the name of the book directory in the collection and the files in the ebt directory that share the name of the book (*.edr, *.dat, *.tag) to reflect the new name you have entered in the Name field.

Alias

The Alias field contains the name shown in the TOC pane when the collection is accessed.

Version

The Version field allows you to specify a version for the current book. This version appears after the book name in the TOC pane.

Edition

The Edition field shows the date the book was built last. DynaWeb does not display this information. This field should not be modified, since mkbook automatically updates it when the book is built. The date is in the form YYYYMMDD.

Colldir

The Colldir attribute allows the publisher to display books from a separate collection as part of the current collection. For example, if you wished to include a user manual named "userman" from a collection in /pro/user/manuals, you would enter the book name into the Name field, and in the Colldir field you would enter: /pro/user/manuals. The next time you accessed the current collection, the book "userman" would be listed as though it resided in the current collection.

Type

The Type field determines how the DynaWeb book engine will attempt to parse the book. Accepted values are "Adi2xDocument", for books that were created with the 2.3 version of mkbook, "Adi3xDocument" for books created with the 3.0 and later versions of mkbook, and "AdiRamDocument" for books that will be opened as RAM books.

Group

If you want the indexing definitions defined for one of the groups listed in the Group Element Definitions section to apply to a book, the book must belong to the group. Select the name of the group to which you want the book to belong.

Hide

Setting the Hide attribute to "true" will hide the book in the collection list.

Add Book/Delete Book

Selecting the Add Book button opens a new definition in the list of books. You can then modify the attributes for the new book to correspond to the book you wish to add to the collection.

Selecting the Delete Book button causes the currently selected book to be removed from the booklist.txt file. This operation cannot be undone (although reloading the frame undoes all changes).

Index (book-level)

This area allows you to specify book-specific index tags. For example, one specific book might have a title called <WARNING>, which you want to be returned on searches for the tag grouping "titles". Using the Collection Manager, you can select the book you want the new definition to apply to and enter <WARNING> into the Tag field and "titles" into the Under field. Selecting Add Index will add the new definition to the list of definitions for that book.

Existing definitions are listed in the Index field. Selecting an existing index definition will display the values in the Tag and Under fields.

Updating the Server

Once you make changes to the collection data, you may select the Update DynaWeb Server button. Activating this button causes the booklist.txt file to be backed up to booklist.txt.bak; a new booklist.txt file to be written, and the collection and book caches are cleared from the server. This means that subsequent accesses to the server will see the new settings in the booklist.txt file.

You need to set permissions appropriately on the web server for the collection directory; otherwise, the booklist.txt file will not be backed up nor will a new one be created. If the web server is running as "nobody," then you need to set world write rights for the directory.

Note: If someone is accessing the server at the moment of update, they might encounter unpredictable behavior, especially if they are trying to access a book that was removed.

A Caution about Indices

The Collection Manager allows publishers to modify their booklist.txt files to include new functionality and modifications to the indexing structure of their books. Althought these changes are saved when the Update DynaWeb Server button is used, the index settings will not be reflected in the search results until you run mkcolidx on the new booklist.txt and generate a new collection-level index.

Internationalization

Supported Encodings

Currently, DynaWeb supports the detection of the following encodings:

Encoding

Explanation

ASCII

Pure 7-bit ASCII

IDENTITY

8-bit characters

SHIFT-JIS

Japanese

EUC-JP

Japanese EUC

EUC-GB

Chinese EUC

EUC-KR

Korean EUC

EUC-TW

Taiwanese EUC

BIG 5

BIG 5

KOREAN JOHAB

Korean JOHAB

ISO 2022-JP

Japanese Internet variant

ISO 2022-KR

Korean Internet variant

ISO-2022

7-bit ISO 2022

UTF-8

8-bit encoding of UNICODE

UTF-7

7-bit encoding of UNICODE

UTF-16

16-bit encoding of UNICODE

NEC Variant

NEC variant of encoding

MAC Variant

MAC variant of encoding

In addition, DynaWeb supports the conversion of ASCII, SHIFT-JIS, EUC-JP, and UTF-8 into UNICODE.


   Printing From DynaWeb   [Table of Contents]  5. Modifying The DynaWeb Interface