Fix UVreadmail.pm

[usenet/usevote.git] / README

UseVoteGer 4.11  (c) 2001-2012 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.11 - 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)


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
die globalen Optionen zu überschreiben.

Ausserdem muss die Datei "usevote.rul" geprueft werden. Wenn Deine
Abstimmung irgendwelche speziellen Regeln enthaelt (z.B. man kann
nur fuer Gruppe x stimmen, wenn man auch fuer y gestimmt hat, oder man
muss fuer den .misc-Abschnitt stimmen, wenn man fuer irgendeinen
anderen Abschnitt gestimmt hat), dann solltest Du diese Datei lesen
und entsprechend aendern. Allerdings empfiehlt es sich, bereits im
RfD deutlich auf die Regeln hinzuweisen, die zur Anwendung kommen sollen.
Die eingegebenen Regeln koennen dann mit "uvvote -t" getestet werden.

Es ist auch moeglich, mehrere Abstimmungen gleichzeitig durchzufuehren,
ohne die .pl und .pm Dateien jedesmal mitzukopieren. Folgende Dateien
sollten im Abstimmungsverzeichnis vorhanden sein (notwendig ist nur
usevote.cfg, darin können alle anderen Pfade angepasst werden):

ballot.sample
bdsgtext.cfg
mailpatterns.cfg
messages.cfg
scheinkennungen
usevote.cfg
usevote.rul

Ggf. sollte das "templates"-Verzeichnis kopiert werden, falls
individuelle Templates fuer einzelne Abstimmungen verwendet werden.

Außerdem muessen i.d.R. einige Pfade in der usevote.cfg angepasst
werden. Dadurch ist auch die Angabe eines anderen Verzeichnisses
fuer einige der oben genannten Konfigurationsdateien moeglich,
falls diese zentral gepflegt werden sollen (z.B. messages.cfg und
mailpatterns.cfg).

Damit die Usevote-Perlmodule gefunden werden, sollten sie im
selben Verzeichnis wie die Programmdateien liegen bleiben. Ansonsten
muss eine Umgebungsvariable gesetzt werden:

PERL5LIB=..

.. steht für das übergeordnete Verzeichnis. Ggf. muss hier ein
absoluter Pfad eingetragen werden, wenn das Abstimmungsverzeichnis
kein Unterverzeichnis des Usevote-Verzeichnisses ist.

Je nach Betriebssystem kann die obige Zeile etwas anders aussehen,
unter Windows sollte z.B. "SET PERL5LIB=C:\PERL\USEVOTE" in die
autoexec.bat aufgenommen oder sonstwie ausgeführt werden (Pfad
natürlich entsprechend anpassen).


7. Wahlschein generieren
========================
 
Der Wahlschein ist ein Abschnitt des CfV, den die Leute zur Stimmabgabe
ausfuellen und zurueckschicken sollen. Am einfachsten erzeugst Du
diesen nach Anpassung der Konfiguration und ggfls. des Templates
mit "uvballot.pl". Folgendes Format ist erforderlich:

#1  [ Stimme ]  
#2  [ Stimme ]
[...]

Eine zusaetzliche Beschreibung rechts daneben macht es dem Waehler
einfacher, ist aber fuer Usevote nicht zwingend erforderlich. Wichtig
sind nur die fortlaufenden Nummern, die entsprechend der Eintraege
in usevote.cfg zugeordnet werden.

Je nach Konfiguration koennen weitere Zeilen noetig sein, dazu spaeter.

Als Stimme in den eckigen Klammern werden diverse Strings erkannt,
die in usevote.cfg definiert werden koennen. JA, NEIN und ENTHALTUNG
sind Standard, einige Abwandlungen sind ebenfalls moeglich.
Zusaetzlich kann ANNULLIERUNG verwendet werden, um eine schon abgegebene
Stimme zu loeschen und somit nicht im Result aufzutauchen.

Bei der Verwendung von persoenlichen Wahlscheinen (Abschnitt 6a der
Wahlregeln fuer de.*) ist das Vorgehen etwas anders, siehe hierzu
den gesonderten Abschnitt weiter hinten.


8. Stimmen verarbeiten
======================

Falls POP3 nicht benutzt werden soll (siehe usevote.cfg), werden alle
Wahlmails zu einer Abstimmung aus einer Mailboxdatei gelesen
(Name/Pfad der Datei in usevote.cfg einstellbar). Standardmaessig
wird das Unix-Mailboxformat erkannt, dieses ist aber ueber "mailstart"
in usevote.cfg konfigurierbar (bei komplett anderen Formaten muesste
der Quellcode geaendert werden).

Wechsele nun in das Verzeichnis, in dem die passenden
Konfigurationsdateien liegen (normalerweise werden diese aus
dem aktuellen Verzeichnis gelesen, was mehrere gleichzeitige
Verfahren moeglich macht) und starte uvvote.pl. Bei Problemen
mit einzelnen Stimmen wirst Du interaktiv durch Menues gefuehrt.
Meistens gibt es folgende Moeglichkeiten, die durch die
eingeklammerten Buchstaben und Zahlen aufgerufen werden koennen:

(0) Wahlschein mit Original vergleichen (diff)
(1) Anzeigen der Wahlmail

Bestaetigen oder Aendern von Wahlschein-Eigenschaften:
(2) Mailadresse
(3) Waehlername
(4) Stimmen
(5) Scheinkennung
(6) Datenschutzklausel
(7) Abstimmung

(i) Diese Stimme ignorieren (ohne Benachrichtigung verwerfen)
(w) Weiter

Teilweise gibt es Unteroptionen:
  (a) OK (Zweifel sind unbegründet, ist alles in Ordnung)
  (b) Aendern (z.B. wenn der Realname von Usevote nicht vollstaendig
      erkannt wurde)
  (c) Ungueltig (es handelt sich nach Deinem Ermessen nicht um
      eine gueltige Stimmabgabe)

Nun solltest Du zunaechst mit (1) die Mail ansehen und anhand
der bemaengelten Punkte entscheiden, ob der Wahlschein gueltig
oder ungueltig ist bzw. welche Maengel tatsaechlich zutreffen.
Mit (0) kannst Du einen Dateivergleich zu einem vorher hinterlegten
Musterwahlschein ausführen ("diff"), um Aenderungen/Fehler schneller
zu sehen.

Mit den Optionen (2) bis (7) kannst Du einzelne Eigenschaften
des Wahlscheins nachbessern (wenn Usevote z.B. einen Namen oder
eine Stimme nicht korrekt erkannt hat) oder auch einfach die
Korrektheit bestaetigen.

