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