About...
Tools...

D³E-HyperNews User Guide

HyperNews is one of the open source web discussion systems that we have customised for D³, selectable from within the D³E Publisher's Toolkit.

Please note that you need to understand web server administration to install this properly. Problems may be sent to D3E-HyperNews' developer, Mike Wright <mwright@ucar.edu>, who will deal as best as he can (he has a day job!)

See the Journal of Interactive Media in Education for an example of D³E-HyperNews in use (for online journal peer review).

D³E-HyperNews requirements in brief:

Software: known to run on Apache and Netscape web servers; written in Perl
Hardware Platform: Unix or Linux (it makes use of unix directory file structures; no Windows port available; see D³E-Phorum for a Windows-based web server discussion environment)

Installation

As D³E is a research project, the modifications we make are specific to our needs. Anyone who wishes to use our version may do so, but should bear in mind that some things may not work the way expected or in the way they do in the general HyperNews release. The current version is a customisation of HyperNews v1.9.5.

Before using the modified version, we advise you to review the documents held on the HyperNews site to become familiar with the general "look" of HyperNews, and with it's installation and use instructions. After that, you should look at a use in the D³E project such as the journal JIME. Go to one of the papers and select a "comment-bubble" to get to the debate section.

As part of the design of JIME, we required HyperNews to "look" and "act" in specific ways - hence our modifying HyperNews. When using HyperNews in a project similar to JIME, we strongly advise you to think what structure you want, and what the URL's to those structures should be before configuring a HyperNews installation. This will make it easier to set up a maintainable structure.

Once HyperNews is installed and being used along side a set of documents on a Web Server in a closely integrated manner, it is hard to reconfigure the integration for such things as a directory restructuring.

The details we give below on using the modified version assume you have looked over the documentation at the HyperNews home site and looked at our examples. Please read through this page before proceeding. When you get to the configuration of the modified HyperNews, the on-line configuration form has further details to help you with that stage.

HyperNews Home Page
Installation of HyperNews
HyperNews Use Instructions
User instructions for D³E (an example of what to give your users.)

Using D³E-HyperNews

The following descriptions relate to how we install and use our modified version of HyperNews. You don't have to follow our model if you don't wish to. To do the installation, we assume the user is familiar with UNIX, NCSA style Web Server configuration (we use the Apache Web Server), and basic use of the UNIX make facility (in at least being able to edit user defined variables in distribution Makefile.)

You can download D³E-Hypernews (version 1.9.5) from here.

Unpack the Source Code

We keep our versions of hypernews in a CGI directory called "cgi-hn" (to allow easier administration by keeping it all separate from "cgi-bin".) To follow this model, you need to set up your Web Server with a CGI directory called "cgi-hn".

Place the source archive file into this directory and do:

gunzip hn_d3e.tar.gz
tar -xvf hn_d3e.tar
cd HyperNews1.9.5.D3E.1/.scripts
If your local version of Perl isn't /usr/local/bin/perl, you will need to change the first line of the Perl script fixPerlPath (found in hn_d3e/.scripts)to reflect the correct path to perl, and then do run the script.

Install HyperNews

In the .scripts directory is a Makefile for use in installing the unpacked HyperNews. make will list the options you can go through to install the D³E version of HyperNews.

make install This will create the final structure with a root directory name of HyperNews1.9.5.D3E.1 (under cgi-hn in our model.) If you want to call it something else (you need to for multiple installations) change the HN_NAME variable in the Makefile. You will need to setup a ScriptAlias (see below) for this directory.

Multiple discussions under one installation will all share a common interface and configuration details. If you only require one style, and one set of access configurations, then one installation is all you'll need.

We run a number of hypernews discussions. This is because we want to change the interface and some configuration details for different projects, and different projects have differing levels of access, e.g. some allow anyone to read and post discussion comments, others are restricted to groups or domains. To allow this type of configuration, one installation of HyperNews will be needed for each configuration variation required.

To run a number of HyperNews installations, we set up a common directory to hold the scripts. We then link the scripts of each hypernews installation against the common set. If you don't want to have a common directory, ignore these steps:

make hn_scripts to create the common directory. See the Makefile for notes about HTACCESS and ADMINFILE variables. These files are needed before this target is run.
make links to link the scripts in the current .scripts directory
or make linkclone to make a "clone" of the present installation with linked directories. This is the target best used to make another installation later if you need it. See also the make target descriptions about linkdirclone and clone in the first part of the Makefile.