Wenn Du alle oben auf der Seite aufgelisteten Maengel beseitigst,
indem Du die entsprechenden Optionen waehlst, wird die Stimme
akzeptiert. Bleiben Zweifel unausgeraeumt, wird eine entsprechende
Fehlermail verschickt (Du erhaeltst dann noch eine gesonderte
Warnung).

Zum Schluss kannst Du (w) wählen, um fortzufahren. Möchtest Du,
dass eine Stimme komplett ignoriert wird (weil es sich z.B.
um Spam handelt), kannst Du (i) waehlen und die folgende
Sicherheitsfrage mit "JA" beantworten.

Ist uvvote.pl durchgelaufen, koennen im Unterverzeichnis tmp/
(wird ebenfalls aktuellen Verzeichnis angelegt!) die ermittelten
Ergebnisse und erzeugten Mails an die Waehler noch einmal geprueft
werden. Ist alles in Ordnung, werden mittels "uvvote.pl clean"
die Mails verschickt und die Ergebnisse gespeichert sowie die
Originalmails archiviert. Hierzu wird das Verzeichnis fertig/
verwendet.

Falls der komplette uvvote-Lauf verworfen werden soll, kann
die Datei mit den Waehlermails (stimmen-xyz im tmp-Verzeichnis,
xyz entspricht der aktuellen Unixtime waehrend des Durchlaufs)
wieder an den urspruenglichen Platz zurueckkopiert werden
(bei POP3: fuer den Neuversuch POP3 abschalten und die 
Maildatei einlesen lassen, da auf dem Server die Mails
moeglicherweise geloescht wurden) und das komplette tmp-Verzeichnis
geloescht werden. Anschliessend den uvvote-Lauf erneut durchfuehren.
Wichtig ist nur, dass das Verzeichnis fertig/ waehrend der ganzen
Abstimmung mitsamt seines Inhaltes erhalten bleibt.

Noch ein kurzes Wort zum Verschicken der Mails: Jede Mail wird
in einer gesonderten durchnummerierten Datei (ack.1, ack.2, ...)
gespeichert, zusaetzlich wird eine Steuerungsdatei ("ack.control")
erzeugt, welche zu jeder Mail Dateinamen und Empfaenger auflistet.
Je nach Einstellung werden die Mails dann per SMTP verschickt oder
es wird ein Shellscript ("domail") erzeugt, welches nach und 
nach die Mails in Sendmail einspeist. Zwecks Serialisierung ist
in usevote.cfg die Einstellung "sleepcmd" konfigurierbar,
normalerweise wird ein "sleep 1" nach jeder Mail ausgefuehrt.
Das Verschicken der Mails (und damit ggfls. der Aufruf von "domail")
erfolgt automatisch mit "uvvote.pl clean".

Unter Windows ist nur SMTP moeglich, es sei denn, es gibt
die Befehle sendmail, sleep und rm ;-)


9. Unzustellbare Bestaetigungen
===============================

Leider kommt es immer mal wieder vor, dass jemand bei der Abstimmung
eine ungueltige Mailadresse angegeben hat. In diesem Fall erhaeltst Du
einen Bounce an die Absenderadresse zurueck (diese laesst sich in
usevote.cfg mit der Option "envelopefrom" einstellen bzw. bei 
direkten Aufruf eines Mailers über die entsprechende Kommandozeilenoption
in der mailcmd-Einstellung, z.B. bei Sendmail -f). Du solltest
solche Fehlermails in einer gesonderten Datei speichern oder in
einem gesonderten POP3-Postfach halten und beim Erstellen
des 2. CfVs und des Results uvbounce.pl aufrufen.

Ausgegeben wird von uvbounce.pl eine Liste mit ungueltigen Adressen,
die einfach an den Abschnitt "ungueltige Stimmen" des 2. CfVs bzw.
Results angehaengt werden kann. Nicht vergessen, die Stimmen manuell
aus der Liste der gueltigen Stimmen zu loeschen (falls Du die
Policy verfolgst, nur Stimmen mit gueltiger Absenderadresse zu werten,
was empfehlenswert ist) und bei Bedarf das Ergebnis zu korrigieren!


10. 2.CfV / Result
===================

Zum Erstellen des 2. CfVs kannst Du erst einmal den 1. CfV als Vorlage
benutzen. Am Ende sollte allerdings eine Liste der Personen folgen,
die bereits abgestimmt haben. Diese laesst sich mit "uvcount.pl -l"
erzeugen. Moeglicherweise fragt uvcount.pl wegen scheinbar doppelter
Stimmabgaben nach und bietet an, eine oder beide Stimmen zu ignorieren.
Du solltest das dann genauer untersuchen und die passende Wahl treffen.

Vorsicht bei doppelten Namen: Es gibt einige doppelt vorkommende
Namen, hinter denen sich voellig unterschiedliche Personen
verbergen! Die Mailadresse sollte in solchen Faellen Auskunft
geben koennen, notfalls einmal nachfragen.

Das Endergebnis kannst Du mit "uvcount.pl -r" ausgeben lassen.
Bei Verfahren mit mehreren Abstimmungspunkten wird automatusch
das folgende tabellarische Format verwendet:

 Ja  Nein : 2/3? >=60? : ang.? : Gruppe
==== ==== : ==== ===== : ===== : =======================================
 100   70 : Nein   Ja  :  Nein : Einrichtung von xyz

Bei Abstimmungen ueber nur einen Punkt gibt es auch die Moeglichkeit,
einen einfachen beschreibenden Text zu verwenden:
"Es gab 100 JA und 70 NEIN-Stimmen ...".

Falls in usevote.cfg die Einstellung "multigroup = 1" gesetzt ist,
wird immer die tabellarische Form gewaehlt, bei "multigroup = 0"
benutzt uvcount.pl bei nur einem Abstimmungspunkt den beschreibenden
Text. Überschreiben laesst sich dieses mit Aufrufparametern:

uvcount.pl -r -m     = Tabellarisch (m = multigroup)
uvcount.pl -r -o     = Text (o = onegroup)

Falls in usevote.cfg die Option "proportional = 1" aktiviert ist,
wird standardmaessig folgendes Ausgabeformat angewandt:

 Ja  Nein : J>=N? Ja/Nein : ang.? : Gruppe
==== ==== : ===== ======= : ===== : ====================================
 100   70 :  Ja    1.429  :       : Einrichtung von abc
  80   90 : Nein   0.888  :       : Einrichtung von xyz

