From upstream: Update copyright.

[usenet/usevote.git] / README

UseVoteGer 4.09  (c) 2001-2007 Marc Langer

UseVoteGer is a voting software for usenet votes.

This script package is free software; you can redistribute it and/or
modify it under the terms of the GNU Public License as published by the
Free Software Foundation.

Many thanks to:
- Ron Dippold (Usevote 3.0, 1993/94)
- Frederik Ramm (German translation, 1994)
- Wolfgang Behrens (UseVoteGer 3.1, based on Frederik's translation, 1998/99)
- Cornell Binder for some good advice and code fragments
  (e.g. UVtemplate.pm, UVformats.pm)

This is a complete rewrite of UseVoteGer 3.1 in Perl (former versions were
written in C). Not all functions of Usevote/UseVoteGer 3.x are implemented!
 
-------------------------------------------------------------------------------

UseVoteGer 4.09 - Usenet-Abstimmungssoftware
===========================================

von Marc Langer <uv@marclanger.de>

aktuelle Versionen: http://www.usevote.de


Inhaltsverzeichnis
==================

1.  Kurzbeschreibung
2.  Usevote fuer Ungeduldige
3.  Kompatibilitaet zu frueheren Versionen
4.  Liste der Dateien
5.  Anfangs-Konfiguration
6.  Konfiguration fuer einzelne Abstimmungen
7.  Wahlschein generieren
8.  Stimmen verarbeiten
9.  Unzustellbare Bestaetigungen
10. 2. CfV / Result
11. Datenschutz
12. Personalisierte Wahlscheine
13. Die einzelnen Programme
14. Die Konfigurationsdateien
15. Templates


1. Kurzbeschreibung
===================

Diese Software vereinfacht die Durchfuehrung von Usenet-Abstimmungen.
Usevote in der Urversion wurde von Ron Dippold fuer die Reorganisation
der Gruppe comp.sys.ibm.pc.games geschrieben und spaeter fuer die
allgemeine Verwendung verbessert.

Die deutsche Uebersetzung von Frederik Ramm diente jahrelang als
Grundlage fuer CfV-Auswertungen im deutschsprachigen Raum.
Wolfgang Behrens von den German Volunteer Votetakers (GVV) passte
es spaeter an neue Begebenheiten (z.B. personalisierte Wahlscheine)
an. Jedoch liefen die UseVoteGer 3.1beta-Versionen aufgrund eines
unbekannten Fehlers nicht auf jedem System (Segmentation Fault).

Um groessere Flexibilitaet und Plattformunabhaengigkeit zu bieten,
habe ich mich entschlossen, UseVoteGer in Perl neu zu implementieren.
Getestet wurde diese Version mit Perl 5.x unter Linux sowie
ActiveState Perl unter Windows 98.


2. Usevote fuer Ungeduldige
===========================

I. Einmalig bei der Usevote-Erstinstallation
   (1) usevote.cfg nach Bedarf anpassen (selbsterklaerend)
       ACHTUNG: Unter Windows gibt es das Programm "less" nicht, da "more"
       aber einigermassen broken ist, sollte man sich less fuer Windows
       herunterladen: http://www.greenwoodsoftware.com/less/less381d.zip
       Notfalls laesst sich auch in usevote.cfg die Einstellung "pager"
       auf "more" setzen, aber viel Freude hat man damit nicht...
   (2) Evtl. die Templates im gleichnamigen Unterverzeichnis fuer
       eigenen Geschmack anpassen. Die Templates enthalten saemtliche
       Texte fuer Bestaetigungs-/Fehlermails sowie die Ausgabeformate
       und Texte fuer die CfVs und das Result.
   (3) Perlmodule MIME::Parser, MIME::QuotedPrint, Digest::MD5,
       Date::Parse und Email::Date installieren, falls noch nicht vorhanden.
       Bei Benutzung von POP3 oder SMTP (siehe usevote.cfg) muss
       Libnet installiert sein (Net::POP3 und Net::SMTP).
       (Fuer Perl-Einsteiger: Unter Unix geht die Modul-Installation
       sehr einfach mit "perl -MCPAN -e shell", ActivePerl fuer
       Windows hat einen eigenen Paketmanager)

       Achtung: Bei meinem ActivePerl 5.6.1 war eine alte Libnet-Version
       enthalten, die noch keine SMTP-Authentication unterstuetzte.
       Bei Benutzung dieses Features muss evtl. erst upgedated werden.

II. Fuer jedes Voting
   (1) usevote.cfg auf das durchzufuehrende Voting anpassen
       (selbsterklaerend)
   (2) bei Sonderregeln (Abhaengigkeiten der einzelnen Abstimmungspunkte)
       in usevote.rul Regeln definieren (selbsterklaerend)
   (3) CfV erstellen und Wahlschein mit uvballot.pl generieren
   (4) Fertigen CfV einreichen und auf Veroeffentlichung warten ;-)
   (5) Bis zum 2. CfV regelmaessig (an den ersten Tagen mehrmals taeglich,
       spaeter einmal taeglich) dies tun:
       - uvvote.pl durchlaufen lassen
       - im Verzeichnis tmp/ die Datei ergebnis.* (Ergebnis der Auswertung)
         und evtl. ack.* (Bestaetigungsmails an die Waehler) kontrollieren
       - Falls es Probleme gab: Bitte den Abschnit "Stimmen verarbeiten"
         weiter unten in dieser Datei genau durchlesen. Dort steht
         beschrieben, wie Fehler korrigiert werden koennen
       - "uvvote.pl clean" aufrufen, um die Bestaetigungen zu verschicken
         und das Ergebnis zu speichern/archivieren
       - Falls Wahlbestaetigungen als unzustellbar zurueckkommen, solltest
         Du diese zusammen in einer Datei speichern oder in ein spezielles
         POP3-Postfach leiten
   (6) Zwischenbestaetigung fuer den 2. CfV mit "uvcount.pl -l" erzeugen und
       veroeffentlichen. Falls Wahlbestaetigungen als unzustellbar
       zurueckkamen, kannst Du mit "uvbounce.pl dateiname" automatisch eine
       Liste der ungueltigen Adressen erzeugen ("dateiname" ist die Datei,
       in die Du zuvor die Bounces gespeichert hattest). Siehe auch Abschnitt
       "Unzustellbare Bestaetigungen" weiter unten in dieser Datei, dort
       ist auch erklaert, wie die Bounces aus einem POP3-Postfach gelesen
       werden koennen.
   (7) Bis zum Result wieder wie (5)
   (8) Zum vorgegebenen Zeitpunkt die Wahl abschliessen,
       mit "uvcount.pl -r -v" Endergebnis erzeugen und veroeffentlichen
       (zuvor wiederum Liste der ungueltigen Mailadressen erzeugen, siehe
       Punkt 6)