Web Server Configuration

The Web Server must now be configured to use the installation. We use the Apache Web Server, an NCSA style Web Server. We also assign a "user and group" to the Web Server, and assign these to the HyperNews scripts. Thus, any CGI running will run as this "user/group" pair, and thus will have the normal "read/write" permissions on the system as this user. You should set up this user with care in order to restrict what the user can do.

To use HyperNews, you access it via a URL that takes the format:

http://your_server_name/CGI_Script_Alias/Hypernews_script_name/forum

e.g. http://www.hypernews.org/HyperNews/get/hypernews.html

You need to set the ScriptAlias in the srm.conf file to your needs:

ScriptAlias /CGI_Script_Alias/ /directory_path/cgi-hn/hn_d3e

hn_d3e is the default name given at installation. If you're running multiple installations, this directory will have a name for each installation (usually descriptive of the installation use for ease of administration.) The name is set with the HN_NAME variable in the Makefile.

This CGI directory will also need access set up for it in the access.conf file:

<Directory /directory_path/cgi-hn>
AllowOverride AuthConfig Limit
Options FollowSymLinks
</Directory>

You will now need to have the web server re-load it's configuration files.

Note 1: We keep the HyperNews archive (the discussion contributions and lists of discussion members) outside the document tree of the Web Server for ease of administration and security and so don't need a configuration section for it in the Web Server configuration files.

Note 2: If you use the HyperNews installation under a "virtual server" (easily set up using the Apache Web Server,) have the virtual server running and the CGI stuff set up before configuring HyperNews (the next section.) Configure the installation of HyperNews through the virtual server you want it to work with (next section.)

Configuration of a HyperNews Installation

Having installed HyperNews into a CGI location and set up the Web Server to run the scripts in HyperNews, you now need to configure the installation. This is done through a web form. Before doing this, you need to do a few things:

You need a directory to hold any discussion contributions and lists of discussion members. We keep this directory outside the document tree of the Web Server for ease of administration and security. Make a note of the path name as you will need it in configuration (hndocs).
You need a directory under the Web Server document tree to hold resources (image files) that are used in the HyperNews interface. You will need the URL to this area for use in configuration (hniconsURL).
Set up a valid email address if you configure HyperNews to post email messages of new discussion additions. This is the email address that will "send" the posts. Having another address for "errors" etc. will also be useful.
Be ready to make a note of administrator passwords and article creation URL's that will be given to you as part of the configuration process.

Now, to configure Hypernews, go to the form at:

http://your_server/ScriptAlias_to_HyperNews/Admin/setup-form.pl

Note: The distribution comes with the original short form. We have not modified the short form to work with this distribution. We have not modified the setup.pl to work from the commandline either. The above URL will run this. If you use the short form, or run setup.pl from the commandline, we do not guarantee the modified version will be configured correctly.

The "Admin" directory is for administrators to use. It was set up by the make install process. After configuration, access to this directory will be restricted to administrators (defined in configuration.) Any "clone" installation will have the same restrictions until re-configured.

When the form is up, please read the instructions and further details to help you configure the particular version of HyperNews to your needs.

A copy of this page is included in the distribution from D3E in the .scripts directory (instructions-d3e.html).

What is different

We have changed various forms (e.g. subscription, membership, setup, adding comments etc.) and various "kernal" scripts to meet our requirements. In some cases, we have simplified the general HyperNews interface, and changed it's look (such as in "outline" view.) We also use a restricted set of "comment identifiers" e.g. "Agree, Disagree". We have modified the "Makefile" quite a bit. We added the "forums" script that is accessed through the "Admin" directory of an installation.

As the modifications have included our own "buttons", these are included in the "Icons" directory of the distribution. The original HypreNews icons are available in the "Icons-HN" directory. Similarly, we have tailored icons-table-dist (the original is icons-table-dist.orig.) We have left the original distribution HTML files in place.

HyperNews is at a later version number. We don't plan to update our version to that version at present as our current version does what we need. We will monitor the state of HyperNews, and we may upgrade if time, resources and needs permit.

May 11, 1998.

About...
Tools...

D3E-HyperNews User Guide