Das genaue Aussehen ist im Template "result-proportional" aenderbar,
die Bedingungen und Auswertungsformeln sind ueber usevote.cfg
einzustellen (prop_formula und condition1). Die Spalte "ang.?" muss
in diesem Fall manuell ausgefüllt werden, da manchmal auch mehrere
Abstimmungsgegenstände angenommen werden, z.B. bei Moderationsnachwahlen
für verschiedene Posten.

Die Waehlerliste mit abgegebenen Stimmen erzeugst Du mit
"uvcount -v". Diese Option laesst sich auch mit -r kombinieren,
so dass Du Dir das doppelte Aussortieren von Duplikaten sparst.
Wichtig: Diese Liste darf erst im Result veroeffentlicht werden,
nicht im 2. CfV!

Falls ein trivialer Schutz vor Spammern gewuenscht ist, koennen durch
eine Aenderung in den Template "voterlist", "votes-single", "votes-multi"
und "bouncelist" alle Mailadressen verfremdet werden. Entweder Du fuegst
folgende Definition ein:

mail            := value mail | replace '@' ' -at - '

Oder Du veraenderst direkt die vorgegebenen Formate, indem Du
die Mailadresse mit Hilfe des Pipe-Symbols durch die replace-Funktion
schickst:

multi-line := value mail | replace '@' ' -at- ' | justify-behind name 72

Die Replace-Funktion erwartet wie im Beispiel gezeigt zwei Werte,
die zu ersetztende Zeichenfolge (hier das '@') und eine neue Zeichenfolge,
die statt dessen eingesetzt werden soll und frei gewaehlt werden kann.

Wie bereits beschrieben, sollte am Ende des 2. CfVs bzw. Results noch die
Liste der gebouncten Mailadressen angehaengt werden (z.B. mit dem Programm
uvbounce.pl) und bei Bedarf die urspruenglichen Stimmen geloescht und das
Ergebnis korrigiert werden.


11. Datenschutz
===============

Zum Schutz der deutschen Wahlleiter wurden spezielle Klauseln
aufgenommen, die vom Waehler die Erlaubnis zur Verarbeitung
der Stimme verlangen. Die Option "bdsg" in usevote.cfg schaltet
diese Sonderbehandlung ein oder aus. Folgende Besonderheiten
gelten bei Aktivierung:

- Im Wahlschein ist ein spezieller Hinweistext enthalten, der
  aus der Datei bdsgtext.cfg genommen wird. Beim Verarbeiten
  abgegebener Stimmen wird der Abschnitt wieder mit der Datei
  verglichen. Fehlt er oder wurde er veraendert, wird der
  Wahlschein dem Wahlleiter zur Kontrolle vorgelegt.
  Die Fehlerpruefung ignoriert Quote- und Leerzeichen sowie
  Zeilenumbrueche, kann aber versagen, wenn dem Quotezeichen
  Initialen vorangestellt sind (wie in manchen Mailboxnetzen
  ueblich) oder eine Silbentrennung ueber den Text gelaufen ist.

- Ausserdem enthaelt der Wahlschein eine spezielle Frage,
  die mit JA zu beantworten ist. Anderenfalls muss ebenfalls
  Kontrolle durch den Wahlleiter erfolgen. Der Text dieser
  Frage ist ueber usevote.cfg einzustellen.

Erfolgt eine derartige Kontroll-Vorlage beim uvvote.pl-Lauf,
sollte der Wahlleiter sich den Wahlschein genau anschauen
und dann entweder im Menue die Option (6)(a) waehlen oder
mit (w) fortfahren. Im letzteren Fall wird die Stimme
verworfen und eine Hinweismail zurueckgeschickt.

Wenn eine Wahlbestaetigung veraendert und zurueckgeschickt
wird, fehlt der entsprechende Datenschutzhinweis. Da in
diesem Fall die Zustimmung aber bereits bei der ersten
Stimmabgabe gegeben wurde, kann der Wahlleiter beruhigt
die Korrektheit wie oben beschrieben bestaetigen.


12. Personalisierte Wahlscheine
===============================

Die Wahlregeln fuer de.* sehen im Abschnitt 6a ein Verfahren
mit persoenlichen Wahlscheinen vor, die mit einer speziellen
Kennung versehen mehr Sicherheit vor Manipulation bieten.

Um dieses Verfahren einzuschalten, muss zunaechst die Option
"personal = 1" in usevote.cfg gesetzt werden und das Template
"ballot-personal" im Unterverzeichnis "templates" um den Text
des CfVs erweitert werden (einfach statt des von Sternchen
umrandeten Kommentars in der Datei einfuegen). Bitte eventuell
im Text vorkommende eckige Klammern wie folgt unschaedlich
machen: \[Text\] (Backslash voranstellen), da in den Templates
diese Klammern spezielle Bedeutungen haben (siehe gesonderten
Abschnitt zu dem Thema in dieser Datei).

Der gepostete CfV enthaelt i.d.R. nur einen Dummy-Abschnitt
mit Hinweis auf die gesonderte Wahlscheinanforderung. So ein
Abschnitt kann mit uvballot.pl generiert werden.

Der dana-Moderation sollte beim Einreichen des CfVs auch
ein Dummy-Wahlschein mitgesendet werden, wie er bei der
Wahlscheinanforderung verschickt wird. Dieser laesst sich mit
"uvcfv.pl -t" erzeugen.

Die eingehenden Wahlscheinanforderungen sollten an eine
spezielle Mailadresse gehen und dann mit uvcfv.pl verarbeitet
werden. Je nach Konfiguration in usevote.cfg werden die
Mails aus einer Mailboxdatei oder per POP3 eingelesen und jeweils
mit einem personalisierten Wahlschein beantwortet. Bitte vor
dem Posten des CfVs einen Test durchfuehren, um sicherzustellen,
dass die generierten Wahlscheine korrekt sind und auch bei
der Auswertung akzeptiert werden (hierbei wird die speziell
eingefuegte Wahlscheinkennung in Verbindung mit der Absenderadresse
geprueft).


13. Die einzelnen Programme
===========================

uvballot.pl
  Generiert den Wahlschein fuer den CfV. Bei personalisierten
  Wahlscheinen (personal = 1 in usevote.cfg) wird nur ein Dummy-
  Abschnitt mit Hinweisen zur Wahlscheinanforderung ausgegeben.

  Die Vorlage fuer den Wahlschein ist im templates-Unterverzeichnis
  konfigurierbar:
  - ballot               Standard-Wahlschein (personal=0)
  - ballot-request       Dummy-Abschnitt mit Hinweisen zur
                         Wahlscheinanforderung (personal=1)
  - ballot-personal      Wahlschein mit Scheinkennung, wird von
                         uvcfv.pl verwendet

  Aufrufparameter:

  -c config_file         liest die Konfiguration aus config_file
                         (usevote.cfg falls nicht angegeben)
  -h                    
  --help                 zeigen einen Hilfetext an


