[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
General Programming Concepts: Writing and Debugging Programs

Calling the Documentation Library Service From Your Documentation

Note: If you are creating documentation that will only be used with AIX Version 4.3 through AIX Version 4.3.2 of the Documentation Library Service, you only need to follow the instructions in Section A. If you are creating documentation that will only be used with AIX Version 4.3.3 and later versions of the Documentation Library Service, you only need to follow the instructions in Section B.
  1. Section A: Calling the Documentation Library Service From Your Documentation (for AIX Version 4.3, AIX Version 4.3.1 and AIX Version 4.3.2)
    1. Search Methods
    2. Custom Search Forms
    3. The Parameters Method for Calling a Custom Search Form
    4. The Configuration File Method for Calling a Custom Search Form
      1. Creating Configuration Files that Call Search Forms in Different Languages
      2. Search Form Techniques
        1. Generic Search Form Technique
        2. Custom Search Form Technique
      3. Create a Configuration File
      4. Insert Search Links into your Documents
  2. Section B: Calling the Documentation Library Service From Your Documentation (for AIX Version 4.3.3 and later)
    1. Navigation Strategies
    2. Creating a Custom View Set
  3. Section C: Calling the Documentation Library Service From Your Documentation (for all versions)

Section A: Calling the Documentation Library Service From Your Documentation
(for versions AIX Version 4.3, AIX Version 4.3.1 and AIX Version 4.3.2)

Search Methods

There are two different ways to search documents:

  1. Search all registered indexes on a system for a given language.

    By default, all registered indexes (compressed copies of document volumes) for a given language will appear in the Documentation Library Service global search form. This form is found by clicking on the Documentation Search Service icon in the CDE desktop Help subpanel. When users do a search using this form, all registered indexes for a given language are available for a search.

  2. Only search the documents for a single application.

    You can provide "Search" links within your GUI or HTML documents that will launch a search form that only shows on and searches in your documents. These search forms will be accessed via an application's help menu (Search Help) or from links in their documentation pages, Search links. For example, The AIX Base Library includes a "Search" link in the header at the top of each page in their documents. Another example is Web-based System Manager, which includes a search link in its Extended Help document pages. The form that is launched from this link searches only Web-based System Manager help documents.

You call a search form by calling the ds_form CGI program that is installed in the web server cgi-bin directory on the documentation server. If you call this program without specifying any parameters, it will, by default, return the generic global search form. This form shows all registered indexes written in the server's default language.

Most likely, you want users to search your specific documents, instead of doing a global search. If so, you should include in the link command the parameters that tell the search service to create a custom search form that only searches your documents. You can also change other elements of the form such as the title and text at the top of the search form, graphics, and almost any other HTML element of a page. You can also change the appearance of the results page.

Custom Search Forms

There are two different ways to specify a custom search form:

  1. Parameters Method
    Include parameters in the launch link command that list the custom elements of your form. The parameter technique is simplest if you just want to use the generic form and specify a few index names.

  2. Configuration File Method
    Include in the launch link just the name of a configuration file. The search service will read the contents of this file to get the custom elements for your search form. The configuration file technique is better if you want to make a custom form or have a lot of index names to specify.

Note: If you plan to produce translated versions of your search forms and you want a custom title for your search form, we suggest that you use the configuration file method instead of using a title parameter method. The title parameter is part of a call to a CGI program. The CGI standards limit the character codes that can be passed to a CGI program. For title text that is inside a configuration file you can use any character codes that your browser can display. This should make translation of the search form title easier.

The Parameters Method for Calling a Custom Search Form

To include parameters in the HTML link, after the URL of the search form CGI add a question-mark (?) followed by an ampersand (&) separated list of parameters and their corresponding values:

<A HREF="/cgi-bin/ds_form?parameter1=value&parameter2=value&...">Search</A>

Parameters you can include in the link command to customize your form:

Parameter Description and Example
columns Tells the search form CGI how many indexes to display on each line of the search form page. The default value is three.

Example: If you want the search form to contain four columns of indexes, you might insert the following link in your HTML document:

<A HREF="/cgi-bin/ds_form?columns=4">Search</A>
config Instead of including parameters in your HTML link that customize your search form, you can just specify the name of a configuration file (config=filename.lang) that contains your customization information. The configuration file technique is better if you are doing a lot of customization that would require a long parameters list.

Example: To call a configuration file named /usr/docsearch/config/calculator/calculator.en you would use the following link:

<A HREF="/cgi-bin/ds_form?config=/usr/docsearch/config/calculator/calculator.en">Search</A>

See The Configuration File Method for Calling a Custom Search Form for details on how to use a configuration file.

indexes Instructs the search form CGI which indexes to display for selection.

When you give a list of indexes to display the search form will contain only those indexes that are in the list and can be found on that documentation server. Any index specified that is not found on the documentation server will not be displayed.

Example: If you want the generic search form, and you have two indexes called Book1Sen and Book2Sen that you want to be searched, you might insert the following link in your HTML document:

<A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen">Search</A>

This will create a link called Search in your documents. When this link is clicked, it will open a generic search form with only the two indexes Book1Sen and Book2Sen available for searching if they exist.

  • If you want the search form to display an index you specified even when it is not found or is in error, put the characters %2B in front of the index name in the HTML link.
    Example: If you want the search form to display the indexes Book1Sen and Book2Sen regardless of whether or not they can be found on the documentation server, you might insert the following link in your HTML document:
    <A HREF="/cgi-bin/ds_form?indexes=%2BBook1Sen,%2BBook2Sen">Search</A>
  • If you want the search form to prevent a specific index from being displayed and selectable for searching, you can put a minus (-) in front of the index name in the HTML link.
    Example: If you want the search form to display all of the indexes except the indexes Book1Sen and Book2Sen, you might insert the following link in your HTML document:
    <A HREF="/cgi-bin/ds_form?indexes=-Book1Sen,-Book2Sen">Search</A>
  • If you want the Documentation Library Service to automatically fill in the language suffixes for the indexes you named, you can replace the language suffix with TWO underscore characters (__). The search service will automatically replace these two underscores with the correct suffix for the language that is being used when the search for is being called.
    Example: If you want the search form to display the two indexes Book1S and Book2S, and you want the Documentation Library Service to automatically fill in the language suffices, you would insert the following link in your HTML document:
    <A HREF="/cgi-bin/ds_form?indexes=Book1S__,Book2S__">Search</A>
lang Instructs the search form CGI in which language to display the search form. See the Language Support Table for more information on possible values for the lang parameter.

If you have created indexes for translated versions of your documents in the Search link in those documents, you must call a search form that is displayed in the same language as the translated documents. This is required so that the readers of that language will be able to understand the search form labels and buttons. It is also required so that the language(codeset) of the user-entered searched terms and the documents match. If they mismatch erroneous results may occur.

To call a search form in a specific language, you must include a lang=locale parameter in the HTML link that calls the search form.

If you include index names as parameters (indexes=), you must specify the language of each index. There are two ways you can specify the language of the index.

  1. Make the last two characters of the index name specify the language that is inside the index. For example, if an index is Spanish (es), you might name it index_namees.

  2. Make the last two characters of the index name TWO underscores (__). The language suffix will then be automatically be filled in using the value specified in the lang=locale parameter. For example, if lang=es_ES (Spanish) and you have two indexes named index_nameA__ and index_nameB__ ,the two underscores will automatically be replaced with es when the search form is built.

    This technique is valuable if you are translating the same indexes into many different languages. You can then just copy the same HTML search link statement into the all the different language versions of your documents. Within the different translations, you only need to change the value of the lang parameter, and not the index names.

Example: Assume your documents are written in German. You want to call a German search form and you want to have two German indexes (cal413de,cal567de) displayed for search. You could insert the following search (Suche) link in your German HTML documents:

<A HREF="/cgi-bin/ds_form?/lang=de_DE&indexes=cal413de,cal567de">Suche</A>

Or, if you're using the underscore method, the link would look like this:

<A HREF="/cgi-bin/ds_form?/lang=de_DE&indexes=cal413__,cal567__">Suche</A>
results_title Instructs the search form CGI what to display as the title of the search results page.

Example: If you want the title of the results page to be Results of My Search, you might insert the following link in your HTML document:

<A HREF="/cgi-bin/ds_form?results_title=Results+of+My+Search">Search</A>
Note: All spaces in the title must be replaced with pluses (+).
title Instructs the search form CGI what to display as the title of the search form page.

Example: If you want the title of the search form to be Search My Documents, you might insert the following link in your HTML document:

<A HREF="/cgi-bin/ds_form?title=Search+My+Documents">Search</A>
Note: All spaces in the title must be replaced with pluses (+).

The Configuration File Method for Calling a Custom Search Form

This is the recommended method if you want a custom search form or have more than a few indexes you want to search.

Note :With the exception of the indexes configuration file entry, a parameter will supersede any configuration file entry of the same name.

Instead of listing a long list of customization parameters in the HTML link that calls your search form, you can create a configuration file and insert all of your customization information inside that file. Then in your link you just include the name of the configuration file as the parameter config=filename.lang where lang is the two letter specification of the language you want to the search form to display. Use the same language suffixes that are used when you specify the language in an index name. For example if you want the configuration file to call an English search form name the file filename.en. Language suffixes are listed in the Language Support Table.

Creating Configuration Files that Call Search Forms in Different Languages

If you have created indexes for translated versions of your documents, in the Search link in those documents, you must call a search form that is displayed in the same language as the translated documents. This is required so that the readers of that language will be able to understand the search form labels and buttons. It is also required so that the the language(codeset) of the user-entered searched terms and the documents match. If they mismatch erroneous results may occur.

If a lang= parameter is also specified in the HTML link that calls the search form, that parameter will supersede a language suffix in a configuration file name.

Search Form Techniques

There are two techniques for using configuration files to specify the language of a search form and the search form's indexes.

Use the Generic Search Form Technique if you just want the generic search form and do not need a custom title or text in the form.

Use the Custom Search Form Technique if you want to create a customized search form that contains a custom title or text.

Create a configuration file

Create a configuration file that contains the custom elements for our search form. If the Documentation Library Service is installed on your computer, a sample configuration file can be found in /usr/docsearch/sample.cfg.

There are two types of configuration file entries, and there are two formats for configurations that can be set in a configuration file:

  1. Configuration file entries of the type:

    parameter=value

    Parameter Description and Example
    columns Tells the search form CGI how many indexes to display on each line of the search form page. The default value is three.

    Example: If you want the search form to contain four columns of indexes, you might insert the following in your configuration file:

    columns=4

    If a columns parameter is also specified in the HTML link, the parameter will supersede the columns configuration file entry.

    indexes Instructs the search form CGI which indexes to display for selection.

    • When you give a list of indexes to display the search form will contain only those indexes that are in the list and can be found on that documentation server. Any index specified that is not found on the documentation server will not be displayed.

      Example: If you want the search form to display only the indexes Book1Sen and Book2Sen, you might insert the following in your configuration file:

      indexes=Book1Sen,Book2Sen
    • If you want the search form to display an index you specified even when it is not found or is in error, put a plus (+) in front of the index name in the configuration file.

      Example: If you want the search form to display the indexes Book1Sen and Book2Sen regardless of whether or not they can be found on the documentation server, you might insert the following in your configuration file:

      indexes=+Book1Sen,+Book2Sen
    • If you want the search form to prevent a specific index from being displayed and selectable for searching, you can put a minus (-) in front of the index name in the configuration file.

      Example: If you want the search form to display all of the indexes except the indexes Book1Sen and Book2Sen you might insert the following in your configuration file:

      indexes=-Book1Sen,-Book2Sen
    • The data from an indexes parameter specified in the HTML link is cumulative with the data in the indexes configuration file entry.

      Example: If the HTML link is:

      <A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen&config=/tmp/config.cfg">Search</A>

      and the configuration file /tmp/config.cfg contains the line:

      indexes=Book3Sen,Book4Sen
      The search form will display Book1Sen, Book2Sen, Book3Sen and Book4Sen.

    • The data from an indexes parameter specified in the HTML link will override the data in the indexes configuration file entry.

      Example: If the HTML link is:

      <A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen&config=/tmp/config.cfg">Search</A>

      and the configuration file contains the line:

      indexes=-Book2Sen
      The search form will display both Book1Sen and Book2Sen.

    lang Instructs the search form CGI in what language to display the search form.

    Example: If you want the search page to be displayed in German, insert the following line in the configuration file:

       lang=de_DE

    Any locale supported by the Documentation Library Service can be specified by inserting a lang=locale file entry in the configuration file. See the Language Support Table for more information on possible values for the lang parameter.

    Note: Only one value for lang can be specified at a time. Do not include more than one lang entry in a configuration file. The language suffix of any index name specified in an indexes= entry, must match the language specified in the lang= entry or the indexes will not be shown on the Search Form.
    results_title Instructs the search form CGI what to display as the title of the search results page.

    Example: If you want the title of the results page to be Results of My Search, you might insert the following in your configuration file:

    results_title=Results of My Search
    If a results_title parameter is also specified in the HTML link, the parameter will supersede the results_title configuration file entry.
    Note: The results_title parameter will be ignored if a results_top configuration file entry is given.
    search_page Redirects the web browser to another URL without changing the HTML link in the document.

    Example: If you had a configuration file for users wanting to search your documentation, but now want them to search the documentation at some remote site instead, you might change the contents of your configuration file to:

    search_page=http://my.other.site/mypath/mypage.html
    Note: Specifying a search_page configuration will cause all other settings to be ignored.
    title Instructs the search form CGI what to display as the title of the search form page.

    Example: If you want the title of the search form to be Search My Documents, you might insert the following in your configuration file:

    title=Search My Documents
    If a title parameter is also specified in the HTML link, the parameter will supersede any title configuration file entry.

    Note: The title configuration will be ignored if the search_top configuration is given.

  2. Configuration file entries of the type:

    configuration_begin
    your HTML code
    configuration_end

    Notice that all of these configurations have _begin appended to their name to indicate the start of the HTML code fragment, and _end appended to their name to indicate the end of the HTML code fragment.

    Parameter Description and Example
    search_top Replaces the default HTML header of the search form page with the HTML code between the search_top_begin and search_top_end tags.

    Example: If you want the top of your search form page to contain an image named myimage.gif which is in the web server's /images directory, and the title of your search form page to be Search My Documents, you might insert the following in your configuration file:

    search_top_begin
    <HTML>
    <HEAD>
    <TITLE>Search My Documents</TITLE>
    <BODY>
    <DIV ALIGN="CENTER">
    <IMG SRC="/images/myimage.gif">
    </DIV>
    <P>
    search_top_end
    Note : Any title parameter or title configuration file entry specified will be ignored.
    search_bottom Replaces the default HTML footer of the search form page with the HTML code between the search_bottom_begin and search_bottom_end tags.

    Example: If you want the bottom of the search form page to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file:

    search_bottom_begin
    <HR>
    <P>
    <DIV ALIGN="CENTER">
    <A HREF="MAILTO:me@my.site">Feedback</A>
    </DIV>
    </BODY>
    </HTML>
    search_bottom_end
    results_top Replaces the default HTML header of the results page with the HTML code between the results_top_begin and results_top_end tags.

    Example: If you want the top of your results page to contain an image named myimage.gif which is in the web server's images directory, and the title of your results page to be Results of My Search, you might insert the following in your configuration file:

    results_top_begin
    <HTML>
    <HEAD>
    <TITLE>Results of My Search</TITLE>
    <BODY>
    <DIV ALIGN="CENTER">
    <IMG SRC="/images/myimage.gif">
    </DIV>
    <P>
    results_top_end
    Note: Any results_title parameter or results_title configuration file entry specified will be ignored.
    results_bottom Replaces the default HTML footer of the results page with the HTML code between the results_bottom_begin and results_bottom_end tags.

    Example: If you want the bottom of the results page to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file:

    results_bottom_begin
    <HR><P>
    <DIV ALIGN="CENTER">
    <A HREF="MAILTO:me@my.site">Feedback</A>
    </DIV>
    </BODY>
    </HTML>
    results_bottom_end
Insert Search links into your documents

Insert into your documents the Search links that specify a configuration file to generate your custom search form. See the previous section for information on specifying a configuration file in an HTML link.

Section B: Calling the Documentation Library Service From Your Documentation
(for AIX Version 4.3.3 and later)

Navigation Strategies

Users can navigate your documents in two ways:

Creating a Custom View Set

  1. Create a View Set Configuration File
  2. Create a View Definition File
  3. Register the Contents of each of your View Definition Files
  4. Create Links in your Documentation to your Custom View Set
  1. Create a View Set Configuration File

    1. Create a view set directory. This directory is named /usr/docsearch/views/locale/view_set_name where locale is the name of the language locale in which the documentation was written, and view_set_name is a name which uniquely identifies your view set.

    2. Create a view set configuration file named config in the view set directory.

    Example: If your view set is named MyDocuments and you want to create a set of English views, your configuration file should be in the location /usr/docsearch/views/en_US/MyDocuments/config

    Note: Lines in the configuration file beginning with a # are assumed to be comments and are ignored.

    There are many things that can be customized in the view set configuration file:

    Field Description and Examples
    View Name and Label The name of an view and the text to be displayed on the tabs which allow the user to change between different views of a view set. A separate view name is necessary because a view label may be different in other languages. For example, if you have a view named Books which you link to from your documentation, the name of the view will always be Books but in Spanish the label of the view could be Libros.

    view = View_Name <TAB> View Label

    Example: If the name of the view is Tasks, but you want the label on the tab to be How To, you would add the following line to the view set configuration file:

    view = Tasks   How To
    title The text to be displayed at the top of the library GUI and the browser window.

    title = Library GUI Title

    Example: If you want the text at the top of the library GUI to be My Documentation, you would add the following line to the view set configuration file:

    title = My Documentation
    results_title The text to be displayed at the top of the results GUI and the browser window containing the results GUI.

    results_title = Results GUI Title

    Example: If you want the text at the top of the library GUI to be My Documentation Search Results, you would add the following line to the view set configuration file:

    results_title = My Documentation Search Results
    page_top Replaces the default HTML header of the library GUI with the HTML code between the page_top_begin and page_top_end tags.

    Example: If you want the top of your library GUI to contain an image named myimage.gif which is in the web server's /myimages directory, and the title of browser window to be My Documents, you might insert the following in your view set configuration file:

    page_top_begin
    <HTML>
    <HEAD>
    <TITLE>My Documents</TITLE>
    <BODY>
    <DIV ALIGN="CENTER">
    <IMG SRC="/myimages/myimage.gif">
    </DIV>
    <P>
    page_top_end
    Note : If a title configuration file entry is specified, it will be ignored.
    page_bottom Replaces the default HTML footer of the library GUI with the HTML code between the page_bottom_begin and page_bottom_end tags.

    Example: If you want the bottom of the library GUI to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file:

    page_bottom_begin
    <HR>
    <DIV ALIGN="CENTER">
    <A HREF="MAILTO:me@my.site">Feedback</A>
    </DIV>
    </BODY>
    </HTML>
    page_bottom_end
    results_top Replaces the default HTML header of the results GUI with the HTML code between the results_top_begin and results_top_end tags.

    Example: If you want the top of your results page to contain an image named myimage.gif which is in the web server's /myimages directory, and the title of the browser window to be Results of My Search, you might insert the following in your view set configuration file:

    results_top_begin
    <HTML>
    <HEAD>
    <TITLE>Results of My Search</TITLE>
    <BODY>
    <DIV ALIGN="CENTER">
    <IMG SRC="/myimages/myimage.gif">
    </DIV>
    results_top_end
    Note: If a results_title configuration file entry was specified, it will be ignored.
    results_bottom Replaces the default HTML footer of the results GUI with the HTML code between the results_bottom_begin and results_bottom_end tags.

    Example: If you want the bottom of the results page to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file:

    results_bottom_begin
    <HR>
    <DIV ALIGN="CENTER">
    <A HREF="MAILTO:me@my.site">Feedback</A>
    </DIV>
    </BODY>
    </HTML>
    results_bottom_end

  2. Create a View Definition File

    Create a view definition file for each view in your view set. The format of this file is as follows:

    #<TAB>Entry Title[<TAB>Field:Value...]
    #<TAB>Entry Title[<TAB>Field:Value...]
    #<TAB>Entry Title[<TAB>Field:Value...]

    where the # is the level of the entry in the hierarchical tree structure, the entry title is the text to be displayed in the library GUI, and the possible fields are those listed below. The first entry level in a view definition file is always 0 and can increase up to 9 as the depth of the entry increases. Entries with the same level # will be displayed with the same indentation. (You can think of the entry level as the number of times to indent the tree at that entry.)

    Field Description and Examples
    Checked Specifies default search state (selected for search or not selected for search) (This applies only to custom views. You can not specify a default search state for the Global Views.) The value can be either Yes or No. If no Checked field is present for an entry, the default search state is for the entry to be selected for search (i.e. Yes).
    Examples: Checked: Yes
    Checked: No
    Collate Specifies whether to sort the children of this entry (whether entries directly under this entry are to be kept in the order given, or sorted lexicographically according to the locale). The value can be either Yes or No. If no Collate field is present for an entry, the default ordering is the order given (i.e. No).
    Examples: Collate: Yes
    Collate: No
    Expand Specifies whether this node of the tree is expanded or collapsed by default. (This applies only to custom views. You can not specify a default expansion state for the Global Views.) The value can be either Yes or No. If no Expand field is present for an entry, the default expansion state is the for the entry to be collapsed (i.e. No).
    Examples: Expand: Yes
    Expand: No
    Extra Specifies text that is to be displayed after the title, but that should not be a link when a URL is given.

    Example: Extra: Some other text that isn't part of the link

    Icon Specifies the filename of the icon which is to be displayed before the entry's title.

    Following is a list of icon's which are provided by the Documentation Library Service.

    • bookcase.gif
    • bookshelf.gif
    • book.gif
    • chapter.gif
    • paper.gif

    These icons reside in the directory /usr/docsearch/images. If you want to use your own icon, place it in that directory on the documentation server machine. If no Icon field is present for an entry, no icon will be displayed.
    Example: Icon:book.gif

    Note: Icons are assumed to be 24 pixels wide and 24 pixels high. If you use an icon which is larger or smaller than this size, the icon will be resized to 24 by 24.
    Index Name of the search engine index(es) of documents represented by this entry and its descendants. Multiple indexes can be specified by listing them, separated by commas. Once a view definition file specifies an index for an entry, no other view definition files will be able to add entries under that entry. This helps to ensure that the contents of the tree below the index are exactly the documents which were indexed.
    Examples: Index:BSADMNEN
    Index:	CMDS01EN,CMDS02EN,CMDS03EN,
    	CMDS04EN,CMDS05EN,CMDS06EN
    Position Suggested relative position within a container. For example, if you are inserting an article under a book and you want that article to appear as the third article in the book, you could assign it a position number of 3 if there were already articles with positions of 1 and 2. In case of multiple entries with the same position, order will be determined by the value of Collate field. The position of an entry in the view definition file overrides any position field. Therefore, it is not necessary to specify positions for entries below the point at which no other books will be occupying the same space. If no Position field is present for an entry, the default position value is zero (0).

    Example: Position:5

    URL The URL of the document to go to for navigation. This is used to locate the document when a web server is being used. This value must be an absolute path, but must not contain the protocol (http://) or the name or port number of the web server. If no URL is specified, the entry will not be a HTML link when displayed.

    Example: URL:/doc_link/en_US/a_doc_lib/cmds/aixcmds2/grep.htm

    Version The version of this entry. When registering documentation, a higher numbered version on an entry will replace a previous lower version number.

    Example: Version:4.3.2.0

    A portion of an example view definition file is below:

    0       AIX Base Library        Position:1      Icon:bookcase.gif
    1       AIX System Management Guides    Position:1      Icon:bookshelf.gif
    2       Operating System and Devices    Index:BADMNEN   Postion:1       Icon:book.gif
    3       Chapter 1. System Management with AIX   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch1.htm  Icon:chapter.gif
    4       The System Administrator's Objectives   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch1.htm#CE13340208vick
    3       Chapter 2. Starting and Stopping the System     URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch2.htm  Icon:chapter.gif
    4       Starting the System     URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/starting.htm     Icon:paper.gif
    4       Understanding the Boot Process  URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_boot.htm   Icon:paper.gif
    4       Understanding System Boot Processing    URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_sys.htm    Icon:paper.gif
    4       Understanding the Service Boot Process  URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_svc.htm    Icon:paper.gif
    4       Understanding the RAM File System       URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_ram.htm    Icon:paper.gif
    4       Booting an Uninstalled System   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/boot_unin.htm    Icon:paper.gif
    4       Rebooting a Running System      URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/rebooting.htm    Icon:paper.gif
    4       Booting from Hard Disk for Maintenance  URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/boot_hard.htm    Icon:paper.gif
    4       Booting a System That Crashed   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/boot_crash.htm   Icon:paper.gif
    4       Accessing a System That Will Not Boot   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/accessing.htm    Icon:paper.gif
    4       Rebooting a System With Planar Graphics URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/reboot_plan.htm  Icon:paper.gif
    4       Diagnosing Boot Problems        URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/diagnosing.htm   Icon:paper.gif
    4       Creating Boot Images    URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/create_boot.htm  Icon:paper.gif
    4       Identifying System Run Levels   URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/ident_sys.htm    Icon:paper.gif
    4       Changing System Run Levels      URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/change_sys.htm   Icon:paper.gif
    4       Changing the /etc/inittab File  URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/change_init.htm  Icon:paper.gif
    4       Stopping the System     URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/stop_sys.htm     Icon:paper.gif
    4       Understanding the Shutdown Process      URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_shutdown.htm       Icon:paper.gif
    4       Shutting Down the System        URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/shut_down.htm    Icon:paper.gif  Icon:paper.gif
    4       Shutting Down the System to Single-User Mode    URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/shut_single.htm  Icon:paper.gif
    4       Shutting Down the System in an Emergency        URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/emergency_shut.htm       Icon:paper.gif
    3       Chapter 3. Security     URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch3.htm  Icon:chapter.gif
    4       Security Administration URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/security_admin.htm       Icon:paper.gif
            .
            .
            .

  3. Register the Contents of each of your View Definition Files

    /usr/sbin/ds_reg [-d] locale View_Set View view_definition_file

    where locale is the locale (language) in which your documentation is written, View_Set is the name of the view set, View is the name of the view into which you wish to register your documentation, and view_definition_file is the location of the view definition file. The optional -d flag is used to unregister the contents of a registered view definition file.

    Example: If you have a view definition file in /MyDocuments/Books.vdf, and you want to register it into the English Global Books view, you would type the command:

    /usr/sbin/ds_reg en_US Global Books /MyDocuments/Books.vdf
    Example: If you have a view definition file in /MyDocuments/Books.vdf, and you want to unregister it from the English Global Books view, you would type the command:

    /usr/sbin/ds_reg -d en_US Global Books /MyDocuments/Books.vdf
  4. Create Links in your Documentation to your Custom View Set

    The base URL of the Documentation Service CGI program is always /cgi-bin/ds_form. This URL can be modified by any of the following arguments. Multiple arguments are separated by an ampersand (&).

    Argument Description and Example
    lang The locale of the documentation you want to display. If no locale is specified the default locale of the documentation server will be used.

    Example: If you want to see Japanese documentation, your link might be

    <A HREF="/cgi-bin/ds_form?lang=Ja_JP">

    viewset The name of the view set you want to display. If no viewset is specified, the Global view set will be used.

    Example: If your view set is called MyDocuments your link might be

    <A HREF="/cgi-bin/ds_form?viewset=MyDocuments">

    view If no view is specified, the first view in the viewset will be used.

    Example: If you want to see the Commands view of the default (Global) view set, your link might be

    <A HREF="/cgi-bin/ds_form?view=Commands">

    advanced This argument specifies that you want to see the advanced search form. If no advanced argument is given, the simple search form will be displayed.

    Example: If you want to see the advanced version of the library GUI

    <A HREF="/cgi-bin/ds_form?advanced">

    Example: If you want to create a link in your Spanish (es_ES) documentation to the Subroutines view of your Custom View Set MyDocuments, your link could be

    <A HREF="/cgi-bin/ds_form?viewset=MyDocuments&view=Subroutines&lang=es_ES">

Section C: Calling the Documentation Library Service From Your Documentation
(for all versions of AIX)

If your documentation may be viewed under any version of the Documentation Library Service, you should follow both methods of calling the service from your documentation. Any arguments that are specific to one version of the Documentation Library Service will be ignored by other versions.

Example: If you want to create a link in your German (de_DE) documentation that instructs the 4.3.3 version of the Documentation Library Service to use the Books view of your Custom View Set MyDocuments and instructs earlier versions of the Documentation Library Service to use the configuration file

/usr/docsearch/config/MyApplication/MyConfig.de
<A HREF="/cgi-bin/ds_form?lang=de_DE&viewset=MyDocuments&view=Books&config=/usr/docsearch/config/MyApplication/MyConfig.de">

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]