Users can navigate your documents in two ways:
To enable users to navigate and search your documentation in the Global view set, you must:
Note: You may register your documentation into any of the other views of the Global view set. The process is the same for the Books view though a separate view definition file may be required for each view.
If your documentation is in English, the HTML link might be
<A HREF="/cgi-bin/ds_form?lang=en_US">Home/Search</A>
To enable users to navigate and search your documentation separately from all other documentation on the system, you must create a Custom View Set.
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 |
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 |
|---|---|
| Printfile | Beginning in AIX 5.1, this optional VDF tag is used to create a
link to your book in the list of printable books in the Print Tool .
When a user clicks on this link in the Print Tool, the library service will
download a printable file containing your entire book to the user's
browser. In addition to inserting this tag in your VDF, you will need
to create and package the printable book file. For more information on
these tasks, see Making your Documents Printable.
The Printfile tag has the following syntax: Printfile[1-20]:/doc_link/$path This syntax displays the book in the list of printable books in the Print Tool. $path is the path to your printable file. This path must be a sub-directory of the /usr/share/man/info directory. The link doc_link is automatically placed by the library service in the machine's web server document directory. This link points the web server to the /usr/share/man/info directory and allows the web server to find your print file if it is installed under /usr/share/man/info. The number 1-20 is optional. It is used only when your book is too large to be contained in one printable file. You can split your book into as many as 20 different printable files for downloading. The number specifies which section of the book is located in the file defined by the path. A separate link will appear in the list of printable books for each section or Printfile tag for a book. If your book only has one file for downloading, omit the number entry. Examples: Assuming your application is called the Esther tool, and your book is called userguide.pdf, you could use the following tags: If you ship the entire book in one file, in only one language (English), use: Printfile:/doc_link/esther/userguide.pdf If you split the book up into two files for download, use: Printfile1:/doc_link/esther/userguide_section1.pdf Printfile2:/doc_link/esther/userguide_section2.pdf You ship an English version and a Spanish version. The first tag is used in your English VDF and the second is used in your Spanish VDF: Printfile:/doc_link/english/esther/myownbigbook/userguide.pdf Printfile:/doc_link/spanish/esther/myownbigbook/userguide.pdf |
| 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.
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.
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 of the parent entry. 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:library.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
Icon:paper.gif
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
.
.
.
/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/Commands.vdf, and you want to unregister it from the Spanish AIX Commands view, you would type the command:
/usr/sbin/ds_reg -d es_ES AIX Commands /MyDocuments/Commands.vdf
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">