[demonstration pages]

[copyright]

[installation]

[configuration]

[templates]

[passwords]

[access]

[bugs]

Introduction and motivation

W3news is a flexible CGI tool that implements a usenet newsreader through html pages. It connects directly to NNTP servers. The layout of the w3news generated pages is configurable through template html pages. Restricted newsgroups, only accessible through passwords, are possible.

Compared to other threaded discussion software, w3news has the advantage of using a NNTP newsserver for storage, so users can use either the w3news interface or a standard newsreader to get access to the discussion.

Demonstration pages

There used to be demo pages, but the news server on which they were stored is no longer under my control.

Copyright

The w3news software is available under the GNU GPL.

Getting and installing

In order to use this program, you need a working http server and the ability to run CGI programs. You also need access to a newsserver through NNTP. It is tested on Linux connecting to a INND server, but it should work with most other Unix systems and newsservers as well.

You need the following:

• Source archive of w3news, w3news.tar.gz.
• The libCGI library. It is located in the `support' subdirectory of the w3news tarball since it is apparently no longer supported by the author.

I'd like to know how you use this program; please drop me a short note telling me about the kind of discussion board you build with w3news. Your feedback is always welcome.

Now do the following:

• Install the libCGI library.
• Unpack the w3news sources somewhere.
• Edit the Makefile. A couple of directories should be set, as well as the name of the NNTP server.
• Type `make' to compile the thing.
• Edit the configuration files, see configuration below.
• Type `make install' to install the binaries and the configuration file.

If you encounter any problems, don't hesitate to contact me.

Configuration

W3news can handle multiple sets of newsgroups, and each set can have different permissions (ie. password protected or freely accessible) and the look of the pages of each set can be configured separately.

All this is setup in the directory 'conf' (you can edit the copy in the w3news source directory, 'make install' will take care of all the permissions later). This directory contains two subdirectories, 'groups' and 'templates'.

conf/groups

This directory contains a subdirectory for each group of newsgroups you want w3news to handle. Each of these directories should contain

• A softlink link 'w3news' pointing to '../../w3news2' (make it with 'ln -s ../../w3news2 w3news').
• A configuration file 'w3news.conf'. This file contains information about authorization (see the section on password protected groups below for more on this), the location of the template files used to do the layout of the various w3news pages, and a list of groups that should be accessible. See 'conf/groups/public/w3news.conf' for an example; it's fairly straightforward to setup.

config/templates

This directory contains a subdirectory for each set of templates you want to use for layout of the w3news pages. Groups can share one set of template files if you want. There are some simple default template files in 'conf/templates/demo/' and more complicated ones (in use at the Dutch Labour Party site) in 'conf/templates/pvda_new'. See the section on templates below for detailed information.

Constructing the template html files

W3news uses html template files to determine the appearance on the client's browser (instead of having everything hardcoded). Below is a description of all the new tags available for use with W3news. The source distribution contains, for each page that w3news can display (the list of groups, the list of articles in a group, the followup form etc.) a demo page (in the directory `conf/templates/demo/').

groups.html

This is the page that determines the look of the list of groups accessible through w3news. The following tags are available:

<w3n_grouplist>

at the location of this tag, the list of newsgroups available in this group will be displayed.

articlelist.html

The page that contains the list of articles in a given group. Available tags:

<w3n_foreach_article> and </w3n_foreach_article>

the text enclosed between these tags is repeated for each article in the group. See the demo files for an example. Inside this block, you can use

<w3n_author>

author of the article.

<w3n_date>

date of the message.

<w3n_subject>

subject of the message.

<w3n_organisation>

organisation of poster.

$w3n_article_url

the url to access the article.

<$w3n_post_url>

the url used to start a new thread.

article.html

The page that shows a single article. Tags:

<w3n_author>

<w3n_date>

<w3n_subject>

<w3n_organisation>

as before.

<w3n_body>

the body of the article.

$w3n_next_url

$w3n_prev_url

$w3n_next_inthread_url

$w3n_prev_inthread_url

$w3n_followup_url

$w3n_post_url

will be replaced with url's to the pages that perform the requested action.

<w3n_if_prev_exists> and </w3n_if_prev_exists>

this block will only be shown when a previous article (chronologically) exists. Similar things exist for `next article', `previous in thread' and `next in thread':

<w3n_if_next_exists>

<w3n_if_prev_inthread_exists>

<w3n_if_next_inthread_exists>

followupform.html

The page with a form for posting a followup. Tags include the usual ones (author, date, subject, organisation, group) as well as

<w3n_author_email>

the email address of the poster of the previous message.

$w3n_action

the url that has to go in the submit button.

post.html

The page for starting a new thread. Tags are identical to the ones of followup.html.

error.html

The page that reports errormessages. Only one tag:

<w3n_errormessage>

the text of the errormessage.

postconfirm.html

A page that confirms the receipt of a message written using post.html or followup.html. No tags.

If there's anything other tag you'd like to have included in a future version of w3news, drop me a note.

Using password protected groups

NNTP newsservers are capable of restricting access to certain groups using passwords. The w3news software can be configured to automatically send these passwords when it connects to the NNTP server. In turn, access to certain sets of groups managed by w3news can be restricted using standard '.htaccess' files used by most www server software.

To setup all this, do the following (instructions are for use with INN, small changes are probably necessary if you use other software on your newsserver). Suppose we have a set of groups 'public.*' and another set 'restricted.*'. Then,

• In 'nnrp.access' (one of INN's configuration files), you would have to add lines like

  *:RP:::public.*,!restricted.*
  :RP:luckyguys:ourpassword:restricted.*,public.*
  

  The first line indicates that users that do not notify the NNTP server about their identity should have access to all 'public.*' groups but not to all 'restricted.*' groups.

  The second line indicates that users who identify themselves as being members of the group 'luckyguys' and use the password 'ourpassword' should get access to both 'restricted.*' and 'public.*'.

  Note that this can get tricky if you have multiple password protected groups. The INN manual can be confusing.

• In the 'w3news.conf' file that specifies the newsgroups that you have just restricted in your NNTP server, add the lines

  authinfo_user luckyguys
  authinfo_password ourpassword

• Make a '.htaccess' file in the the directory in which this 'w3news.conf' file is residing. See the manual pages of your www server for details on how to do this.

Accessing the w3news module with your browser

The following access options are now available (all URL's have to be prefixed with

http://www.my.domain/${WWW_ROOT}/groups/[groupname]/w3news

where '${WWW_ROOT}' is the variable as set in the Makefile), and '[groupname]' is the name of the w3news group of newsgroups (corresponding to a subdirectory in 'conf/groups/'):

/groups

lists all the groups.

/articlelist/[newsgroupname]

lists all articles in the given newsgroup.

/article/[newsgroupname]/[number]

shows an article.

/followup/[newsgroupname]/[number]

post a followup message.

/post/[newsgroupname]

start a new thread in the given group.

Known bugs

• If the subject of an article contains quotes, all sorts of things can go wrong in the creation of the followup forms. These things should be properly encoded. Sometimes, using other types of quotes in the templates helps.
• When a URL appears in the text and is ended with a period (like `http://www.pvda.nl.'), w3news goes into an endless loop. Putting a space before the period solves the problem, but this should be fixed. fixed in 1.4
• Cannot effectively handle very large newsgroups, for various reasons (index page takes long to transfer, memory use becomes excessive). improved in 1.3