uvbounce.pl
  Liest Bounces aus den uebergebenen Dateien oder aus einer POP3-
  Mailbox ein (Verhalten haengt von usevote.cfg ab) und generiert
  eine Liste von unzustellbaren Adressen, die an den 2. CfV oder das
  Result angehaengt werden kann. Falls POP3 in usevote.cfg
  eingeschaltet und die Option -f (siehe unten) nicht benutzt wurde,
  werden die uebergebenen Dateinamen ignoriert.

  Die Mails werden aus den uebergebenen Mailboxdateien geloescht
  und statt dessen in einer neuen Datei mit der Erweiterung ".processed"
  gespeichert.

  Die Vorlage fuer die ausgegebene Liste ist im templates-
  Unterverzeichnis konfigurierbar (Datei "bouncelist").

  Aufrufparamter:

  -c config_file         liest die Konfiguration aus config_file
  -f dateiname(n)   
  --file dateiname(n)    lesen die Bounces aus den uebergebenen Dateien,
                         auch wenn in der Konfigurationsdatei POP3
                         eingeschaltet ist. Diese Option wird benoetigt,
                         falls zwar die Stimmzettel per POP3 eingelesen
                         werden sollen, nicht aber die Bounces.
                         Die Dateinamen werden durch Leerzeichen getrennt.
  -h
  --help                 zeigen einen Hilfetext an


uvcfv.pl

  Liest Mailboxen ein und beantwortet alle Mails mit personalisierten
  CfVs (falls personal=1 in usevote.cfg).

  Die Vorlage fuer die ausgegebene Liste ist im templates-
  Unterverzeichnis konfigurierbar (Datei "ballot-personal").

  Aufrufparamter:

  -c config_file        liest die Konfiguration aus config_file
                        (usevote.cfg falls nicht angegeben)
  -t
  --test                gibt einen Dummy-Wahlschein mit Scheinkennung
                        an der Standardausgabe aus, zur Pruefungszwecken
  -h
  --help                zeigen einen Hilfetext an


uvcount.pl

  Zaehlt Stimmen und gibt Waehlerlisten aus. Dient zur Erstellung
  von 2.CfV und Result.

  Es werden die folgenden Vorlagen aus dem templates-Unterverzeichnis
  benutzt:

  - result-multi       Ergebnisauszaehlung bei mehreren Gruppen
  - result-single      Ergebnisauszaehlung bei nur einem Abstimmungs-
                       gegenstand (nicht tabellarisch, sondern im
                       Fliesstext), falls in usevote.cfg multigroup=0
                       gesetzt ist oder die Option -o verwendet wird
                       (siehe unten)
  - voterlist          Reine Auflistung der bisherigen Waehler ohne
                       Stimmen (fuer 2. CfV)
  - votes-multi        Stimmenliste im Mehrgruppenformat (eine Liste
                       mit allen Waehlern, rechts daneben die jeweils
                       abgegebenen Stimmen)
  - votes-single       Stimmenliste im Eingruppenformat (getrennte
                       Listen mit Ja-, Nein- und Enthaltungsstimmen)

  Aufrufparamter:

  -c config_file      liest die Konfiguration aus config_file
                      (usevote.cfg falls nicht angegeben)
  -f result_file      liest die Stimmen aus result_file (ueberschreibt
                      die "resultfile"-Angabe aus der Konfigurationsdatei)
  -l
  --list              Geben eine Liste aller Waehler aus (ohne Stimmen).
  -v
  --voters            Wie --list, aber mit Angabe der abgegebenen Stimmen.
  -r
  --result            Ausgabe des Endergebnisses (kann mit --list oder
                      --voters kombiniert werden).
  -m
  --multigroup        Benutzt auch bei Eingruppenabstimmungen das
                      Mehrgruppenformat beim Endergebnis (ueberschreibt
                      die Einstellung aus usevote.cfg).
                      Nur in Kombination mit --result verwendbar,
                      schliesst --onegroup aus.
  -o
  --onegroup          Benutzt bei Eingruppenabstimmungen immer das
                      Eingruppenformat beim Endergebnis (ueberschreibt
                      die Einstellung aus usevote.cfg).
                      Nur in Kombination mit --result verwendbar,
                      schliesst --multigroup aus.
  -n
  --nodup             Verzichtet auf das Aussortieren von doppelten
                      Stimmabgaben. Nicht empfohlen!
  -h
  --help              zeigen einen Hilfetext an



uvvote.pl

  Liest Mailboxen aus einer Datei oder per POP3 ein wertet die Mails
  als Stimmzettel aus. Erst beim Aufruf mit der Option "clean" werden
  die Ergebnisse endgueltig gespeichert und die Bestaetigungsmails
  verschickt.

  Es werden diverse Vorlagen aus dem templates-Unterverzeichnis
  benutzt, um Bestaetigungs- und Fehlermails zu generieren.

  Aufrufparameter:

  -c config_file       liest die Konfiguration aus config_file
                       (usevote.cfg falls nicht angegeben)
  -t
  --test               fuehrt einen Test der Konfiguration durch und
                       gibt das ermittelte Ergebnis aus.
  -h
  --help               zeigen einen Hilfetext an



14. Die Konfigurationsdateien
=============================

mailpatterns.cfg
----------------

Diese Datei enthaelt einen regulaeren Ausdruck (Perl-Syntax) pro
Zeile. Passt die Mailadresse eines Abstimmenden auf eines der Muster,
wird dem Wahlleiter bei der Auswertung eine Warnung angezeigt.
In der Regel kann man diese ignorieren, weil heutzutage viele
Privatleute ihre eigene Domain haben und Role-Accounts wie news@
benutzen. Sieht man aber so etwas wie news@t-online.de ist
Vorsicht angebracht und man sollte durch Auswahl von "(W)eiter" 
die Stimme ungueltig werten und eine entsprechende Fehlermail
zurueckschicken lassen.


messages.cfg
------------

