[insert project logo here (125x200px max)]

Navigator

• Home
• Downloads
• Documentation
• Research
• News
• Forums
• Project Summary
• CVS repository

Mailing-lists

• Help
• Announcement
• Developer

Please report any errors or omissions you find to our `Help' mailing-list, or post a message in the Forums.

Copyright and Licensing Information

Snap is (c) Jonathan T. Moore, 1999-2002 and licensed under the GNU General Public License (GPL).

All other parts of Splash are (c) Willem de Bruijn, 2002-2003 and licensed under the BSD Open Source License.

All sourcecode is made publicly available.

Acknowledgment

Splash and the Splash website are hosted by SourceForge.net

introduction - publishing news - updating the website - releasing files - using the cvs repository

Splash - Project Administration Guide

SNMP Plus a Lightweight API for SNAP Handling

Introduction

Splash, as most open source projects, is being developed by independent individuals at different locations. This can make administering the various tasks of the project a tricky task. The howto's and suggestions on this page should help anyone working with Splash to update the project in a similar manner.

This page is mostly of interest to developers, either part of the Splash team or independent users applying Splash to their own tasks. Nevertheless, some general tips might be interesting to administrators of similar projects. The information on this page is written as an addition to the Sourceforge.net documentation. Sections E and G are especially important for anyone using SourceForge regularly.

Publishing News

One of the tasks of a project administrator is to keep users and developers up to date on issues ranging from documentation updates to security issues. A number of channels exist to make such information known. To make sure people are neither overwhelmed with information, nor starved from important updates (especially security fixes) it is important to choose how and when to release these statements.

How to make a public announcement

An administrator can choose from a number of channels to supply information to its users. At sourceforge, our project host, these channels are:

• mailing lists
• the RSS news feed
• forums
• the website
• private emails

Which channel to choose depends largely on the information one wants to make known. For this we will select three criteria:

1. urgency
2. intended audience
3. channel status

The urgency of a statement dictates how obtrusive a message can be. Information that can be regarded as highly important to users can best be sent directly to them (push), instead of placed on a known location (pull). Directly opposing this are messages of lesser urgency. Examples of the first are security issues and -fixes. The second category encompasses file releases and documentation updates.

The following is a simple rule governing the use of push and pull channels. Never push information on a user's agenda unless he or she really needs it. If you do otherwise, chances are that really important information will be treated at lower priority in the future. Be careful with direct emails and related channels.

The intended audience of a message is another important criteria for selecting your channel. At the very least one should disseminate between users and developers, and therefore make separate channels available for these groups. In larger projects more groups can be thought of, but that is not necessary for now. In case of Splash, we have made separate mailing-lists and forum threads for these two groups. Use them in their intended fashion.

Lastly, channel status deals with a practical implication of having many possible channels to your audience. At the time of writing, nearly no-one has registered to the mailing-lists. Using only the mailing lists to spread a message can therefore be considered useless at the moment.

When to make a public announcement

As there are many channels available we want to use them as consistently as possible. Here are a number of guidelines for making information public.

(*1) don't send spam; make sure people are interested in hearing about certain types of information first. Preferably, make people register for the announcement mailing list and refrain from sending direct messages completely.

(*2) try to use automated tools for this. For Splash we have a web gateway to the CVS repository that shows a complete history of all its files. Also, sourcecode documentation is created dynamically by a third party tool called doxygen.

Updating the Website

The website serves as a portal (for lack of a better word) to all other sources of information to all audiences. Remember this when making information available. A problem often found on websites, especially those administered by a lot of people, is that of inconsistency. Consistent document layout and site structure are keys to a good user experience. Having various different methods in a single site can confuse people, turning them away from a possibly useful tool.

The Splash website is directed especially toward researchers and developers. This makes adding a lot of introductory information unnecessary. However, supplying as much information as possible publicly (as opposed to through private communication, e.g. email) in a clear and concise manner is important, as future users might have little contact with previous developers and - administrators. For this purpose we have created a simple update system.

Using the Templates

The Splash website is generated on the fly from a number of independent sources. Most pages consist of manually prepared data, for instance this file. To guarantee a consistent look and feel and limit data replication, identical parts of the webpages have been moved out of the raw data files. The Splash CVS repository contains the subdirectory /project/website_input in which these raw files are saved. In the parent directory you can find various scripts that autogenerate complete correct XHTML 1.0 webfiles from the input in website_input.For introductory information on how (not) to create webpages visit this site. XHTML tag reference can be found at DevGuru.

If you want to edit information on the website do not edit the actual webpages!. Instead, open up the files in website_input ending on ".html.part". For instance, if you want to change this file (remove a typo, which most probably exists ;) ), open up the file [..]/website_input/doc/admin.html.part instead of the actual admin.html file on the webserver.

Similarly to altering files, if you want to add a file you should do so by adding a .html.part file in the website_input directory structure. In the generated webfile this .html.part file will be enclosed in a table data cell as follows:

  <td>[contents of your .part.html file]</td>
  

As long as the mark up code you use is valid XHTML 1 the output will become a valid webpage. Note that not all valid XHTML elements are considered valid when placed inside a table data cell.

After you've made all your changes to the website execute one of the following scripts in [...]/project (the parent dir of website_input):

By running update.sh or update_nodoxygen.sh the full webpages will be sent to the website and the raw datafiles are updated in the CVS repository.

NB: the proper way of executing these scripts is

  ./[scriptname] [sourceforge username]
  

For instance, use "./update.sh wdebruij" if your sourceforge username is wdebruij (which it certainly isn't :) ).

Checking code layout

After having updated the website you can test whether a file is free of grammatical errors (HTML grammar, not plain English) by clicking on the XHTML image on the left. This will redirect you to the W3C's validator service, which automatically parses and checks your page.

Checking Spelling and Grammar

There are a number of helpful tools out there for checking natural language in your files. Firstly, you can use Google for checking the correctness of a single word or an expression. Google suggests alternate spelling for possibly misspelled words. Use the number of found items for comparing complete figures of speech. For instance, comparing the use of `corect' and `correct' gave 45 thousand compared to 20 million pages. This trick also works on (parts of) sentences, but don't forget the necessary quotation marks then.

