thh/usevote
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Activity
usevote/README
Thomas Hochstein f90cfdb57f Update documentation. 
Signed-off-by: Thomas Hochstein <thh@inter.net>
2021-12-19 15:21:15 +01:00

1298 lines
57 KiB
Plaintext
Raw Permalink Blame History

UseVoteGer 4.12 (c) 2001-2014 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.12 - 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
DSGVO), 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 <20>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<EFBFBD>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 <20>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<65>hrt werden (Pfad
nat<EFBFBD>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<67>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 ausfuehren ("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 <20>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? >=15? : 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. <20>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<65>llt werden, da manchmal auch mehrere
Abstimmungsgegenst<EFBFBD>nde angenommen werden, z.B. bei Moderationsnachwahlen
f<EFBFBD>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<75>tzlich eingebundene Konfigurationsdateien werden an der
Stelle der "include"-Zeile eingef<65>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>=15"
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<><5A><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>-]{2,} +
.*[a-zA-Z<><5A><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>]{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<41>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
Reference in a new issue View git blame Copy permalink