Weitere Details finden sich im Folgenden.
Jeder Nutzer dieser Software sollte sich diesen Text wenigstens einmal
komplett durchlesen.

Abschnitt 6 beschreibt, wie mehrere Abstimmungen gleichzeitig durchgefuehrt
werden koennen, ohne saemtliche Programmdateien zu kopieren.


3. Kompatibilitaet zu frueheren Versionen
=========================================

- englische Usevote-Versionen: keine Kompatibilitaet

- deutsche Usevote-Versionen (Usevote 3.0a, UseVoteGer 3.1):
  * Wahlscheine haben neue Markierungen zum sicheren Erkennen
    der Stimmen. Bisherige Wahlscheine sind mit dieser Version
    nicht mehr einsetzbar!

  * acktext.txt gibt es nicht mehr, statt dessen sind im Unterverzeichnis
    "templates" Vorlagen zu finden, die diese Texte enthalten.

  * usevote.cfg ist komplett inkompatibel

  * usevote.rul: voll kompatibel, ohne Einschraenkungen

  * Ergebnisdateien: Inhalt kompatibel, aber Namensgebung geaendert
    (obwohl irrelevant, da Umstieg auf diese Version waehrend
    einer laufenden Wahl nicht moeglich)

  * scheinkennungen: Dateiformat gaendert (aus selbigen Gruenden
    nicht weiter wichtig)

  * uvshell: integriert in uvvote.pl, ueber usevote.cfg steuerbar
    
  * uvvote.pl: Aufrufparameter geaendert / Zusammenfuehrung mit uvshell
  
  * uvcfv.pl: Alte Funktionalitaet ist nicht mehr implementiert,
    statt dessen dient das Tool jetzt zum Generieren der persoenlichen
    Wahlscheine und Verschicken des CfV an die Waehler
 
  * uvcount.pl: Beinhaltet auch uvack und uvdup. Drei Einzelprogramme
    schienen mir ineffizient.

  * uvbounce.pl: Ausgabeformat etwas anders


