General Programming Concepts: Writing and Debugging Programs

Writing your HTML Documents

Currently, the Documentation Library Service supports searching HTML documents that are written using the languages and codesets listed in the Language Support Table. All documents in a single index must be written using the same language and codeset. Note that even though a document is written in a supported language, it cannot be searched unless it is written using the codeset of characters listed in the table. The last column in the table shows the characters that must be used as the last two characters of the index name for an index that contains that language. For example, if you are going to create an index named doc456 and it is written in Spanish in the 8859-1 codeset, you would name it doc456es.

For more information on codesets and locales see Locale Overview in AIX 5L Version 5.1 System Management Guide: Operating System and Devices.

The Portable ASCII codeset of characters is included inside all other codesets. So you can include Portable ASCII characters in documents in all languages.

If you are creating a document in a codeset other than ISO8859-1, the Netscape browser may have a problem with displaying ampersand encoded characters that are equivalent to characters outside the Portable ASCII characters. These characters will not display correctly. For example, if you are using &copy for the copyright symbol, this is equal to a character value that is not in the Portable ASCII codeset. It may not display properly in any non-ISO8859-1 codeset.

HTML documents must be customized for use with the Documentation Library Service by including Search links in each document that will call the search form. These search links can be placed anywhere in the document. For example, they can be in the body of the text, in a header at the top of each page, in a navigation frame - anywhere where users are able to view them. See the next section for information on how the search link must be written.

Users may be using an ASCII browser to view the documentation. If it is likely that end users will be using an ASCII browser, the HTML documentation should be ASCII user-friendly. This includes techniques such as using an ALT attribute in the <IMG> tag for users unable to view images and <NOFRAMES> tags for users with browsers that are not frames capable. Consult HTML reference material for other techniques.

Insert a title tag in each document. Document titles should be meaningful and unique. The document title will appear in the list of matched documents in the search results page as the title of the found document. The text between the <TITLE> and </TITLE> tags should contain the title of the document and no other HTML tags. Additionally, titles should have a maximum length of 256 bytes.

Making your Documents Printable

Books within the documentation library are structured as a collection of articles or chapters. These articles are loaded into the client web browser one at a time for reading. While this allows great flexibility in navigating through articles, it is difficult to print an entire book in one print action. Beginning in AIX 5.1, the Documentation Library Service contains a Print Tool button. When you clicks this button, list of books that can be downloaded in a single printable file is displayed. You have the option of including your book in this list for printing.

To have your book appear in this list, complete the following:

1. Create a single file that merges all of your book's files into a single file in a printable format. The format you use is up to you. AIX manual print files are in PDF format, but any format can be used.
2. Add the print file to your install package. The print file must be installed to be accessible from the machine's web server's document directory. By default, the /usr/share/man/info directory is always linked under the web server's document directory, therefore, it is recommended that you install the printable file for your book into /usr/share/man/info. For example, if your product is called Esther, and your book's print file is named userguide.pdf, you could install the print file as /usr/share/man/info/esther/userguide.pdf.

   Note:

   If you have different language versions of your book, you will need to ship and install a separate print file for each language. For example, if you have an English and a Spanish version of your book, you might install two printable files as follows: /usr/share/man/info/esther/english/userguide.pdf and /usr/share/man/info/esther/spanish/userguide.pdf

3. In your View Definition File (VDF) , include a Printfile tag on the entry line that defines the book to define the name and location of the file that contains the printable version of the book. The library service uses the path in this tag to create a link to your printable book in the printable books list in the Print Tool. During configuration, the library service automatically creates a link in the machine's web server's documentation directory which points to /usr/share/man/info. This link is named doc_link. Therefore, if you are installing your print file under the /usr/share/man/info directory, you must use the name doc_link instead of /usr/share/man/info as the first part of your path in the Printfile tag. Using our above English-only example, you would include the following tag in the entry line for your book in your VDF: Printfile:/doc_link/esther/userguide.pdf

For our two language example, you would use the following Printfile tags - the first one in the English VDF and the second in the Spanish VDF:

Printfile:/doc_link/esther/english/userguide.pdf
Printfile:/doc_link/esther/spanish/userguide.pdf

For more details on View Definition Files and the Printfile tag, see ***.