$Id: README.TXT,v 1.5 2004/10/29 08:42:32 hubbers Exp $

After unzipping the file 'nieuwslicht.zip' you have created a directory 'nieuwslicht' which contains the following files:

- client.bat
- client.sh
- server.bat
- server.sh
- nieuwslicht.jar
- README.TXT (this file)
- votes_sample.sos

If you used the source release 'nieuwslicht_src.zip' you have gained a
source directory as well:

- src


How to run these programs:
==========================

On Linux:
=========
You can start the client program (i.e. where the voters are entering their
preferences) by typing './client.sh <id> [print]'.
- <id> can be any string, it is intended to be able to see from which client
  the vote is coming. (The sample file used 'TEST' as id.)
- [print] is an optional keyword to indicate whether the ballots need to be
  printed to the default printer or sent to a file. (If your default printer
  happens to be a PS printer this will lead to a nice PS file.)


You can start the server by typing './server.sh'.

On Windows:
===========
You can doubleclick on the 'client.bat' file to start the client. In this case
the client is always started with id 'A'. If you prefer another id, edit this
file and change the 'A' into something else.
Furthermore, this batch file implies that no real printer is used. If you want
to print to the default printer on your system, modify the batch file into
something like 'java -jar nieuwslicht.jar A print'.

To start the server doubleclicking on server.bat should do the trick.


How to operate the client:
==========================

After startup you see a screen with a vote number entry field which is
enabled and a disabled screen with buttons for the candidates.

Since only the entry field is enabled, you should start by typing one of the 
valid vote numbers. (See the end of this file for a list.) It is case 
insensitive. This test is done in order to prevent people from simply casting
more than one vote. Though not impossible, guessing a valid id will be
difficult.

If you have managed to enter a valid one, the panel with the buttons for the
candidates becomes enabled. Choosing a candidate is just a matter of clicking
on either the picture or the name underneath it.

After clicking the vote is being printed and a popup window appears on the
screen, ordering the voter to check whether the print shows the candidate of
his choice.
If this is OK, he should press 'Afdruk is JUIST' button, if not he should
press 'Afdruk is ONJUIST'.
In either case a new popup tells the user what he has to do. 
If it was OK he should fold the ballot and put it into the appropriate box.

If it was not OK for some obscure reason, he can choose
another candidate. He cannot modify his vote number anymore.
On each next print the text 'Correctie x' appears where 'x' equals the
number of corrections he made. This is done in order to be able to check
whether the withdrawn prints are not folded and put into the ballot box.
Withdrawn prints should be given to one of the operators.

To quit the program, push the close button on the window title.
Or, if the program is run in full screen mode, simply press the Radboud
University logo.
A popup will appear and ask for the magic word. This is done to prevent
voters from too easily killing our application. Right now the magic word is
'exit'.
As a side effect of shutting down the program a file
'votes_<timestamp>.sos' is being recorded to disk.

This file can be found in the OS's temp directory. On Linux typically '/tmp',
on Windows '\WINNT\TEMP'. Anyway, the server knows where to look.



How to operate the server:
==========================

After starting up the server you get a screen consisting of three areas.
A status area on top, a button area on the left and a chart area on the right.

In the status area you can see how many candidates have been found in the
setup file. Typically three: Bush, Kerry and Blanco.
There are no votes imported yet.

The first thing to do is import the votes. (Although the user interface does
allow pushing other buttons as well.) After pushing the button, you get a
file browser which typically starts in the directory where the client has
recorded its votes.
Simply choose the appropriate .sos file.

The status area will be updated, showing the number of votes incorporated.
On the 'Stemmen' tab in the chart area you can view a list of all votes
imported.

It is possible to import several vote files before counting.
In case some vote id's show up more than once, only the first occurance is
recorded. In order to decrease chances on such a collision, the id for the
client is incorporated into the vote id.

After reading all the votes it is simply a matter of pushing the 'Telling'
button to get the results in the chart area.
Votes for unknown candidates are not counted hence it is possible that
the number of imported votes is larger than the number of counted votes.
The 'Stemmen' tab shows which votes were counted and which were not.

The button 'Telling' and '1e Hertelling' operate exactly the same. They count
the votes in an unfair way. Unfair is defined as follows.

If a vote is for Bush the vote is always counted.
If a vote is for Kerry or Blanco the vote is only counted correctly if
Bush has already his 'predicted percentage'. If Bush has not yet reached
this percentage, these votes are counted for Bush.

On the 'Instellingen' tab you can set the 'predicted percentage' for Bush.
In fact 'minimum percentage' is a better formulation. Since all votes that
were already for Bush are never given away, the outcome might be higher than
this percentage.

After changing this value, go back to the 'Diagrammen' tab and push 'Herstel'
and then 'Telling' again. Simply pushing '1e Hertelling' also works.

The button '2e Hertelling' always counts the votes fairly as they were
originally casted. The value of the slider has no influence.

The button 'Herstel' only resets the counting results, it does not modify
the imported votes.

The button 'Afsluiten' shuts down the program.




This is a list of the valid vote id's:

d316 9f7d 642a 0eda 
a9e4 ac19 7c5b d3f2 
b506 2d3f cf84 212a 
7fee 4933 04f3 6cdc 
ea2e d0dc bff5 d8ac 
5ab9 a0ad c355 1882 
ad64 bd22 44f3 8b2b 
b704 46c4 04f2 1abe 
6b51 aecd eb77 734f 
aea1 b3b0 ae52 0979 
a06e a671 6826 e0ac 
9426 8761 404f e492 
79d2 bba3 e1cf 92d9 
e091 cb09 970b 186d 
4ebc 2a44 ca77 c009 
9593 6867 0bce 91eb 
90d4 7707 7a8b 8327 
978c 24b0 01cc 7830 
dce4 019d 70b9 63f1 
6b00 b324 22dd 5876 
fff3 a62e 83ed f77f 
68ce 845f 2d9b db64 
030b 8285 9552 daeb 
c795 26a5 4e2d 93a4 
de89 d0df b60e e5be 