4. Liste der Dateien
====================

* Ausgelieferte Dateien:

CHANGES           Versionsaenderungen
COPYING           GNU General Public License
README            Diese Datei
UVconfig.pm       Routinen zum Einlesen und Pruefen der Konfiguration
UVformats.pm      Routinen zum Formatieren von Texten in Templates
UVmenu.pm         Routinen zur Interaktion mit dem Wahlleiter
UVmessage.pm      Routinen zum Parsen von Texten und Ersetzen von Platzhaltern
UVreadmail.pm     Routinen zum Einlesen und MIME-Decodieren der Mails
UVrules.pm        Routinen zur Regelverarbeitung (usevote.rul)
UVsendmail.pm     Routinen zum Erzeugen von Mails
UVtemplate.pm     Routinen zur Verarbeitung von Vorlagen (Templates)
bdsgtext.cfg      Spezieller Text fuer den Wahlschein (Hinweis auf
                  Datenschutzgesetz), muss ausserhalb Deutschlands ggfls.
                  angepasst oder kann ignoriert werden (bdsg=0 in usevote.cfg)
mailpatterns.cfg  Wildcards fuer verdaechtige Mailadressen
messages.cfg      Programm-Meldungen (Ressourcen-Datei)
scheinkennungen   Speicherung der Scheinkennungen bei personalisierten
                  Wahlscheinen. Muss zu Beginn der Abstimmung leer sein.
usevote.cfg       Konfigurationsdatei
usevote.rul       Abstimmungsregeln
uvballot.pl       Wahlschein aus Abstimmungsdaten erstellen
uvbounce.pl       Listen von unzustellbaren Bestaetigungen erzeugen
uvcfv.pl          Erstellen und Verschicken von personalisierten Wahlscheinen
uvcount.pl        Stimmenzaehlung, Erstellen von Waehlerlisten und
                  Aussortieren von doppelten Stimmabgaben
uvvote.pl         Stimmen verarbeiten (fuer die taegliche Arbeit)

templates/                Verzeichnis mit Templates (Vorlagen)
  ack-mail     	          Template fuer Bestaetigungsmails
  address-not-registered  Fehlermail: Noch keine Scheinkennung fuer Adresse
                          vergeben
  ballot                  Template fuer einen Wahlschein
  ballot-personal         Template fuer personalisierten Wahlschein
  ballot-request          Template fuer eine Wahlscheinanforderung
  bdsg-error              Fehlermail: Datenschutzklausel nicht akzeptiert
  bouncelist              Template fuer Liste der ungueltigen Mailadressen
  cancelled               Template fuer Bestaetigung der Stimmannullierung
  invalid-account         Fehlermail: Fragwuerdige Mailadresse (Role Account)
  invalid-name            Fehlermail: Kein gueltiger Name in Mail/Wahlschein
                          gefunden
  mailheader              Template fuer den Header von Mails an die Waehler
  multiple-votes          Fehlermail: Widerspruechliche Stimmen im Wahlschein
  no-ballot               Fehlermail: Kein Wahlschein in Mail gefunden
  no-ballotid             Fehlermail: Keine Wahlscheinkennung gefunden
  no-votes                Fehlermail: Keine Stimmen abgegeben
  result-multi            Template fuer ein Wahlergebnis mit mehreren Gruppen
  result-single           Template fuer ein Wahlergebnis mit einer Gruppe
  result-proportional     Template fuer ein Wahlergebnis, bei dem das Verhaeltnis
                          oder die Differenz von Ja- und Nein-Stimmen entscheidet
                          (z.B. Moderationsnachwahlen, "proportional=1" gesetzt)
  rule-violated           Fehlermail: Wahlregeln aus usevote.rul verletzt
  voterlist               Template fuer eine Waehlerliste (2. CfV)
  votes-multi             Template fuer eine Stimmenliste mit mehreren Gruppen
  votes-single            Template fuer eine Stimmenliste bei einer Gruppe
  wrong-ballotid          Fehlermail: Falsche Wahlscheinkennung angegeben

* Beim Programmlauf erstellte Dateien (Name ist konfigurierbar):

