Commit | Line | Data |
---|---|---|
1135267f | 1 | UseVoteGer 4.12 (c) 2001-2014 Marc Langer |
ac7e2c54 TH |
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 | ||
1135267f | 21 | UseVoteGer 4.12 - Usenet-Abstimmungssoftware |
ac7e2c54 TH |
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 | ||
ac7e2c54 TH |
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 |