Probably the first thing you will want to do once your Greenstone installation is up and running is personalize the home page. The file that generates the Greenstone home page is called home.dm, and is located in the macros subdirectory of the directory into which you installed Greenstone. (The default for Windows systems is C:\Program Files\gsdl.) This is a plain text file that you will have to edit to create a new home page. Instead of editing it, we recommend creating a new file, say yourhome.dm. This will be like home.dm but will define “package home”—which is the bit that does the actual work—in a different way.

When you make a different home page, there must be some way of linking in to the digital library pages so that you can search and browse the collections on your system. The solution that Greenstone adopts is to use “macros”. That's why the home-page file is called “.dm” and not “.html”—it's a “macro” file rather than a regular html file. But don't quail: the macro file basically contains just html, sprinkled with a few mystical incantantations which are explained below. The macro language is a powerful facility, and only a small part of it is described below—see the Greenstone Digital Library Developer's Guide for more information.

<imgcaption figure_your_own_greenstone_home_page|%!– id:264 –%Your own Greenstone home page ></imgcaption>

Figure <imgref figure_your_own_greenstone_home_page> shows an example of a new digital library home page. Each of the “Click here” links takes you to the appropriate Greenstone facility. This page was generated by the file called yourhome.dm shown in Figure <imgref figure_yourhome_dm>.

<imgcaption figure_yourhome_dm|%!– id:266 –%yourhome.dm used to create Figure <imgref figure_your_own_greenstone_home_page> ></imgcaption>

package home
_content_ {
<h2>Your own Greenstone home page</h2>
<ul>
<table>
<tr valign=top><td>Search page for the demo collection<br></td>
      <td><a href="_httpquery_&c=demo">Click here</a></td></tr>
<tr><td>"About" page for the demo collection</td>
      <td><a href="_httppageabout_&c=demo">Click here</a></td></tr>
<tr><td>Preferences page for the demo collection</td>
      <td><a href="_httppagepref_&c=demo">Click here</a></td></tr>
<tr><td>Home page</td>
      <td><a href="_httppagehome_">Click here</a></td></tr>
<tr><td>Help page</td>
      <td><a href="_httppagehelp_">Click here</a></td></tr>
<tr><td>Administration page</td>
      <td><a href="_httppagestatus_">Click here</a></td></tr>
<tr><td>The Collector</td>
      <td><a href="_httppagecollector_">Click here</a></td></tr>
</table>
</ul>
}
# if you hate the squirly green bar down the left-hand side of the
# page, uncomment these lines:
# _header_ {
# }

You can use Figure <imgref figure_yourhome_dm> as a template for creating your own specialized Greenstone home page. Basically, it defines a macro called content. Inside the curly braces is ordinary html. You could insert additional text, along with any html formatting commands, to put the content that you want to see on the page. The text is regular html; if you want you can include hyperlinks and use all the other facilities that html provides.

To make your new home page link in with other digital library pages, you need to use an appropriate magic spell. In this macro language, magic spells are words flanked by underscores. You can see these in Figure <imgref figure_yourhome_dm>. For example, _httppagehome_ takes you to the home page, _httppagehelp_ to the help page, and so on. In some cases you need to include a collection name. For example, _httpquery_&c=demo specifies the search page for the demo collection; for other collections you should replace demo by the appropriate collection name.

The definition of the macro called _content_ is plain html. Any standard html code may be placed within a macro definition. However, the special characters '{', '}', '\', and '_' must be escaped with a backslash to prevent them from being processed by the macro language interpreter.

Note that the _content_ macro definition does not contain any html header or footer. If you want to change the header or footer of your home page, you should define _header_ and/or _footer_ macros, adding them to the yourhome.dm file in the form

_macroname_ {
...
}

For example, the squirly green bar down the left-hand side of Greenstone pages is defined in the _header_ macro, and making this macro null will remove it, as indicated at the end of Figure <imgref figure_yourhome_dm>.

You have to tell Greenstone about the new home page yourhome.dm. The system reads in the macro files that are specified in the main configuration file main.cfg, so if you create a new one you must include it there. Name clashes are handled sensibly: the most recent definition takes precedence.

Thus to make the Greenstone digital library software use the home page in Figure <imgref figure_your_own_greenstone_home_page> instead of the default, first put the yourhome.dm file in Figure <imgref figure_yourhome_dm> into the macros directory. Then edit the main.cfg configuration file to replace home.dm with yourhome.dm in the list of macro files that are loaded at startup.

You may want to redirect a more convenient URL to your Greenstone cgi program. For example, on our system the URL http://nzdl.org (which is shorthand for http://nzdl.org/index.html) is redirected to http://nzdl.org/cgi-bin/library . The Apache webserver accomplishes this with the Redirect directive. Along with other directives, this goes into the C:\Program Files\Apache Group\Apache\conf\httpd.conf configuration file. To redirect the URL http://www.yourserver.com to http://www.yourserver.com/cgi-bin/library , put this line into httpd.conf:

Redirect /index.html http://www.yourserver.com/cgi-bin/library

Then you will reach your digital library system directly from the URL http://www.yourserver.com . Instead, if you wanted a URL like http://www.yourserver.com/greenstone to be redirected to http://www.yourserver.com/cgi-bin/library , include in the httpd.conf file

Redirect /greenstone http://www.yourserver.com/cgi-bin/library

If your computer doesn't have a domain name (like the “www.yourserver.com” above), just replace www.yourserver.com by localhost in the lines above. So long as the browser is running on the same machine as the webserver—which it surely is if your computer doesn't have a domain name—this has the same effect as the above redirections.

Instead of putting redirect directives into the file httpd.conf, you can equally well put them into a file called .htaccess within your server's document root directory. In fact, doing so has two advantages. First, changes to .htaccess take effect immediately, whereas you have to restart the Apache webserver to see the effect of changes to httpd.conf. Second, on Unix systems you usually have to be logged in as the “root” user to edit httpd.conf, whereas you don't to edit .htaccess.