Using the links2html program

Barry Cornelius
Computing Services, University of Oxford, Oxford, UK
last updated: 10th June 2005; first created: February 1998


The links2html program is able to build a hierarchical structure of references to the WWW. Although these notes show you how to use links2html to organise your WWW bookmarks, it can be used for other things.

If you find these notes confusing, then look at the last section of the notes where there are some details about how to get started.

The directory tree that links2html expects to find

By default, the links2html program works with the files that are in (and below) the directory ~/public_html/bookmarks. This directory can be created using the commands:

umask 022
chmod 755 ~
mkdir ~/public_html
mkdir ~/public_html/bookmarks
These commands set the default permissions so that anyone (including the WWW server) can look at any WWW pages in the directory ~/public_html/bookmarks.

You can execute the links2html program when you are in the directory ~/public_html/bookmarks or in any subdirectory below this directory. In each of these directories, the links2html program looks for subdirectories and a file called links. Both of these are optional, i.e., there may be no subdirectories and/or there may not be a file called links. It ignores any other files.

The file called links

If you want a directory to contains links to some WWW pages, then you should put these in a file called links. The links2html program expects the file links (if it exists) to be a textfile where each line that you add to the file has the following format:

i.e., a line consists of a phrase (where each space is replaced by an underline) followed by one space followed by a URL.

When the links2html program is executed, it will alter the file links. On each line that is of the above format, it will add today's date followed by a unique number at the start of the line, e.g.:

980205 00641 Durham_home_page
If a line is already in this format, the links2html program does not alter the line.

So, whenever you have a new link to add, just add a new line with the format:

to the file links, and then run the links2html program again.

If you already have a line in the file links and the URL changes, just edit the URL of the appropriate line of the file links, alter the date part of the line (if you wish), and then run the links2html program again.

The file called index.htm

When the links2html program is executed, it will also create/update a file (in the current directory) called index.htm. This is the file that will be accessed when you use a WWW browser to look at the bookmarks that have been created by the links2html program.

The file index.htm is an HTML file that is in two parts. The first part contains one WWW link for each of the lines in the links file, and the second part contains one WWW link for each of the subdirectories. The two parts are divided by a horizontal rule.

So, you don't ever have to edit the index.htm file: it is automatically created by the links2html program.

Executing the links2html program

To execute the links2html program, type the command:

By default, this program will only process the current directory. If you want it to process the current directory and all of its subdirectories, type the command:
/users/dcl0bjc/bin/links2html -r

Using a different directory tree [optional]

By default, links2html uses the directory ~/public_html/bookmarks. You can tell it to look elsewhere by setting an environment variable, e.g.:

setenv LINKS2HTML_PARENT /users/dxy3abc/public_html/otherdir
It is recommended that the directory is in your public_html directory.

Getting started with links2html

Here are some steps that can be used to get you started with using links2html.

First, execute the following commands to set up appropriate permissions and directories. Each mkdir command will give you an error message (which you can safely ignore) if the directory already exists:

umask 022
chmod 755 ~
mkdir ~/public_html
mkdir ~/public_html/bookmarks
cd ~/public_html/bookmarks

Now copy some files and directories across:

cp -r ~dcl0bjc/public_html/bookmarks.example/* .
Note: this line ends in a star followed by a space followed by a full stop.

You should now look at the files that have been copied. In particular, use a text editor (such as pico) to see what is in the following files:


Now do:

cd ~/public_html/bookmarks
/users/dcl0bjc/bin/links2html -r
Have a look to see how the above files have been altered by the links2html program and note that it has created several files called index.htm.

Now use any WWW browser to examine what you have created. Start at the URL where dxy3abc is replaced by your username.