Hier sind alle kuerzeren Texte enthalten, die Usevote ausgibt,
unabhaengig davon, ob sie nur dem Wahlleiter bei der Programmausfuehrung
ausgegeben werden oder in persoenlichen Mails bzw. dem Result
auftauchen. Laengere Textpassagen sind als eigene Dateien im
"templates"-Verzeichnis zu finden und bieten weitergehende
Formatierungsmoeglichkeiten.

Jede Zeile in der messages.cfg besteht aus einem Identifier, einem
Gleichheitszeichen und dem eigentlichen Text. Der Identifier ist
grundsaetzlich in Grossbuchstaben gehalten und vom Programmcode fest
vorgegeben. Aenderungen duerfen nur rechts vom Gleichzeichen vorgenommen
werden, wenn Dir z.B. Formulierungen nicht gefallen oder Du anders-
sprachige Ausgaben haben moechtest.

Variablen sind ueber ${VARIABLE} einzubauen, allerdings sind die
Variablennamen und deren Inhalte vom Programmcode vorgegeben und
sollten beibehalten werden. Es gibt keine vordefinierten Variablen,
die Du selbst einbauen kannst, es sei denn, Du erweiterst den
Programmcode an der entsprechenden Stelle.

Die einzigen Texte, die fest im Programmcode stehen, sind die
Hilfetexte der einzelnen Programme (ueber die Option -h oder --help
aufrufbar) sowie die Startmeldungen (Copyright etc.) und initiale
Fehlermeldungen (usevote.cfg oder messages.cfg nicht gefunden,
ungueltige oder falsch kombinierte Aufrufparameter).


usevote.rul
-----------

Mit dieser Datei koennen spezielle Regeln fuer eine gueltige Stimmabgabe
bei Mehrgruppenabstimmungen erstellt werden, z.B. dass man Punkt 3 oder 4
waehlen muss, wenn man fuer Punkt 2 gestimmt hat (quasi als weitergehende
Auswahlmoeglichkeit). Solche Regeln verkomplizieren aber die Abstimmung
und sollten nur in Ausnahmefaellen benutzt werden. Urspruenglich gedacht
war diese Moeglichkeit z.B. fuer .misc Gruppen, die zwangsweise bei einer
Aufteilung mit angelegt werden mussten. Dadurch, dass das in den
Wahlregeln fuer de.* als Automatismus eingebaut ist, kann man sich
so etwas meistens sparen. Fuer den Fall, dass bei einer vorgeschlagenen
neuen Gruppe der Name noch unklar ist, gibt ebenfalls das Benutzen
von speziellen Wahlregeln wenig Sinn, da man auch eine Meinung ueber
den Gruppennamen haben kann, wenn man eigentlich gegen die Gruppe ist.

Wenn Du aber ein Verfahren betreust, in dem Du solche Sonderregeln
benoetigst, kannst Du eine Regel pro Zeile in der folgenden Syntax schreiben:

if .jjjjj then J....

Eine Regel beginnt immer mit "if", und danach folgen eine Anzahl Symbole;
diese Anzahl muss gleich der Anzahl der Gruppen sein, ueber die abgestimmt
wird. Oben geht es also um eine Abstimmung ueber sechs Gruppen.
Die Symbole hinter "if" geben an, in welchem Fall diese Regel Anwendung
finden soll. Falls sie zutrifft, wird die Bedingung hinter "then"
geprueft (dort muessen nochmal so viele Symbole folgen, wie Gruppen
im Wahlschein vorkommen). Ist diese Bedingung nicht erfuellt, wird
der Wahlschein dem Wahlleiter als regelverletzend vorgelegt, und
wenn diese mit "(w)eiter" den Fehler bestaetigt, wird eine entsprechende
Fehlermeldung zurueckgeschickt und die Stimme als ungueltig gewertet.

Folgende Symbole sind erlaubt:

   J   eine JA-Stimme
   N   eine NEIN-Stimme
   E   eine Enthaltung
   S   eine JA- oder NEIN-Stimme
   H   eine Enthaltung oder JA-Stimme
   I   eine Enthaltung oder NEIN-Stimme
   .   egal (Ja, nein oder Enthaltung)
   j   eine oder mehrere der markierten Gruppen hat JA-Stimme
   n    ""   ""    ""     ""     ""       ""    ""  NEIN-Stimme
   e    ""   ""    ""     ""     ""       ""    ""  Enthaltung
   s    ""   ""    ""     ""     ""       ""    ""  Ja- oder Nein-Stimme
   h    ""   ""    ""     ""     ""       ""    ""  Enthaltung oder Ja-Stimme
   i    ""   ""    ""     ""     ""       ""    ""  Enthaltung oder Nein-Stimme

Hier noch ein Beispiel:
    if S... then .ss.
    if .S.. then ..E.
    if ..S. then .E..

Diese Regeln sagen: Wer fuer die erste Gruppe abstimmt, der muss auch
fuer die zweite und dritte Gruppe abstimmen - egal wie. Ausserdem muss er
(Regeln 2 und 3) sich bei 3 enthalten, wenn er bei 2 eine Stimme abgibt
und umgekehrt. Die vierte Gruppe wird hier gar nicht betroffen.


usevote.cfg
-----------

Dieses ist die zentrale Konfigurationsdatei fuer Usevote. Einige
Einstellungen sind nur einmal auf das System und Deine Gewohnheiten
anzupassen, andere muessen fuer jede Abstimmung geaendert werden.
Alle Einstellungen sind mit mehr oder weniger sinnvollen
Standardwerten vorgegeben, die sich bei leerer usevote.cfg mittels
"uvvote.pl -t" ermitteln lassen.

Es lassen sich durch eine Zeile "include dateiname" weitere 
Konfigurationsdateien einbinden. Die Stelle, an der dieses geschieht,
ist dabei wichtig, da die usevote.cfg von oben nach unten gelesen
wird (zusätzlich eingebundene Konfigurationsdateien werden an der
Stelle der "include"-Zeile eingefügt) und bei mehrmals vorkommenen
Optionen der jeweils letzte gesetzte Wert benutzt wird.
Daher sollte eine Datei mit systemweiten Defaults am besten am
Anfang der usevote.cfg eingebunden werden, die dort gesetzten
Optionen sollten aber unbedingt aus der usevote.cfg geloescht werden,
damit die systemweiten Einstellungen nicht gleich wieder ueberschrieben
werden.

Das Format ist allgemein:

Option = Wert

Der Wert muss in manchen Faellen 0 (=aus) oder ungleich 0 (=an) sein,
in anderen Faellen muss eine exakte Zahl oder Zeichenkette eingegeben
werden. 