A useful service for finding translations and synonyms is Babylon.com. Bablyon translates many different languages and utilizes various domain specific dictionaries as well. Use it to translate from English to English for obtaining synonyms. A stand-alone application is available for the Win32 platform.

If you want to check entire pages of information the previously mentioned tools will not suffice. For this purpose use ispell or aspell under Unix. I'm not quite sure what stand alone systems are available under Windows, but Microsoft Office has an excellent internal spell- and grammarchecker.

Rigorously checking your grammar is unfortunately as yet impossible. However, there do exist some tools you might want to check out. Under Windows this is the aforementioned Office. For unix I suggest you try diction, an assistant that is supposedly based on the rules defined by William Strunk in his 1918 book, "Elements of Style".

Changing the Style and Layout; Altering the Templates

If you want to change the visual aspects of the website the advantages of our scripted system become apparent. You will need to change at most four small files to updated the look and feel of the entire site.

Style characteristics, such as highlighting color, font and background color are encoded in a Cascading Style Sheet. Change the file standard.css in website_input to change to look of these predefined items.

The layout of the pages, including items such as the navigation bar and the project logo, are defined in a number of template files in website_input:

Releasing Files

Determining when to release Files

Developers are encouraged to use the CVS repository for obtaining the latest version of the Splash sourcecode. Full scale Releases are intended mostly for the end users and should therefore be updated less frequently. A rule of thumb:

• publish new releases with an altered update number (i.e. the Z in version X.Y.Z) when important yet small fixes to the CVS tree have been tested and found OK.
• publish new releases with an altered minor number (the Y in the example above) when completely new functionality has been added and tested.
• publish new releases with an altered major number (X) only when the codebase is completely overhauled, breaking consistency with earlier implementations.

Whatever you decide, make sure that file releases are as bug free as possible! At the very least make sure that no compilation errors exist in file releases.

Making Packages for Redistribution

The sourcecode from snap-wjdb and snap_svc uses the tools autoconf and automake to create redistributable packets. To update the version numbers of these packets you have to change the second line of the configure.in and rerun these tools:

  aclocal && autoconf && autoheader && automake -a --foreign
  

If all went well, you can extract a redistributable package using the command make dist.

Using the Sourceforge File Release System

Detailed information about SourceForge's file release system can be found in section G4 of the Sourceforge.net documentation

Using the CVS Repository

A CVS Primer

General information on using a CVS repository can be found in the CVS reference manual. Sourceforge specific information is made available through the Sourceforge Document Manager (skip to item F).

The Splash Repository Layout

The Splash repository, found under /cvsroot/splash-snap on cvs.sourceforge.net, contains five main branches:

• benchmark_results contains raw data obtained during test runs
• code contains the sourcecode for the various Splash packages
• doc contains the raw form of paper based documentation (mostly LaTeX)
• project contains the raw form of this website
• misc is currently unused

You can anonymously access the repository using cvs on unices using the following instructions:

	cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/splash-snap login
 	cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/splash-snap co snapsnmp
  

Use similar settings for TortoiseCVS on the Win32 platform.

Web access is also enabled. Follow this link to visit our webCVS gateway.

Only registered members of the Splash team are allowed to update the repository. To do this, set the following environment options:

  CVSROOT = :ext:[sourceforge username]@cvs.sourceforge.net:/cvsroot/splash-snap
  CVS_RSH = ssh
  

and execute a simple cvs login; cvs co snapsnmp request.