The documentation for your Silicon Graphics systems is available online. Because the documentation is quite extensive, it makes sense to store the online files centrally, rather than replicating the files on each system in the workgroup. The administrator generally sets up and maintains the shared documentation for the work group. You can share documentation throughout your work group by using the IRIS InSight™ system on a DynaWeb™ server. DynaWeb enables you to gain access to the shared documentation by using a browser (for example, Netscape Navigator™).
A DynaWeb server makes IRIS InSight books available to World Wide Web clients. DynaWeb dynamically converts the InSight Standard Generalized Markup Language (SGML) tagged text and graphics into HyperText Markup Language (HTML) form.
This section explains the components of the DynaWeb server including the programs used to administer it, the directory structure of the DynaWeb Server, and the features of the DynaWeb server that give the individual administrator great flexibility configuring the server.
DynaWeb has two major components: a server and an SGML-to-HTML converter.
Like any Web server, a DynaWeb server listens for HTTP requests from clients. Each request contains a URL that identifies the server and a particular block of data such as a home page, a section of text, or an image.
IRIS InSight books are binary files that contain SGML-tagged text and graphics. The SGML-to-HTML converter transforms each request for all or part of an InSight book into an HTML-tagged text stream. If a large block of text is requested, the converter dynamically builds a table of contents (TOC) for the text.
These components work together to handle requests from Web clients.
The server can simultaneously handle up to 256 incoming requests from Web clients. Whenever a Web client requests data from a DynaWeb server, the browser sends an HTTP request to the server specifying the information to be sent. On receiving the request, the server establishes a connection with the client and passes the data request to the DynaWeb SGML-to-HTML converter. The information is transmitted back to the client.
The connections are short lived, lasting only long enough for the server to process the requested data and send it to the client. After sending the requested information, the server terminates its connection.
The DynaWeb directory structure helps to isolate other parts of the filesystem from Web clients. The directory /usr/lib/Insight/dweb/servroot is the highest point in the DynaWeb directory tree that any Web client can access and is called the DynaWeb root directory. The paths of all files accessible to Web clients are defined relative to the DynaWeb root directory. In this way, the root directory helps control the part of the host filesystem that is accessible to Web clients.
Collections of books are added to the DynaWeb directory structure by linking or copying directories to the /usr/lib/Insight/dweb/servroot directory.
A DynaWeb collection is an IRIS InSight bookshelf containing one or more InSight books that a DynaWeb server offers to Web clients. Each collection is a directory in the DynaWeb root directory and each book in a collection is a subdirectory of the collection directory. Collections are added to the DynaWeb root directory in three ways:
Each time the DynaWeb server is started, it creates links (if they don't already exist) from the servroot directory to directories that contain InSight books.
You can create symbolic links from the DynaWeb root directory to a collection directory.
You can copy a collection to the DynaWeb root directory.
InSight book collections are automatically made available to the DynaWeb server by means of symbolic links in the DynaWeb root directory. Using symbolic links in this way simplifies book maintenance and DynaWeb upgrades.
Because the DynaWeb server collects information about available collections and books only when it starts up, changes to the collections and books that happen while the server is running are not displayed to client users. When collections are added, books are added, or books are removed, the DynaWeb server must be restarted so that it displays the available collections and books.
You can limit access to the documentation server by setting up DynaWeb to use HTTP authentication. In that case, users must enter a password to view the available collections and books. For more information, see the IRIS InSight DynaWeb Administrator's Guide.
A home page is an HTML document that welcomes client users to the DynaWeb root directory on the server, introduces your Web site to them, and provides at least one predefined browsing choice for accessing information offered by the server. DynaWeb supplies a default home page, which can be replaced by another home page.
A publisher's page is an optional HTML document that publishers can use for any purpose, such as presenting forms to collect data from client users, or providing a list of other sites of interest. For example, a publisher's page might enable readers to submit evaluations of documents or notes about improvements or upgrades.
DynaWeb supports an access log file and an error log file. By default, the server logs information to both files. However, you can turn off either or both kinds of logging.
You can extract statistics such as the total number of accesses, the number of requests, and the type of information requested.
DynaWeb supports Common Gateway Interface (CGI) scripts. CGI defines an interface that lets your server run scripts. Some sample scripts are supplied with DynaWeb. For additional information, including a complete description of the Common Gateway Interface, refer to http://hoohoo.ncsa.uiuc.edu/cgi/.
This section describes the considerations and overall process of setting up DynaWeb for your work group. For more detailed instructions, see the IRIS InSight DynaWeb Administrator's Guide.
DynaWeb can run either as a CGI script or as a process. If you are concerned about security, you may wish to run DynaWeb as a CGI script piggybacked on another server, utilizing the SGML-to-HTML and organizational capabilities of DynaWeb while retaining the extra security provided by the front-end server.
If you set up DynaWeb to run as a process, it can be set up so that it appears to users as multiple servers. Each “server” can have a different configuration, for example, different collections of books or server pages in different languages. Each configuration is described by a configuration file and is associated with a port number. Users select the configuration they want using hypertext links or by specifying a port number in a URL.
The choices you make in setting up DynaWeb can affect the methods users employ to access books and collections. The following methods can be used regardless of whether you set up DynaWeb to run as a CGI script or as a process:
Create a hypertext link from your home page to the DynaWeb home page.
Specify the URL of the DynaWeb home page or the DynaWeb collections page to your Web browser.
Install the Silicon Graphics What's New product.
If you set up DynaWeb to run as a CGI script, this method can be used to access books and collections:
Specify the URL of the parent server to your Web browser.
Following the initial setup of DynaWeb to run as a CGI script or as a process, follow these steps to make IRIS InSight book collections accessible to your work group:
Set up collections in standard locations
IRIS InSight book collections in the standard locations, /usr/share/Insight/library/*/*, are automatically made available to the DynaWeb server when it starts up. InSight book collections in nonstandard locations and collections of DynaText books can be made available as well.
Optionally, set up collections in non-standard locations.
You can set up collections in non-standard locations and collections of DynaText books in two ways: by using symbolic links or by setting up a collection as a directory. Using symbolic links makes book maintenance and DynaWeb upgrades simpler, but introduce potential security risks, particularly if the linked directory contains additional links.
Optionally, enable HTTP authentication.
When the DynaWeb server is installed, authentication is inactive. To enable user name and password checking, uncomment the line that starts DWEB_PASSWD_FILE = in the configuration file /usr/lib/Insight/dweb/data/config/dynaweb.cfg.tmpl, and add the absolute pathname of the password information file as the value of DWEB_PASSWD_FILE.
Optionally, make other changes to the configuration parameters.
Ordinarily you do not need to change the parameters manually in the configuration file. Several values (such as hostname and server port) are defined during installation. Most other values have defaults. The configuration parameters and the format of the configuration file are detailed in the IRIS InSight DynaWeb Administrator's Guide.
 | Note: Collections you add to DynaWeb and changes you make to the DynaWeb configuration parameters do not take effect until the server is restarted. |
This section lists possible causes and solutions for some problems that you may encounter when administering a DynaWeb server.
You cannot find a DynaWeb directory using the pathname specified in a DynaWeb guide.
A directory pathname without a leading slash indicates that the path is relative to the DynaWeb home (root) directory.
Clients are unexpectedly accessing directories outside of the DynaWeb root directory tree.
Make sure that symbolic links exist only where expected. Web clients can navigate downward within any linked directory. Moreover, if a linked directory is, itself, linked to another directory, Web clients can jump to and move downward from there.
The server does not display your site-specific home page.
The filename of the home page is set by the DWEB_HOMEPAGE configuration parameter. To use a different filename for the home page, you must assign your own filename as the value of DWEB_HOMEPAGE.
The hypertext link to your collections fails to bring up your collection list.
Ensure that the XREF value in the link matches the value of the DWEB_COLLECTMAGIC configuration parameter.
The server cannot find your home page after you change its name in the server configuration file.
Check the file and its pathname.
The values of resource parameters must contain a leading slash (for example, /docs/my-homepage.html). This slash is necessary, because the server appends the value of file parameters to the value of DWEB_ROOTDIR to produce the full directory path.
A client can't access the DynaWeb server.
Make sure the server is responding.
Check the configuration file for errors.
Make sure the file /usr/lib/Insight/dweb/data/config/dynaweb.cfg exists.
A button does not appear on the button bar.
Check the server configuration file to ensure that the button assignment is not disabled (by the insertion of a # at the start of the line). Make sure that the icon file is present in the servroot/icons directory and uses the same name as defined in the server configuration file.
Note: An unavailable icon causes no problem for the server. A client displays a browser-specific icon, instead of the correct server icon.
Make sure the .gif file for the icon exists and is not corrupted.
The server cannot find an icon after you change its name in the configuration file.
Make sure the values of resource parameters contain a leading slash (for example, /icons/button_up.gif).
Users cannot find the button bar.
If the button bar is at the bottom, and the returned information is longer than the document view, users must scroll downward before the button bar appears. In the middle of a block of text, the button bar is out of view (at either the top or bottom of the text).
A bookshelf is missing or a removed bookshelf or book still appears.
Make sure you restarted the DynaWeb server after adding or removing a book or collection.
A user complains that the server is acting weirdly.
Verify whether the user is specifying either of the following parameters in URLs: DWEB_NAVHINTS or DWEB_REDIRECT. The server uses these parameters to pass state information to itself. Setting them in a URL causes the server to behave in unpredictable ways.
After you supply your ID and password and they have been validated by the server, when you switch books, collections, or other documents, you are again prompted for your information.
Make sure all URLs match the DWEB_HOST parameter. Otherwise the server thinks you are not authenticated and tries to validate you again. This will happen every time you link to a URL that contains a different hostname. For example, mycomputer:88 does not match mycomputer.mycompany.com:88.