Alles, was hinter einem # Zeichen steht, wird als Kommentar gewertet
und ignoriert. Steht hinter einem Wert so ein Kommentar, wird
normalerweise alles bis zum Kommentarzeichen noch in den String
einbezogen. In so einem Fall sollte der Wert von Anfuehrungszeichen
umschlossen werden. Im folgenden Beispiel wird ein Dateiname
definiert:

# Der Dateiname endet mit 10 Leerzeichen (bis zum Kommentarzeichen):
tpl_mailheader = mailheader          # Kommentar

# Der Dateiname enthaelt keine Leerzeichen, da mit Anfuehrungsstrichen
# begrenzt:
tpl_mailheader = "mailheader"        # Kommentar

Folgt kein Kommentar in der selben Zeile, koennen die Anfuehrungsstriche
weggelassen werden.

Hier eine Auflistung der immer anzupassenden Optionen
(BOOL bedeutet, dass 0 (aus) oder 1 (an) eingetragen werden muss):

votename         Name der Abstimmung
group1           Erster Abstimmungsgegenstand
group2           Zweiter (und so weiter durchnummerieren)
sampleballotfile Datei mit Musterwahlschein aus dem CfV fuer Dateivergleich (diff)
votefile         Mailbox mit eingehenden Stimmen (falls POP3 ausgeschaltet)
mailboxtype      Typ der Mailbox (mbox, maildir)
personal         Personalisierte Wahlscheine verwenden? [BOOL]
                 (siehe gesonderten Abschnitt weiter oben)
voteaccount      Mailadresse, unter der abgestimmt werden kann
                 (Reply-To im CfV auf diese Adresse setzen)
requestfile      Datei mit Anforderungsmails bei "personal=1", falls
                 POP3 ausgeschaltet ist
bdsg             Datenschutzklausel generieren und auf deren Existenz 
                 pruefen? [BOOL] (siehe gesonderten Abschnitt weiter oben)
replyto          Reply-To Header auswerten? [BOOL] (nicht empfohlen und in
                 de.* von den GVV nicht praktiziert)
voteack          Jede Stimme mit einer Bestaetigungsmail beantworten? [BOOL]
                 (in de.* so ueblich)
mailcc           weitere Mailadresse, an die eine Kopie jeder Bestaetigungs-
                 oder Fehlermail geschickt wird (fuer Archivzwecke)
onestep          Mails direkt verschicken und Ergebnisse speichern? [BOOL]
                 ("uvvote clean" Aufruf entfaellt)
multigroup       Fuer das Ergebnis auch bei Eingruppenabstimmung des
                 Mehrgruppenformat waehlen? [BOOL]
