Previous Next  Contents Glossary  Index References  Cover License
Appendix 4 - The Apache manual

The official thesaurus of Apache concepts and procedures is set up in the manual directory, by the standard Apache installation process. The documents it contains are multilingual, i.e. one document can exist in different language versions: English, German, French, Spanish, Russian, Japanese, Chinese, Korean, etc... A part from English, not all the languages have a version for every document though.

The documents can be in HTML or XML format. A presentation is given below for HTML documents. It can be repeated identically for XML documents.

It is advisable that you have a look at the contents of the manual directory before reading the following.

1. Multilanguage documentation

1.1 Language versions and type map
The different language versions are distinguished by an additional extension: .en for English, .de for German, etc...

In HTML format, a certain document can have, for example, these versions:

docu.html.en in English
docu.html.de in German
docu.html.es in Spanish
docu.html.fr in French

For each such group, there is a so-called type map document which contains the URI of the different versions along with their language and their content-type properties. Here, the name of this type map is the common part of the different version names, docu.html with the above example.

The .html extension notwithstanding, this is a text file, not an HTML page. You can display one of them to see (normally, double-clicking on it would display it in a user presentation form; from this display, you can display the source, as for a regular HTML page).

1.2 The negotiation function

language version select A request from a user or an HTML hyperlink would name a type map document, not a specific language version. The content-negotiation function of Apache would select the appropriate language version, based on the LanguagePriority directive, set in the Apache configuration file.

1.3 Editing the configuration file
As generated by the standard installation process, the configuration file does not contain the sufficient codes to have the mentionned type maps treated as such. You must add directives like 

<Directory manual>
   AddHandler type-map html
</Directory>

to declare the .html extension as a type-map extension for all files contained in the manual directory and below.

2. A local single language version
To activate the content-negotiation function you must call upon Apache, i.e. request the desired document from a browser, using an http address.

As the manual directory is not contained in the document root, to allow access to it, you have to define an alias. For example: 

Alias /manual/ C:/Apache2/manual/
 under Windows
or 
Alias /manual/ /user/apache2/manual/
 under UNIX

If Apache is in your local computer, you can then access a document from the Apache thesaurus through a request like: 

http://localhost/manual/mod/docu.html

You cannot display a document by double-clicking on its type-map (namely, docu.html in the example). As of September 2004, when you double-click on the English (or any other language) version of the document:

docu.html.en

it is not displayed as an HTML document should.

If you are sure you need the English version only, you can setup a version of the thesaurus on your computer where the documents can be accessed by a double click.

2.1 Procedure outline
A procedure is as follows:
1. Copy the manual directory to your computer (if it is already in your computer, make a copy of it), and apply the described changes to the copied version -- it is not recommended to modify the original version which should be maintained
2. Remove the type-map files (or change their extension to other than .html)
3. Change all the .html.en extensions to .html
Since the hyperlinks from the documents target the type maps, with the .html extension, they will direct you to the renamed English version.

2.2 The ChangeExtension utility

The ChangeExtension utility, available in the Apache/java/classes/tools directory can be used to change a given extension of all the files in a directory.

You have first to point the CLASSPATH environment variable to the classes directory.

The ChangeExtension utility is called using the command (from any directory): 

java tools.ChangeExtension
You will be requested to enter the old extension, then the new extension into which it is to be changed to - example: 
Old extension: .html
New extension: .sav
After you have confirmed by entering a "Y" (case is unimportant), a selection box is displayed. You can walk through the directory tree to select the desired directory:
- the current directory is displayed in the line labelled 'File name", near the box bottom
- to go up one level in the tree, click on the icone with an upward arrow, on the box top row
- to go down on a directory and make it current, double-click on it
- when you are satisfied with the current directory, select it by clicking on the "Open" button
You can try, and go as far as selecting the directory to modify. At the question 
Proceed on to modify these files? (Y/N)
you can cancel the procedure by entering an "N" (or anything not starting with a "Y" or "y") -- nothing would have been done.

2.3 Changing the file extensions

2.3.0 Practical advice

In the following is a description of how to change the .html extensions to something else, then remove the .en suffix so that .html.en becomes .html

Lest you mistakenly change the .html extensions remaining after the .en are removed, it is advisable to change the original .html to something else, in all of the directories first. Only then, remove the .en suffixes.

2.3.1 Changing the type map extension

To effect the proposed changes, you have first to change the .html extension of the type map files to something else, for example .save. So enter .html as the old extension, and .save as the new extension. After this, the screen will show: 
Old extension: .html
New extension: .save
Change .html to .save ? (Y/N)
Confirm by entering "Y" or "y" (type the letter and press the key).

A few lines intended to guide those who did not read this document are displayed. Press the key to proceed on.

Then continue to the end.

2.3.2 Removing the .en extension

Next, you have to remove the .en suffix from the file names. You do it by entering:
- .en as the old extension
- nothing as the new extension (just press the key).

You start with a screen like this: 

Old extension: .en
New extension: 
Change .en to  ? (Y/N)
Confirm by entering "Y" or "y" (type the letter and press the key). Then proceed on as before.

Previous Next Contents Glossary Index References Cover License