ergebnis.alle     Saemtliche Einzelergebnisse zusammengefasst (wird 
                  bei jedem Lauf von uvvote.pl neu erstellt)
errors.log        Fehlermeldungen, die beim Programmlauf auftauchen,
                  werden hier abgelegt. Normalerweise bleibt die Datei
                  leer, ansonsten wird beim Programmende eine Warnung
                  mit Verweis auf die Datei ausgegeben.
uidlcache         Eindeutige IDs der abgerufenen Mails (bei Benutzung
                  von POP3). Darf waehrend einer laufenden Abstimmung
                  keinesfalls geloescht werden, um Mehrfachzaehlung von
                  Stimmen zu verhindern.
uidlcache_req     dto, fuer die Mailbox mit den Wahlscheinanforderungen
                  (bei Verwendung von personalisierten Wahlscheinen)
uidlcache_bounce  dto, fuer die Mailbox mit den Bounces (wird von
                  uvbounce.pl ausgewertet)
usevote.lock      Temporaere Lockdatei, um gleichzeitiges Ausfuehren
                  mehrerer Instanzen zu verhindern. Kann (falls vorhanden)
                  gefahrlos geloescht werden, wenn gerade keines der
                  Usevote-Scripts laeuft.

* Folgende Unterverzeichnisse werden von Usevote im aktuellen
  Verzeichnis (CWD) angelegt:

fertig/           Verzeichnis fuer Archivierung verarbeiteter Dateien
tmp/              Verzeichnis fuer temporaere Dateien

* Von Usevote dort erstellte Dateien:

ack.*             Bestaetigungsmails (in tmp/)
ack.control       Steuerungsdatei fuer Bestaetigungsmails (in tmp/)
domail            Shellscript zum Verschicken der Mails (in tmp/)
ergebnis.*        Ergebnisdateien einzelner Durchlaeufe (zunaecht in tmp/,
                  spaeter nach fertig/ verschoben und archiviert)
stimmen.*         Archivierte Stimmendateien (dto.)


5. Anfangs-Konfiguration
========================
 
Zuerst solltest Du "usevote.cfg" fuer Dein System anpassen (Details
dort in den Kommentarzeilen und weiter hinten in dieser Dokumentation).
Unter Windows werden die Regular Expressions fuer die Stimmenerkennung
moeglicherweise lauter unlesbare Zeichen enthalten (anderer Zeichensatz),
dort sollten saemtliche in Namen vorkommende Umlaute und Buchstaben mit
Accents etc. aufgefuehrt werden. Weiter ist bei Nutzung von Windows zu
beachten, dass das Kommando zum Loeschen des Bildschirms "cls" und nicht
"clear" heisst. Dazu gibt es auch eine Einstellung in usevote.cfg. Den
standardmaessig eingestellten Pager "less" gibt es unter Windows zunaechst
nicht, more ist aber so buggy, dass man sich am besten "less" fuer
Windows herunterladen sollte:
http://www.greenwoodsoftware.com/less/less381d.zip

Im Unterverzeichnis "templates" findest Du Vorlagen, die fuer die
einzelnen Bestaetigungstexte, Mails, Wahlscheine und Waehlerlisten
verwendet werden. Hier kannst Du unter Beachtung der Syntax (siehe
gesonderte Dokumentation) alle Texte an Deinen Geschmack und Deine
Beduerfnisse anpassen.


6. Konfiguration fuer einzelne Abstimmungen
===========================================
 
Fuer jede Abstimmung muss eine eigene Konfigurationsdatei geschrieben
werden. Aendere einfach usevote.cfg entsprechend der Regeln fuer die
betreffende Abstimmung. Falls Du haeufiger Wahlleiter spielst, solltest
Du Dir eine globale Konfigurationsdatei mit Standardeinstellungen
(z.B. als ~/.usevote-defaults.cfg) anlegen und in der usevote.cfg nur
noch die Einstellungen setzen, die sich fuer jede Abstimmunge aendern.
Die globale Datei kann am Anfang der usevote.cfg mit folgender Zeile
eingebunden werden:

include ~/.usevote-defaults.cfg

Zu beachten ist aber, dass jeweils die letzte Definition einer Option
benutzt wird. Die usevote.cfg sollte daher wirklich nur noch
abstimmungsspezifische Einstellungen enthalten, um nicht versehentlich