| 1 | UseVoteGer 4.12 (c) 2001-2014 Marc Langer |
| 2 | |
| 3 | UseVoteGer is a voting software for usenet votes. |
| 4 | |
| 5 | This script package is free software; you can redistribute it and/or |
| 6 | modify it under the terms of the GNU Public License as published by the |
| 7 | Free Software Foundation. |
| 8 | |
| 9 | Many thanks to: |
| 10 | - Ron Dippold (Usevote 3.0, 1993/94) |
| 11 | - Frederik Ramm (German translation, 1994) |
| 12 | - Wolfgang Behrens (UseVoteGer 3.1, based on Frederik's translation, 1998/99) |
| 13 | - Cornell Binder for some good advice and code fragments |
| 14 | (e.g. UVtemplate.pm, UVformats.pm) |
| 15 | |
| 16 | This is a complete rewrite of UseVoteGer 3.1 in Perl (former versions were |
| 17 | written in C). Not all functions of Usevote/UseVoteGer 3.x are implemented! |
| 18 | |
| 19 | ------------------------------------------------------------------------------- |
| 20 | |
| 21 | UseVoteGer 4.12 - Usenet-Abstimmungssoftware |
| 22 | =========================================== |
| 23 | |
| 24 | von Marc Langer <uv@marclanger.de> |
| 25 | |
| 26 | aktuelle Versionen: http://www.usevote.de |
| 27 | |
| 28 | |
| 29 | Inhaltsverzeichnis |
| 30 | ================== |
| 31 | |
| 32 | 1. Kurzbeschreibung |
| 33 | 2. Usevote fuer Ungeduldige |
| 34 | 3. Kompatibilitaet zu frueheren Versionen |
| 35 | 4. Liste der Dateien |
| 36 | 5. Anfangs-Konfiguration |
| 37 | 6. Konfiguration fuer einzelne Abstimmungen |
| 38 | 7. Wahlschein generieren |
| 39 | 8. Stimmen verarbeiten |
| 40 | 9. Unzustellbare Bestaetigungen |
| 41 | 10. 2. CfV / Result |
| 42 | 11. Datenschutz |
| 43 | 12. Personalisierte Wahlscheine |
| 44 | 13. Die einzelnen Programme |
| 45 | 14. Die Konfigurationsdateien |
| 46 | 15. Templates |
| 47 | |
| 48 | |
| 49 | 1. Kurzbeschreibung |
| 50 | =================== |
| 51 | |
| 52 | Diese Software vereinfacht die Durchfuehrung von Usenet-Abstimmungen. |
| 53 | Usevote in der Urversion wurde von Ron Dippold fuer die Reorganisation |
| 54 | der Gruppe comp.sys.ibm.pc.games geschrieben und spaeter fuer die |
| 55 | allgemeine Verwendung verbessert. |
| 56 | |
| 57 | Die deutsche Uebersetzung von Frederik Ramm diente jahrelang als |
| 58 | Grundlage fuer CfV-Auswertungen im deutschsprachigen Raum. |
| 59 | Wolfgang Behrens von den German Volunteer Votetakers (GVV) passte |
| 60 | es spaeter an neue Begebenheiten (z.B. personalisierte Wahlscheine) |
| 61 | an. Jedoch liefen die UseVoteGer 3.1beta-Versionen aufgrund eines |
| 62 | unbekannten Fehlers nicht auf jedem System (Segmentation Fault). |
| 63 | |
| 64 | Um groessere Flexibilitaet und Plattformunabhaengigkeit zu bieten, |
| 65 | habe ich mich entschlossen, UseVoteGer in Perl neu zu implementieren. |
| 66 | Getestet wurde diese Version mit Perl 5.x unter Linux sowie |
| 67 | ActiveState Perl unter Windows 98. |
| 68 | |
| 69 | |
| 70 | 2. Usevote fuer Ungeduldige |
| 71 | =========================== |
| 72 | |
| 73 | I. Einmalig bei der Usevote-Erstinstallation |
| 74 | (1) usevote.cfg nach Bedarf anpassen (selbsterklaerend) |
| 75 | ACHTUNG: Unter Windows gibt es das Programm "less" nicht, da "more" |
| 76 | aber einigermassen broken ist, sollte man sich less fuer Windows |
| 77 | herunterladen: http://www.greenwoodsoftware.com/less/less381d.zip |
| 78 | Notfalls laesst sich auch in usevote.cfg die Einstellung "pager" |
| 79 | auf "more" setzen, aber viel Freude hat man damit nicht... |
| 80 | (2) Evtl. die Templates im gleichnamigen Unterverzeichnis fuer |
| 81 | eigenen Geschmack anpassen. Die Templates enthalten saemtliche |
| 82 | Texte fuer Bestaetigungs-/Fehlermails sowie die Ausgabeformate |
| 83 | und Texte fuer die CfVs und das Result. |
| 84 | (3) Perlmodule MIME::Parser, MIME::QuotedPrint, Digest::MD5, |
| 85 | Date::Parse und Email::Date installieren, falls noch nicht vorhanden. |
| 86 | Bei Benutzung von POP3 oder SMTP (siehe usevote.cfg) muss |
| 87 | Libnet installiert sein (Net::POP3 und Net::SMTP). |
| 88 | (Fuer Perl-Einsteiger: Unter Unix geht die Modul-Installation |
| 89 | sehr einfach mit "perl -MCPAN -e shell", ActivePerl fuer |
| 90 | Windows hat einen eigenen Paketmanager) |
| 91 | |
| 92 | |
| 93 | II. Fuer jedes Voting |
| 94 | (1) usevote.cfg auf das durchzufuehrende Voting anpassen |
| 95 | (selbsterklaerend) |
| 96 | (2) bei Sonderregeln (Abhaengigkeiten der einzelnen Abstimmungspunkte) |
| 97 | in usevote.rul Regeln definieren (selbsterklaerend) |
| 98 | (3) CfV erstellen und Wahlschein mit uvballot.pl generieren |
| 99 | (4) Fertigen CfV einreichen und auf Veroeffentlichung warten ;-) |
| 100 | (5) Bis zum 2. CfV regelmaessig (an den ersten Tagen mehrmals taeglich, |
| 101 | spaeter einmal taeglich) dies tun: |
| 102 | - uvvote.pl durchlaufen lassen |
| 103 | - im Verzeichnis tmp/ die Datei ergebnis.* (Ergebnis der Auswertung) |
| 104 | und evtl. ack.* (Bestaetigungsmails an die Waehler) kontrollieren |
| 105 | - Falls es Probleme gab: Bitte den Abschnit "Stimmen verarbeiten" |
| 106 | weiter unten in dieser Datei genau durchlesen. Dort steht |
| 107 | beschrieben, wie Fehler korrigiert werden koennen |
| 108 | - "uvvote.pl clean" aufrufen, um die Bestaetigungen zu verschicken |
| 109 | und das Ergebnis zu speichern/archivieren |
| 110 | - Falls Wahlbestaetigungen als unzustellbar zurueckkommen, solltest |
| 111 | Du diese zusammen in einer Datei speichern oder in ein spezielles |
| 112 | POP3-Postfach leiten |
| 113 | (6) Zwischenbestaetigung fuer den 2. CfV mit "uvcount.pl -l" erzeugen und |
| 114 | veroeffentlichen. Falls Wahlbestaetigungen als unzustellbar |
| 115 | zurueckkamen, kannst Du mit "uvbounce.pl dateiname" automatisch eine |
| 116 | Liste der ungueltigen Adressen erzeugen ("dateiname" ist die Datei, |
| 117 | in die Du zuvor die Bounces gespeichert hattest). Siehe auch Abschnitt |
| 118 | "Unzustellbare Bestaetigungen" weiter unten in dieser Datei, dort |
| 119 | ist auch erklaert, wie die Bounces aus einem POP3-Postfach gelesen |
| 120 | werden koennen. |
| 121 | (7) Bis zum Result wieder wie (5) |
| 122 | (8) Zum vorgegebenen Zeitpunkt die Wahl abschliessen, |
| 123 | mit "uvcount.pl -r -v" Endergebnis erzeugen und veroeffentlichen |
| 124 | (zuvor wiederum Liste der ungueltigen Mailadressen erzeugen, siehe |
| 125 | Punkt 6) |
| 126 | |
| 127 | Weitere Details finden sich im Folgenden. |
| 128 | Jeder Nutzer dieser Software sollte sich diesen Text wenigstens einmal |
| 129 | komplett durchlesen. |
| 130 | |
| 131 | Abschnitt 6 beschreibt, wie mehrere Abstimmungen gleichzeitig durchgefuehrt |
| 132 | werden koennen, ohne saemtliche Programmdateien zu kopieren. |
| 133 | |
| 134 | |
| 135 | 3. Kompatibilitaet zu frueheren Versionen |
| 136 | ========================================= |
| 137 | |
| 138 | - englische Usevote-Versionen: keine Kompatibilitaet |
| 139 | |
| 140 | - deutsche Usevote-Versionen (Usevote 3.0a, UseVoteGer 3.1): |
| 141 | * Wahlscheine haben neue Markierungen zum sicheren Erkennen |
| 142 | der Stimmen. Bisherige Wahlscheine sind mit dieser Version |
| 143 | nicht mehr einsetzbar! |
| 144 | |
| 145 | * acktext.txt gibt es nicht mehr, statt dessen sind im Unterverzeichnis |
| 146 | "templates" Vorlagen zu finden, die diese Texte enthalten. |
| 147 | |
| 148 | * usevote.cfg ist komplett inkompatibel |
| 149 | |
| 150 | * usevote.rul: voll kompatibel, ohne Einschraenkungen |
| 151 | |
| 152 | * Ergebnisdateien: Inhalt kompatibel, aber Namensgebung geaendert |
| 153 | (obwohl irrelevant, da Umstieg auf diese Version waehrend |
| 154 | einer laufenden Wahl nicht moeglich) |
| 155 | |
| 156 | * scheinkennungen: Dateiformat gaendert (aus selbigen Gruenden |
| 157 | nicht weiter wichtig) |
| 158 | |
| 159 | * uvshell: integriert in uvvote.pl, ueber usevote.cfg steuerbar |
| 160 | |
| 161 | * uvvote.pl: Aufrufparameter geaendert / Zusammenfuehrung mit uvshell |
| 162 | |
| 163 | * uvcfv.pl: Alte Funktionalitaet ist nicht mehr implementiert, |
| 164 | statt dessen dient das Tool jetzt zum Generieren der persoenlichen |
| 165 | Wahlscheine und Verschicken des CfV an die Waehler |
| 166 | |
| 167 | * uvcount.pl: Beinhaltet auch uvack und uvdup. Drei Einzelprogramme |
| 168 | schienen mir ineffizient. |
| 169 | |
| 170 | * uvbounce.pl: Ausgabeformat etwas anders |
| 171 | |
| 172 | |
| 173 | 4. Liste der Dateien |
| 174 | ==================== |
| 175 | |
| 176 | * Ausgelieferte Dateien: |
| 177 | |
| 178 | CHANGES Versionsaenderungen |
| 179 | COPYING GNU General Public License |
| 180 | README Diese Datei |
| 181 | UVconfig.pm Routinen zum Einlesen und Pruefen der Konfiguration |
| 182 | UVformats.pm Routinen zum Formatieren von Texten in Templates |
| 183 | UVmenu.pm Routinen zur Interaktion mit dem Wahlleiter |
| 184 | UVmessage.pm Routinen zum Parsen von Texten und Ersetzen von Platzhaltern |
| 185 | UVreadmail.pm Routinen zum Einlesen und MIME-Decodieren der Mails |
| 186 | UVrules.pm Routinen zur Regelverarbeitung (usevote.rul) |
| 187 | UVsendmail.pm Routinen zum Erzeugen von Mails |
| 188 | UVtemplate.pm Routinen zur Verarbeitung von Vorlagen (Templates) |
| 189 | bdsgtext.cfg Spezieller Text fuer den Wahlschein (Hinweis auf |
| 190 | Datenschutzgesetz), muss ausserhalb Deutschlands ggfls. |
| 191 | angepasst oder kann ignoriert werden (bdsg=0 in usevote.cfg) |
| 192 | mailpatterns.cfg Wildcards fuer verdaechtige Mailadressen |
| 193 | messages.cfg Programm-Meldungen (Ressourcen-Datei) |
| 194 | scheinkennungen Speicherung der Scheinkennungen bei personalisierten |
| 195 | Wahlscheinen. Muss zu Beginn der Abstimmung leer sein. |
| 196 | usevote.cfg Konfigurationsdatei |
| 197 | usevote.rul Abstimmungsregeln |
| 198 | uvballot.pl Wahlschein aus Abstimmungsdaten erstellen |
| 199 | uvbounce.pl Listen von unzustellbaren Bestaetigungen erzeugen |
| 200 | uvcfv.pl Erstellen und Verschicken von personalisierten Wahlscheinen |
| 201 | uvcount.pl Stimmenzaehlung, Erstellen von Waehlerlisten und |
| 202 | Aussortieren von doppelten Stimmabgaben |
| 203 | uvvote.pl Stimmen verarbeiten (fuer die taegliche Arbeit) |
| 204 | |
| 205 | templates/ Verzeichnis mit Templates (Vorlagen) |
| 206 | ack-mail Template fuer Bestaetigungsmails |
| 207 | address-not-registered Fehlermail: Noch keine Scheinkennung fuer Adresse |
| 208 | vergeben |
| 209 | ballot Template fuer einen Wahlschein |
| 210 | ballot-personal Template fuer personalisierten Wahlschein |
| 211 | ballot-request Template fuer eine Wahlscheinanforderung |
| 212 | bdsg-error Fehlermail: Datenschutzklausel nicht akzeptiert |
| 213 | bouncelist Template fuer Liste der ungueltigen Mailadressen |
| 214 | cancelled Template fuer Bestaetigung der Stimmannullierung |
| 215 | invalid-account Fehlermail: Fragwuerdige Mailadresse (Role Account) |
| 216 | invalid-name Fehlermail: Kein gueltiger Name in Mail/Wahlschein |
| 217 | gefunden |
| 218 | mailheader Template fuer den Header von Mails an die Waehler |
| 219 | multiple-votes Fehlermail: Widerspruechliche Stimmen im Wahlschein |
| 220 | no-ballot Fehlermail: Kein Wahlschein in Mail gefunden |
| 221 | no-ballotid Fehlermail: Keine Wahlscheinkennung gefunden |
| 222 | no-votes Fehlermail: Keine Stimmen abgegeben |
| 223 | result-multi Template fuer ein Wahlergebnis mit mehreren Gruppen |
| 224 | result-single Template fuer ein Wahlergebnis mit einer Gruppe |
| 225 | result-proportional Template fuer ein Wahlergebnis, bei dem das Verhaeltnis |
| 226 | oder die Differenz von Ja- und Nein-Stimmen entscheidet |
| 227 | (z.B. Moderationsnachwahlen, "proportional=1" gesetzt) |
| 228 | rule-violated Fehlermail: Wahlregeln aus usevote.rul verletzt |
| 229 | voterlist Template fuer eine Waehlerliste (2. CfV) |
| 230 | votes-multi Template fuer eine Stimmenliste mit mehreren Gruppen |
| 231 | votes-single Template fuer eine Stimmenliste bei einer Gruppe |
| 232 | wrong-ballotid Fehlermail: Falsche Wahlscheinkennung angegeben |
| 233 | |
| 234 | * Beim Programmlauf erstellte Dateien (Name ist konfigurierbar): |
| 235 | |
| 236 | ergebnis.alle Saemtliche Einzelergebnisse zusammengefasst (wird |
| 237 | bei jedem Lauf von uvvote.pl neu erstellt) |
| 238 | errors.log Fehlermeldungen, die beim Programmlauf auftauchen, |
| 239 | werden hier abgelegt. Normalerweise bleibt die Datei |
| 240 | leer, ansonsten wird beim Programmende eine Warnung |
| 241 | mit Verweis auf die Datei ausgegeben. |
| 242 | uidlcache Eindeutige IDs der abgerufenen Mails (bei Benutzung |
| 243 | von POP3). Darf waehrend einer laufenden Abstimmung |
| 244 | keinesfalls geloescht werden, um Mehrfachzaehlung von |
| 245 | Stimmen zu verhindern. |
| 246 | uidlcache_req dto, fuer die Mailbox mit den Wahlscheinanforderungen |
| 247 | (bei Verwendung von personalisierten Wahlscheinen) |
| 248 | uidlcache_bounce dto, fuer die Mailbox mit den Bounces (wird von |
| 249 | uvbounce.pl ausgewertet) |
| 250 | usevote.lock Temporaere Lockdatei, um gleichzeitiges Ausfuehren |
| 251 | mehrerer Instanzen zu verhindern. Kann (falls vorhanden) |
| 252 | gefahrlos geloescht werden, wenn gerade keines der |
| 253 | Usevote-Scripts laeuft. |
| 254 | |
| 255 | * Folgende Unterverzeichnisse werden von Usevote im aktuellen |
| 256 | Verzeichnis (CWD) angelegt: |
| 257 | |
| 258 | fertig/ Verzeichnis fuer Archivierung verarbeiteter Dateien |
| 259 | tmp/ Verzeichnis fuer temporaere Dateien |
| 260 | |
| 261 | * Von Usevote dort erstellte Dateien: |
| 262 | |
| 263 | ack.* Bestaetigungsmails (in tmp/) |
| 264 | ack.control Steuerungsdatei fuer Bestaetigungsmails (in tmp/) |
| 265 | domail Shellscript zum Verschicken der Mails (in tmp/) |
| 266 | ergebnis.* Ergebnisdateien einzelner Durchlaeufe (zunaecht in tmp/, |
| 267 | spaeter nach fertig/ verschoben und archiviert) |
| 268 | stimmen.* Archivierte Stimmendateien (dto.) |
| 269 | |
| 270 | |
| 271 | 5. Anfangs-Konfiguration |
| 272 | ======================== |
| 273 | |
| 274 | Zuerst solltest Du "usevote.cfg" fuer Dein System anpassen (Details |
| 275 | dort in den Kommentarzeilen und weiter hinten in dieser Dokumentation). |
| 276 | Unter Windows werden die Regular Expressions fuer die Stimmenerkennung |
| 277 | moeglicherweise lauter unlesbare Zeichen enthalten (anderer Zeichensatz), |
| 278 | dort sollten saemtliche in Namen vorkommende Umlaute und Buchstaben mit |
| 279 | Accents etc. aufgefuehrt werden. Weiter ist bei Nutzung von Windows zu |
| 280 | beachten, dass das Kommando zum Loeschen des Bildschirms "cls" und nicht |
| 281 | "clear" heisst. Dazu gibt es auch eine Einstellung in usevote.cfg. Den |
| 282 | standardmaessig eingestellten Pager "less" gibt es unter Windows zunaechst |
| 283 | nicht, more ist aber so buggy, dass man sich am besten "less" fuer |
| 284 | Windows herunterladen sollte: |
| 285 | http://www.greenwoodsoftware.com/less/less381d.zip |
| 286 | |
| 287 | Im Unterverzeichnis "templates" findest Du Vorlagen, die fuer die |
| 288 | einzelnen Bestaetigungstexte, Mails, Wahlscheine und Waehlerlisten |
| 289 | verwendet werden. Hier kannst Du unter Beachtung der Syntax (siehe |
| 290 | gesonderte Dokumentation) alle Texte an Deinen Geschmack und Deine |
| 291 | Beduerfnisse anpassen. |
| 292 | |
| 293 | |
| 294 | 6. Konfiguration fuer einzelne Abstimmungen |
| 295 | =========================================== |
| 296 | |
| 297 | Fuer jede Abstimmung muss eine eigene Konfigurationsdatei geschrieben |
| 298 | werden. Aendere einfach usevote.cfg entsprechend der Regeln fuer die |
| 299 | betreffende Abstimmung. Falls Du haeufiger Wahlleiter spielst, solltest |
| 300 | Du Dir eine globale Konfigurationsdatei mit Standardeinstellungen |
| 301 | (z.B. als ~/.usevote-defaults.cfg) anlegen und in der usevote.cfg nur |
| 302 | noch die Einstellungen setzen, die sich fuer jede Abstimmunge aendern. |
| 303 | Die globale Datei kann am Anfang der usevote.cfg mit folgender Zeile |
| 304 | eingebunden werden: |
| 305 | |
| 306 | include ~/.usevote-defaults.cfg |
| 307 | |
| 308 | Zu beachten ist aber, dass jeweils die letzte Definition einer Option |
| 309 | benutzt wird. Die usevote.cfg sollte daher wirklich nur noch |
| 310 | abstimmungsspezifische Einstellungen enthalten, um nicht versehentlich |
| 311 |