condition1       Bedingungen fuer einen Erfolg der Abstimmung in Perl-Syntax
condition2       (normalerweise "$yes>=2*$no" und "$yes>=60"
resultfile       Datei fuer Gesamtergebnis (normalerweise ergebnis.alle)
idfile           Datei mit Scheinkennungen (bei "personal=1")
pop3             POP3 benutzen? [BOOL] (andernfalls Stimmen aus Datei lesen)
pop3server       POP3-Server fuer eingehende Wahlscheine
pop3port         POP3-Serverport (normalerweise 110)
pop3user         Benutzername
pop3pass         Passwort
pop3delete       Mails nach Abruf vom Server loeschen? [BOOL]
pop3uidlcache    Dateiname zum Speichern bereits abgerufener Mail-IDs (UIDL)
pop3*_req        entsprechende Optionen fuer Mailbox mit eingehenden
                 Wahlscheinanforderungen (bei "personal=1")
pop3*_bounce     entsprechende Optionen fuer Mailbox mit Bounces (Fehlermails)
                 fuer die Verarbeitung durch uvbounce.pl
smtp             SMTP zum Verschicken von Mails benutzen? [BOOL]
                 Andernfalls wird direkt an den MTA uebergeben (nur Unix)
smtpserver       SMTP-Server
smtpport         SMTP-Serverport (normalerweise 25)
smtpauth         SMTP-Authentication nach RFC 2554 benutzen? [BOOL]
smtpuser         SMTP-Benutzername
smtppass         SMTP-Passwort
smtphelo         String fuer die HELO-Greeting bei SMTP (Default: Hostname)
fqdn             String fuer den Host-Teil der Message-ID
                 (Fully Qualified Domain Name) (Default: Hostname)
archivedir       Verzeichnis fuer Archivierung von verarbeiteten Stimmen
tmpdir           temporaeres Verzeichnis
templatedir      Verzeichnis mit Templates (Vorlagen) fuer diverse Zwecke
                 (normalerweise "templates", dort liegen bereits vordefinierte
                 Templates, die i.d.R. nicht angepasst zu werden brauchen)
formats          Konvertierungsfunktionen fuer die Templates, mit Komma getrennt
                 (mitgelieferte UVformats.pm muss hier aufgefuehrt werden,
                 desweiteren koennen eigene Module mit weiteren Funktionen
                 hier eingebunden werden)
controlfile      Name der Steuerungsdatei fuer den Mailversand (tmp/ack.control)
domailfile       Name des Shellscripts zum Versenden der Bestaetigungsmails
                 (falls smtp=0, normalerweise tmp/domail)
mailcmd          Aufruf des Mail Transfer Agents (MTA) zum Verschicken der
                 Bestaetigungsmails (falls smtp=0), z.B.
                 "sendmail -oi -oem -femail@adresse"
sleepcmd         Weiteres Kommando, welches nach jeder Mail aufgerufen werden
                 soll (falls smtp=0). Sinnvoll ist ein "sleep x", wobei x bei
                 langsamen Systemen hoeher gewaehlt werden sollte.
clearcmd         Shellbefehl zum Loeschen des Bildschirms (Standard: clear),
                 muss unter Windows auf "cls" geaendert werden. Falls Shell
                 oder Betriebssystem keinen solchen Befehl bereitstellen,
                 sollte ein Kommando verwendet werden, welches eine Trennlinie
                 oder aehnliches auf dem Bildschirm ausgibt, z.B. mit "echo"
diff             Shellbefehl zum Dateivergleich (diff); es koennen auch 
                 Parameter angegeben werden, z.B. "diff -u". Das verwendete
                 Programm muss das Lesen einer Datei von STDIN erlauben
                 ("-" statt Dateinamen fuer Einlesen von Standardeingabekanal)
pager            Shellbefehl zum seitenweisen Darstellen von Mails auf dem
                 Bildschirm (normalerweise "less"). Unter Windows muss "more"
                 benutzt werden, unter Unix hingegen gibt es moeglicherweise
                 bei "more" Probleme mit der Umleitung von STDERR in eine Datei
                 (wie es z.B. von uvvote.pl benoetigt wird), daher ist "less"
                 der Standardwert.
mailfrom         Absender fuer den From-Header der Bestaetigungsmails. Wird
                 auch in Bestaetigungsmails als Unterschrift eingefuegt und
                 sollte daher am besten in folgendem Format sein:
                 Vorname Nachname <gvv@foo.bar>
                 (ohne Anfuehrungsstriche, falls rfc-konform moeglich)
envelopefrom     Absender fuer den Envelope (Return-Path) der Bestaetigungsmails
                 bei Verwendung von SMTP (bitte nur die Adresse eintragen, ohne
                 Klammern und Zusaetze). Wenn SMTP ausgeschaltet ist, muss
                 diese Einstellung entsprechend der Mailer-Doku in "mailcmd"
                 gesetzt werden (z.B. bei Sendmail und kompatiblen mit -f)
messagefile      Datei mit diversen Meldungen und Textfragmenten (messages.cfg)
rulefile         Datei mit Wahlregeln (usevote.rul)
badaddrfile      Datei mit verdaechtigen Mailadressen (mailpatterns.cfg)
errorfile        Datei fuer Fehlermeldungen beim Programmlauf (errors.log)
mailstart        Einleitungszeile fuer naechste Mail (RegExp), falls Mails
                 aus einer Datei eingelesen werden (smtp=0), normalerweise
                 "^From"
begin_divider    Trennlinien vor und nach dem Wahlschein
end_divider      ("Alles vor/nach dieser Zeile bitte loeschen")
nametext         Text fuer die Namens-Angabe im Wahlschein. Muss im
                 Wahlschein genauso stehen und wird beim Standardtemplate
                 auch aus dieser Einstellung uebernommen. Beispieltext:
                 "Dein Realname, falls nicht im FROM-Header:"
nametext2        Text fuer Namens-Angabe in Bestaetigungsmails
                 (dito, Standardwert "Waehlername:")
addresstext      Text fuer die Adress-Angabe im Wahlschein
                 (dito, Standardwert "Waehleradresse:")
ballotidtext     Text für die Angabe der Wahlscheinkennung (falls personal=1)
                 (dito, Standardwert "Wahlscheinkennung:")
bdsgtext         Text fuer Datenschutzklausel (falls bdsg=1),  erscheint als
                 Abstimmungspunkt (z.B. "Datenschutzklausel - Zustimmung: Ich
                 bin mit der Verarbeitung meiner Daten wie oben beschrieben
                 einverstanden")
bdsgfile         Datei mit Erklaerungstext fuer BDSG-Klausel (bdsgtext.cfg)
rightmargin      Zeilenbreite bei Ausgaben, die nicht durch Templates
                 gesteuert werden. Hat vor allem auf Bildschirmausgaben
                 Auswirkung.
name_re          Regulaerer Ausdruck fuer Erkennung eines gueltigen Realnamens.
                 Beispiel: "[a-zA-ZäöüáàâéèêíìîóòôúùûÄÖÜÁÁÂÉÈÊÍÌÎÓÒÔÚÙÛß-]{2,} +
                 .*[a-zA-ZäöüáàâéèêíìîóòôúùûÄÖÜÁÁÂÉÈÊÍÌÎÓÒÔÚÙÛß]{2,}"
                 (muss ohne Umbruch in eine Zeile)

Regulaere Ausdruecke fuer Erkennung der Stimmen
(Gross-/Kleinschreibung spielt keine Rolle):

ja_stimme        Standardwert: (J\s*A|J|(D\s*A\s*)?F\s*U\s*E\s*R)
nein_stimme      Standardwert: (N\s*E\s*I\s*N|N|(D\s*A\s*)?G\s*E\s*G\s*E\s*N)
enth_stimme      Standardwert: (E|E\s*N\s*T\s*H\s*A\s*L\s*T\s*U\s*N\s*G)
ann_stimme       Standardwert: A\s*N\s*N\s*U\s*L\s*L\s*I\s*E\s*R\s*U\s*N\s*G

Definition der verwendeten Templatedateien
(werden im Unterverzeichnis "templates" mitgeliefert):

tpl_mailheader      "mailheader"         # generally used mail header
tpl_bouncelist      "bouncelist"         # used by uvbounce.pl
tpl_result_multi    "result-multi"       # used by uvcount.pl -r -m
tpl_result_single   "result-single"      # used by uvcount.pl -r -o
tpl_votes_multi     "votes-multi"        # used by uvcount.pl -v (multiple groups)
tpl_votes_single    "votes-single"       # used by uvcount.pl -v (single group only)
tpl_voterlist       "voterlist"          # used by uvcount.pl -l (2nd CfV)
tpl_ballot          "ballot"             # used by uvballot.pl (personal = 0)
tpl_ballot_request  "ballot-request"     # used by uvballot.pl (personal = 1)
tpl_ballot_personal "ballot-personal"    # used by uvcfv.pl    (personal = 1)
tpl_addr_reg        "address-not-registered"  # used by uvvote.pl   (personal = 1)
tpl_no_ballotid     "no-ballotid"        # used by uvvote.pl   (personal = 1)
tpl_wrong_ballotid  "wrong-ballotid"     # used by uvvote.pl   (personal = 1)
tpl_bdsg_error      "bdsg-error"         # used by uvvote.pl   (bdsg = 1)
tpl_ack_mail        "ack-mail"           # used by uvvote.pl   (voteack = 1)
tpl_cancelled       "cancelled"          # used by uvvote.pl
tpl_invalid_account "invalid-account"    # used by uvvote.pl
tpl_invalid_name    "invalid-name"       # used by uvvote.pl
tpl_multiple_votes  "multiple-votes"     # used by uvvote.pl
tpl_no_ballot       "no-ballot"          # used by uvvote.pl
tpl_no_votes        "no-votes"           # used by uvvote.pl
tpl_rule_violated   "rule-violated"      # used by uvvote.pl  (siehe usevote.rul)


15. Templates
=============

Die mitgelieferten Templates befinden sich im Verzeichnis "templates".
In usevote.cfg koennen weitere Verzeichnisse definiert werden, in
denen auch nach Templates gesucht wird ("templatedir", kommaseparierte
Liste mit Verzeichnissen). Außerdem koennen dort die Dateinamen der einzelnen
Templates eingestellt werden, wodurch es moeglich ist, in einzelnen
Abstimmungen andere, selbst definierte Templates zu verwenden, die in
einem gesonderten Verzeichnis abgelegt sind.

Eine Templatedatei besteht aus zwei Teilen. Am Anfang werden die
Formatierungen bestimmter Schluessel definiert und nach einem Trenner
folgt der eigentlich Template-Koerper, der dann von Programm bearbeitet
und ausgegeben wird.

   format-key := function1 param | function2 param

   == TEMPLATE ====================================

   Ich bin nun das eigentliche Template:

   format-key: [$format-key]

Der Trenner beginnt mit den Zeichen '== TEMPLATE' danach koennen beliebige
Zeichen folgen um die beiden Sektionen optisch voneinander abzugrenzen.

Wenn es keine Formatierungsanweisungen gibt, kann der Trenner auch
weggelassen werden. D.h. wenn kein Trenner gefunden wird, wird der
komplette Text als Template-Koerper betrachtet.


Template-Koerper
----------------

Im Template-Koerper werden die zu ersetzenden Token durch eckige
Klammern abgegrenzt. Sollen eckige Klammern im Text ausgegeben werden,
muessen diese durch einen Backslash freigestellt werden.

   [$termersetzung] [@schleife] nur eine \[ Klammer


Termersetzung:

    Ersetzt den Token durch den Wert des angegeben Schluessels:

      [$formatierung] [$schluessel]

    Es wird zuerst nach einer Formatierung mit den entsprechenden
    Bezeichner gesucht. Ist diese vorhanden, werden die entsprechenden
    Funktionen ausgefuehrt (siehe folgender Abschnitt).

    Kann kein Format gefunden werden, wird direkt in der im Programmcode
    gefuellten Datenstruktur nach einem Schluessel mit dem angegeben
    Bezeichner gesucht und sein Wert eingesetzt. Alle Einstellungen
    aus der usevote.cfg sind automatisch als Schluessel definiert, es
    kann also z.B. [$nametext] jederzeit verwendet werden. Eingesetzt
    wird an der Stelle der mit "nametext = " definierte Text aus
    usevote.cfg.

    Schlussendlich ist es noch moeglich einen default-Wert zu
    definieren, der eingesetzt wird, wenn keiner der obigen Wege
    erfolgreich war:

      Hallo [$name|Unbekannter]!

    Diese Zeile gibt, wenn kein Name definiert wurde, das Wort
    "Unbekannter" aus.


Bedingte Verzeigung:

    Ueberprueft ob der Wert des angegebenen Formats/Schluessel boolsch
    WAHR ist. Dementsprechend wird der then oder else Block eingefuegt:

      [?if|then|else] oder auch nur [?if|then]

    Die then/else Bloecke werden natuerlich auch auf Tokens geparst und
    diese dementsprechend ersetzt.


Schleifen/Listen:

    Der nachfolgende Textblock wird fuer alle Elemente des durch den
    Schluessel bezeichneten Arrays ausgefuehrt und eingefuegt.

      [@schluessel|block] oder [@schluessel|block|sep]

    Als zweiter Parameter kann ein Separtor definiert werden, mit dem
    sich z.B. kommaseparierte Listen erzeugen lassen, da der Separator
    eben nur zwischen den Elementen eingefuegt wird.

    Auch fuer Schleifen koennen Formatierungen genutzt werden.Allerdings
    darf kein String zurueckgegeben werden, sondern ein Array mit einer
    Menge von UVtemplate-Objekten.


Kommentare:

    Token die nach der Bearbeitungen entfernt werden:

       [# mich sieht man nicht]


Sonstiges:

    Um in Listen einen Zeilenumbruch zu erzwingen, muss lediglich ein
    '\n' eingefuegt werden, falls eine kompakte Definition der Liste
    erfolgen soll.

       [@names|[name] [email]\n]


Formatierungen
--------------

Eine Formatierung besteht eigentlich nur aus dem entsprechenden
Namen und einer beliebigen Anzahl von Funktionsaufrufen:

   format := funktion param1 "param 2" | funktion param

Aehnlich der Unix-Shell-Funktionalitaet, wird dabei die Ausgabe
einer Funktion an die folgende weitergeleitet. So ist es moeglich,
verschiedenste simple Formatierungen zu kombinieren um nicht fuer
jeden Spezialfall eine neue Funktion schreiben zu muessen.

Die jeweilige Formatierungsfunktion erhaelt als Input die
Datenstruktur, den Output der vorherigen Funktion und die definierten
Parameter in der entsprechenden Reihenfolge.  

Zahlen und einfache Bezeichner koennen direkt definiert werden.
Sollen Sonderzeichen oder Leerzeichen uebergeben werden, muessen
diese gequotet werden. Dazu kann ' oder " verwendet werden.

Die Funktionen geben im Allgemeinen einen String zurueck. Im Rahmen
von Listen können auch Arrays uebergeben werden.

Die erste Funktion duerfte ueblicherweise 'value' sein. Sie gibt
den Wert des angegeben Schluessel zurueck, der dann von den
folgenden Funktionen definiert wird:

   name-60 := value name | fill-right 60

Das Format "name-60" definiert also den Wert des Schluessel "name",
der um Leerzeichen aufgefuellt wird, bis eine Laenge von 60 Zeichen
erreicht wird.

   name-email := value name | justify-behind mail 72

"name-email" resultiert in einem String, der zwischen den Werten von
"name" und "email" genau so viele Leerzeichen enthaelt, damit der
gesamte String 72 Zeichen lang ist.

Wird dieses Format in einer Liste angewandt, erhaelt man eine Tabelle
in der die linke Spalte linksbuendig und die rechte Spalte
entsprechend rechtsbuendig ist.

Soweit ein kleiner Ueberblick ueber die Formatierungen. Ausfuehrliche
Funktionsbeschreibungen und weitere Beispiele finden sich in der
POD-Dokumentation des Moduls UVformat ("perldoc UVformat.pm").

Es ist moeglich, selbst eigene Module mit Formatierungsfunktionen
zu schreiben und ueber die Option "formats" in usevote.cfg einzubinden.
Am besten kann dazu UVformats.pm als Vorlage genommen werden.
Wichtig: der Name einer Formatierungsfunktionen darf nur aus
Gross- und Kleinbuchstaben, Zahlen und Minuszeichen bestehen.
Unterstriche, Punkte etc. sind nicht erlaubt!

Falls eine elementare Funktion fehlt, kannst Du Dich auch gerne
bei mir melden und ich pruefe, wie sie sich einbauen laesst.

Marc Langer, im Oktober 2005