Meta-HTML Installation Guide

THE META-HTML LANGUAGE REFERENCE MANUAL

[TOC]

Meta-HTML Installation Guide

Installing the Server

General Instructions for Installation

There are distribution specific instructions located in the directories Server, Engine, and Processor. You may have only one of these directories if you elected to obtain only the Server, Engine, or Stand-Alone Processor, or, you may have all of them if you received the Meta-HTML Tools Suite distribution.

Installing Your First Web Server

Installing the Meta-HTML Server is quite straight-forward, and only requires you to have the most minimal knowledge of Unix-like systems. For those of you who can't wait, the following sequence is sufficient to install the Meta-HTML Server on a machine that is not already running a web server:

Choose a directory under which your server will be installed, say, "/usr/www". We will call this directory <wwwroot>:
```
    (mkdir /usr/www)
  
```

Create <wwwroot>/bin, <wwwroot>/docs, <wwwroot>/conf, and <wwwroot>/logs.

    (mkdir /usr/www/bin /usr/www/docs /usr/www/conf /usr/www/logs)

Copy "Server/mhttpd" and "Utilities/*" to <wwwroot>/bin.
```
    (cp Server/mhttpd /usr/www/bin)
  
```

Copy "Documentation" to <wwwroot>/docs.

    (cp -r Documentation /usr/www/docs)

Copy "Server/mhttpd.conf" to <wwwroot>/conf.

    (cp Server/mhttpd.conf /usr/www/conf)

Change "www.myhost.com" to the name of your host in the configuration file <wwwroot>/conf/mhttpd.conf. You can do this by either editing the file with your favorite editor (say, emacs), or by "sed"ing the original file:
```
    (cat Server/mhttpd.conf | sed -e "s/www.myhost.com/`hostname`/"
		&gt;/usr/www/conf/mhttpd.conf)
  
```
As the superuser, start the server from the <wwwroot> directory:
```
    (cd /usr/www; su -c bin/mhttpd)
  
```

Congratulations, you are now running the Meta-HTML Server, and you have a Web site! You can now go to your first URL:

Start a browser, and connect to "http://<your-host>/Documentation", where "<your-host>" should be replaced with the name of your machine.

Co-habitating the Meta-HTML Server with an Existing Server

You may run the Meta-HTML Server on a non-standard port (such as 8080), or under an aliased IP address for your machine. The Server tightly binds to the address and port that it finds in the configuration file. The newly installed server may serve the same documents that you are already serving with another server, or, may be configured to serve a different set of documents.

If you are installing the Server with its own set of documents to serve, and its own IP address, simply follow the instructions given under `Installing Your First Web Server'.

Otherwise, the intructions are almost identical; but you must manually edit the `mhttpd.conf' file and change the port number to 8080. You do this by changing the line which reads:

    <set-var mhtml::server-port = <if <get-var mhttpd::ssl-server> 443 80>>

to read:

    <set-var mhtml::server-port = 8080>

Then start the server as described above. The documents are served from the directory specified in `MHTML::DOCUMENT-ROOT'.

Installing the Engine

The Meta-HTML Engine is the CGI program which actually interprets Meta-HTML statements in your documents.

The Engine gets the path of the page to process from the environment variable PATH_INFO, which is also where it tries to find the value of the current session ID. Thus, a full URL to a page full of Meta-HTML commands stored in your Web documents directory as "foo/bar.mhtml" might look like:

  http://www.your-site.com/cgi-bin/nph-engine/foo/bar.mhtml

and, if a session ID were present in the URL,

  http://www.your-site.com/cgi-bin/nph-engine/73847837482/foo/bar.mhtml

Obviously, this URL is "ugly" in the sense that it is unlikely people browsing your Web site could remember it, or that it is something you would like to publish in a television commercial. So, the goal is to make some reasonable URL, such as http://www.your-site.com/foo/bar.mhtml be the one that your viewers see.

You handle this translation in the configuration files for your server, and the server specific sections of this manual tell you how to do that for many of the popular servers.

For example, let's say that you are building a hairy site for an organization called "Foo Industries." The URL of Foo Industries is http://www.foo.com. The Web administrator for Foo Industries sets up a translation for "/*" to point to "/cgi-bin/mhtml-engine/*".

An URL such as "http://www.foo.com/index.html" causes the Engine to be run, with a PATH_INFO value of "/index.html." The engine reads in and interprets "index.html", and then returns that page.

The Meta-HTML Engine performs various translation on the path that it receives; in effect, it is a small and powerful server on its own.

Prior to executing any page, the file "engine.conf" is executed. Typically, this file is used to set up any globally known page variables, so that references to, for example, SITE-DIRECTORY can be resolved readily within the document pages.