c58696115b6a0fd50c75ac207e419f486ba00007
[usenet/usevote.git] / README
1 UseVoteGer 4.11  (c) 2001-2012 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.11 - 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 die globalen Optionen zu überschreiben.
312
313 Ausserdem muss die Datei "usevote.rul" geprueft werden. Wenn Deine
314 Abstimmung irgendwelche speziellen Regeln enthaelt (z.B. man kann
315 nur fuer Gruppe x stimmen, wenn man auch fuer y gestimmt hat, oder man
316 muss fuer den .misc-Abschnitt stimmen, wenn man fuer irgendeinen
317 anderen Abschnitt gestimmt hat), dann solltest Du diese Datei lesen
318 und entsprechend aendern. Allerdings empfiehlt es sich, bereits im
319 RfD deutlich auf die Regeln hinzuweisen, die zur Anwendung kommen sollen.
320 Die eingegebenen Regeln koennen dann mit "uvvote -t" getestet werden.
321
322 Es ist auch moeglich, mehrere Abstimmungen gleichzeitig durchzufuehren,
323 ohne die .pl und .pm Dateien jedesmal mitzukopieren. Folgende Dateien
324 sollten im Abstimmungsverzeichnis vorhanden sein (notwendig ist nur
325 usevote.cfg, darin können alle anderen Pfade angepasst werden):
326
327 bdsgtext.cfg
328 mailpatterns.cfg
329 messages.cfg
330 scheinkennungen
331 usevote.cfg
332 usevote.rul
333
334 Ggf. sollte das "templates"-Verzeichnis kopiert werden, falls
335 individuelle Templates fuer einzelne Abstimmungen verwendet werden.
336
337 Außerdem muessen i.d.R. einige Pfade in der usevote.cfg angepasst
338 werden. Dadurch ist auch die Angabe eines anderen Verzeichnisses
339 fuer einige der oben genannten Konfigurationsdateien moeglich,
340 falls diese zentral gepflegt werden sollen (z.B. messages.cfg und
341 mailpatterns.cfg).
342
343 Damit die Usevote-Perlmodule gefunden werden, sollten sie im
344 selben Verzeichnis wie die Programmdateien liegen bleiben. Ansonsten
345 muss eine Umgebungsvariable gesetzt werden:
346
347 PERL5LIB=..
348
349 .. steht für das übergeordnete Verzeichnis. Ggf. muss hier ein
350 absoluter Pfad eingetragen werden, wenn das Abstimmungsverzeichnis
351 kein Unterverzeichnis des Usevote-Verzeichnisses ist.
352
353 Je nach Betriebssystem kann die obige Zeile etwas anders aussehen,
354 unter Windows sollte z.B. "SET PERL5LIB=C:\PERL\USEVOTE" in die
355 autoexec.bat aufgenommen oder sonstwie ausgeführt werden (Pfad
356 natürlich entsprechend anpassen).
357
358
359 7. Wahlschein generieren
360 ========================
361  
362 Der Wahlschein ist ein Abschnitt des CfV, den die Leute zur Stimmabgabe
363 ausfuellen und zurueckschicken sollen. Am einfachsten erzeugst Du
364 diesen nach Anpassung der Konfiguration und ggfls. des Templates
365 mit "uvballot.pl". Folgendes Format ist erforderlich:
366
367 #1  [ Stimme ]  
368 #2  [ Stimme ]
369 [...]
370
371 Eine zusaetzliche Beschreibung rechts daneben macht es dem Waehler
372 einfacher, ist aber fuer Usevote nicht zwingend erforderlich. Wichtig
373 sind nur die fortlaufenden Nummern, die entsprechend der Eintraege
374 in usevote.cfg zugeordnet werden.
375
376 Je nach Konfiguration koennen weitere Zeilen noetig sein, dazu spaeter.
377
378 Als Stimme in den eckigen Klammern werden diverse Strings erkannt,
379 die in usevote.cfg definiert werden koennen. JA, NEIN und ENTHALTUNG
380 sind Standard, einige Abwandlungen sind ebenfalls moeglich.
381 Zusaetzlich kann ANNULLIERUNG verwendet werden, um eine schon abgegebene
382 Stimme zu loeschen und somit nicht im Result aufzutauchen.
383
384 Bei der Verwendung von persoenlichen Wahlscheinen (Abschnitt 6a der
385 Wahlregeln fuer de.*) ist das Vorgehen etwas anders, siehe hierzu
386 den gesonderten Abschnitt weiter hinten.
387
388
389 8. Stimmen verarbeiten
390 ======================
391
392 Falls POP3 nicht benutzt werden soll (siehe usevote.cfg), werden alle
393 Wahlmails zu einer Abstimmung aus einer Mailboxdatei gelesen
394 (Name/Pfad der Datei in usevote.cfg einstellbar). Standardmaessig
395 wird das Unix-Mailboxformat erkannt, dieses ist aber ueber "mailstart"
396 in usevote.cfg konfigurierbar (bei komplett anderen Formaten muesste
397 der Quellcode geaendert werden).
398
399 Wechsele nun in das Verzeichnis, in dem die passenden
400 Konfigurationsdateien liegen (normalerweise werden diese aus
401 dem aktuellen Verzeichnis gelesen, was mehrere gleichzeitige
402 Verfahren moeglich macht) und starte uvvote.pl. Bei Problemen
403 mit einzelnen Stimmen wirst Du interaktiv durch Menues gefuehrt.
404 Meistens gibt es folgende Moeglichkeiten, die durch die
405 eingeklammerten Buchstaben und Zahlen aufgerufen werden koennen:
406
407 (1) Anzeigen der Wahlmail
408
409 Bestaetigen oder Aendern von Wahlschein-Eigenschaften:
410 (2) Mailadresse
411 (3) Waehlername
412 (4) Stimmen
413 (5) Scheinkennung
414 (6) Datenschutzklausel
415 (7) Abstimmung
416
417 (i) Diese Stimme ignorieren (ohne Benachrichtigung verwerfen)
418 (w) Weiter
419
420 Teilweise gibt es Unteroptionen:
421   (a) OK (Zweifel sind unbegründet, ist alles in Ordnung)
422   (b) Aendern (z.B. wenn der Realname von Usevote nicht vollstaendig
423       erkannt wurde)
424   (c) Ungueltig (es handelt sich nach Deinem Ermessen nicht um
425       eine gueltige Stimmabgabe)
426
427 Nun solltest Du zunaechst mit (1) die Mail ansehen und anhand
428 der bemaengelten Punkte entscheiden, ob der Wahlschein gueltig
429 oder ungueltig ist bzw. welche Maengel tatsaechlich zutreffen.
430
431 Mit den Optionen (2) bis (7) kannst Du einzelne Eigenschaften
432 des Wahlscheins nachbessern (wenn Usevote z.B. einen Namen oder
433 eine Stimme nicht korrekt erkannt hat) oder auch einfach die
434 Korrektheit bestaetigen.
435
436 Wenn Du alle oben auf der Seite aufgelisteten Maengel beseitigst,
437 indem Du die entsprechenden Optionen waehlst, wird die Stimme
438 akzeptiert. Bleiben Zweifel unausgeraeumt, wird eine entsprechende
439 Fehlermail verschickt (Du erhaeltst dann noch eine gesonderte
440 Warnung).
441
442 Zum Schluss kannst Du (w) wählen, um fortzufahren. Möchtest Du,
443 dass eine Stimme komplett ignoriert wird (weil es sich z.B.
444 um Spam handelt), kannst Du (i) waehlen und die folgende
445 Sicherheitsfrage mit "JA" beantworten.
446
447 Ist uvvote.pl durchgelaufen, koennen im Unterverzeichnis tmp/
448 (wird ebenfalls aktuellen Verzeichnis angelegt!) die ermittelten
449 Ergebnisse und erzeugten Mails an die Waehler noch einmal geprueft
450 werden. Ist alles in Ordnung, werden mittels "uvvote.pl clean"
451 die Mails verschickt und die Ergebnisse gespeichert sowie die
452 Originalmails archiviert. Hierzu wird das Verzeichnis fertig/
453 verwendet.
454
455 Falls der komplette uvvote-Lauf verworfen werden soll, kann
456 die Datei mit den Waehlermails (stimmen-xyz im tmp-Verzeichnis,
457 xyz entspricht der aktuellen Unixtime waehrend des Durchlaufs)
458 wieder an den urspruenglichen Platz zurueckkopiert werden
459 (bei POP3: fuer den Neuversuch POP3 abschalten und die 
460 Maildatei einlesen lassen, da auf dem Server die Mails
461 moeglicherweise geloescht wurden) und das komplette tmp-Verzeichnis
462 geloescht werden. Anschliessend den uvvote-Lauf erneut durchfuehren.
463 Wichtig ist nur, dass das Verzeichnis fertig/ waehrend der ganzen
464 Abstimmung mitsamt seines Inhaltes erhalten bleibt.
465
466 Noch ein kurzes Wort zum Verschicken der Mails: Jede Mail wird
467 in einer gesonderten durchnummerierten Datei (ack.1, ack.2, ...)
468 gespeichert, zusaetzlich wird eine Steuerungsdatei ("ack.control")
469 erzeugt, welche zu jeder Mail Dateinamen und Empfaenger auflistet.
470 Je nach Einstellung werden die Mails dann per SMTP verschickt oder
471 es wird ein Shellscript ("domail") erzeugt, welches nach und 
472 nach die Mails in Sendmail einspeist. Zwecks Serialisierung ist
473 in usevote.cfg die Einstellung "sleepcmd" konfigurierbar,
474 normalerweise wird ein "sleep 1" nach jeder Mail ausgefuehrt.
475 Das Verschicken der Mails (und damit ggfls. der Aufruf von "domail")
476 erfolgt automatisch mit "uvvote.pl clean".
477
478 Unter Windows ist nur SMTP moeglich, es sei denn, es gibt
479 die Befehle sendmail, sleep und rm ;-)
480
481
482 9. Unzustellbare Bestaetigungen
483 ===============================
484
485 Leider kommt es immer mal wieder vor, dass jemand bei der Abstimmung
486 eine ungueltige Mailadresse angegeben hat. In diesem Fall erhaeltst Du
487 einen Bounce an die Absenderadresse zurueck (diese laesst sich in
488 usevote.cfg mit der Option "envelopefrom" einstellen bzw. bei 
489 direkten Aufruf eines Mailers über die entsprechende Kommandozeilenoption
490 in der mailcmd-Einstellung, z.B. bei Sendmail -f). Du solltest
491 solche Fehlermails in einer gesonderten Datei speichern oder in
492 einem gesonderten POP3-Postfach halten und beim Erstellen
493 des 2. CfVs und des Results uvbounce.pl aufrufen.
494
495 Ausgegeben wird von uvbounce.pl eine Liste mit ungueltigen Adressen,
496 die einfach an den Abschnitt "ungueltige Stimmen" des 2. CfVs bzw.
497 Results angehaengt werden kann. Nicht vergessen, die Stimmen manuell
498 aus der Liste der gueltigen Stimmen zu loeschen (falls Du die
499 Policy verfolgst, nur Stimmen mit gueltiger Absenderadresse zu werten,
500 was empfehlenswert ist) und bei Bedarf das Ergebnis zu korrigieren!
501
502
503 10. 2.CfV / Result
504 ===================
505
506 Zum Erstellen des 2. CfVs kannst Du erst einmal den 1. CfV als Vorlage
507 benutzen. Am Ende sollte allerdings eine Liste der Personen folgen,
508 die bereits abgestimmt haben. Diese laesst sich mit "uvcount.pl -l"
509 erzeugen. Moeglicherweise fragt uvcount.pl wegen scheinbar doppelter
510 Stimmabgaben nach und bietet an, eine oder beide Stimmen zu ignorieren.
511 Du solltest das dann genauer untersuchen und die passende Wahl treffen.
512
513 Vorsicht bei doppelten Namen: Es gibt einige doppelt vorkommende
514 Namen, hinter denen sich voellig unterschiedliche Personen
515 verbergen! Die Mailadresse sollte in solchen Faellen Auskunft
516 geben koennen, notfalls einmal nachfragen.
517
518 Das Endergebnis kannst Du mit "uvcount.pl -r" ausgeben lassen.
519 Bei Verfahren mit mehreren Abstimmungspunkten wird automatusch
520 das folgende tabellarische Format verwendet:
521
522  Ja  Nein : 2/3? >=60? : ang.? : Gruppe
523 ==== ==== : ==== ===== : ===== : =======================================
524  100   70 : Nein   Ja  :  Nein : Einrichtung von xyz
525
526 Bei Abstimmungen ueber nur einen Punkt gibt es auch die Moeglichkeit,
527 einen einfachen beschreibenden Text zu verwenden:
528 "Es gab 100 JA und 70 NEIN-Stimmen ...".
529
530 Falls in usevote.cfg die Einstellung "multigroup = 1" gesetzt ist,
531 wird immer die tabellarische Form gewaehlt, bei "multigroup = 0"
532 benutzt uvcount.pl bei nur einem Abstimmungspunkt den beschreibenden
533 Text. Überschreiben laesst sich dieses mit Aufrufparametern:
534
535 uvcount.pl -r -m     = Tabellarisch (m = multigroup)
536 uvcount.pl -r -o     = Text (o = onegroup)
537
538 Falls in usevote.cfg die Option "proportional = 1" aktiviert ist,
539 wird standardmaessig folgendes Ausgabeformat angewandt:
540
541  Ja  Nein : J>=N? Ja/Nein : ang.? : Gruppe
542 ==== ==== : ===== ======= : ===== : ====================================
543  100   70 :  Ja    1.429  :       : Einrichtung von abc
544   80   90 : Nein   0.888  :       : Einrichtung von xyz
545
546 Das genaue Aussehen ist im Template "result-proportional" aenderbar,
547 die Bedingungen und Auswertungsformeln sind ueber usevote.cfg
548 einzustellen (prop_formula und condition1). Die Spalte "ang.?" muss
549 in diesem Fall manuell ausgefüllt werden, da manchmal auch mehrere
550 Abstimmungsgegenstände angenommen werden, z.B. bei Moderationsnachwahlen
551 für verschiedene Posten.
552
553 Die Waehlerliste mit abgegebenen Stimmen erzeugst Du mit
554 "uvcount -v". Diese Option laesst sich auch mit -r kombinieren,
555 so dass Du Dir das doppelte Aussortieren von Duplikaten sparst.
556 Wichtig: Diese Liste darf erst im Result veroeffentlicht werden,
557 nicht im 2. CfV!
558
559 Falls ein trivialer Schutz vor Spammern gewuenscht ist, koennen durch
560 eine Aenderung in den Template "voterlist", "votes-single", "votes-multi"
561 und "bouncelist" alle Mailadressen verfremdet werden. Entweder Du fuegst
562 folgende Definition ein:
563
564 mail            := value mail | replace '@' ' -at - '
565
566 Oder Du veraenderst direkt die vorgegebenen Formate, indem Du
567 die Mailadresse mit Hilfe des Pipe-Symbols durch die replace-Funktion
568 schickst:
569
570 multi-line := value mail | replace '@' ' -at- ' | justify-behind name 72
571
572 Die Replace-Funktion erwartet wie im Beispiel gezeigt zwei Werte,
573 die zu ersetztende Zeichenfolge (hier das '@') und eine neue Zeichenfolge,
574 die statt dessen eingesetzt werden soll und frei gewaehlt werden kann.
575
576 Wie bereits beschrieben, sollte am Ende des 2. CfVs bzw. Results noch die
577 Liste der gebouncten Mailadressen angehaengt werden (z.B. mit dem Programm
578 uvbounce.pl) und bei Bedarf die urspruenglichen Stimmen geloescht und das
579 Ergebnis korrigiert werden.
580
581
582 11. Datenschutz
583 ===============
584
585 Zum Schutz der deutschen Wahlleiter wurden spezielle Klauseln
586 aufgenommen, die vom Waehler die Erlaubnis zur Verarbeitung
587 der Stimme verlangen. Die Option "bdsg" in usevote.cfg schaltet
588 diese Sonderbehandlung ein oder aus. Folgende Besonderheiten
589 gelten bei Aktivierung:
590
591 - Im Wahlschein ist ein spezieller Hinweistext enthalten, der
592   aus der Datei bdsgtext.cfg genommen wird. Beim Verarbeiten
593   abgegebener Stimmen wird der Abschnitt wieder mit der Datei
594   verglichen. Fehlt er oder wurde er veraendert, wird der
595   Wahlschein dem Wahlleiter zur Kontrolle vorgelegt.
596   Die Fehlerpruefung ignoriert Quote- und Leerzeichen sowie
597   Zeilenumbrueche, kann aber versagen, wenn dem Quotezeichen
598   Initialen vorangestellt sind (wie in manchen Mailboxnetzen
599   ueblich) oder eine Silbentrennung ueber den Text gelaufen ist.
600
601 - Ausserdem enthaelt der Wahlschein eine spezielle Frage,
602   die mit JA zu beantworten ist. Anderenfalls muss ebenfalls
603   Kontrolle durch den Wahlleiter erfolgen. Der Text dieser
604   Frage ist ueber usevote.cfg einzustellen.
605
606 Erfolgt eine derartige Kontroll-Vorlage beim uvvote.pl-Lauf,
607 sollte der Wahlleiter sich den Wahlschein genau anschauen
608 und dann entweder im Menue die Option (6)(a) waehlen oder
609 mit (w) fortfahren. Im letzteren Fall wird die Stimme
610 verworfen und eine Hinweismail zurueckgeschickt.
611
612 Wenn eine Wahlbestaetigung veraendert und zurueckgeschickt
613 wird, fehlt der entsprechende Datenschutzhinweis. Da in
614 diesem Fall die Zustimmung aber bereits bei der ersten
615 Stimmabgabe gegeben wurde, kann der Wahlleiter beruhigt
616 die Korrektheit wie oben beschrieben bestaetigen.
617
618
619 12. Personalisierte Wahlscheine
620 ===============================
621
622 Die Wahlregeln fuer de.* sehen im Abschnitt 6a ein Verfahren
623 mit persoenlichen Wahlscheinen vor, die mit einer speziellen
624 Kennung versehen mehr Sicherheit vor Manipulation bieten.
625
626 Um dieses Verfahren einzuschalten, muss zunaechst die Option
627 "personal = 1" in usevote.cfg gesetzt werden und das Template
628 "ballot-personal" im Unterverzeichnis "templates" um den Text
629 des CfVs erweitert werden (einfach statt des von Sternchen
630 umrandeten Kommentars in der Datei einfuegen). Bitte eventuell
631 im Text vorkommende eckige Klammern wie folgt unschaedlich
632 machen: \[Text\] (Backslash voranstellen), da in den Templates
633 diese Klammern spezielle Bedeutungen haben (siehe gesonderten
634 Abschnitt zu dem Thema in dieser Datei).
635
636 Der gepostete CfV enthaelt i.d.R. nur einen Dummy-Abschnitt
637 mit Hinweis auf die gesonderte Wahlscheinanforderung. So ein
638 Abschnitt kann mit uvballot.pl generiert werden.
639
640 Der dana-Moderation sollte beim Einreichen des CfVs auch
641 ein Dummy-Wahlschein mitgesendet werden, wie er bei der
642 Wahlscheinanforderung verschickt wird. Dieser laesst sich mit
643 "uvcfv.pl -t" erzeugen.
644
645 Die eingehenden Wahlscheinanforderungen sollten an eine
646 spezielle Mailadresse gehen und dann mit uvcfv.pl verarbeitet
647 werden. Je nach Konfiguration in usevote.cfg werden die
648 Mails aus einer Mailboxdatei oder per POP3 eingelesen und jeweils
649 mit einem personalisierten Wahlschein beantwortet. Bitte vor
650 dem Posten des CfVs einen Test durchfuehren, um sicherzustellen,
651 dass die generierten Wahlscheine korrekt sind und auch bei
652 der Auswertung akzeptiert werden (hierbei wird die speziell
653 eingefuegte Wahlscheinkennung in Verbindung mit der Absenderadresse
654 geprueft).
655
656
657 13. Die einzelnen Programme
658 ===========================
659
660 uvballot.pl
661   Generiert den Wahlschein fuer den CfV. Bei personalisierten
662   Wahlscheinen (personal = 1 in usevote.cfg) wird nur ein Dummy-
663   Abschnitt mit Hinweisen zur Wahlscheinanforderung ausgegeben.
664
665   Die Vorlage fuer den Wahlschein ist im templates-Unterverzeichnis
666   konfigurierbar:
667   - ballot               Standard-Wahlschein (personal=0)
668   - ballot-request       Dummy-Abschnitt mit Hinweisen zur
669                          Wahlscheinanforderung (personal=1)
670   - ballot-personal      Wahlschein mit Scheinkennung, wird von
671                          uvcfv.pl verwendet
672
673   Aufrufparameter:
674
675   -c config_file         liest die Konfiguration aus config_file
676                          (usevote.cfg falls nicht angegeben)
677   -h                    
678   --help                 zeigen einen Hilfetext an
679
680
681 uvbounce.pl
682   Liest Bounces aus den uebergebenen Dateien oder aus einer POP3-
683   Mailbox ein (Verhalten haengt von usevote.cfg ab) und generiert
684   eine Liste von unzustellbaren Adressen, die an den 2. CfV oder das
685   Result angehaengt werden kann. Falls POP3 in usevote.cfg
686   eingeschaltet und die Option -f (siehe unten) nicht benutzt wurde,
687   werden die uebergebenen Dateinamen ignoriert.
688
689   Die Vorlage fuer die ausgegebene Liste ist im templates-
690   Unterverzeichnis konfigurierbar (Datei "bouncelist").
691
692   Aufrufparamter:
693
694   -c config_file         liest die Konfiguration aus config_file
695   -f dateiname(n)   
696   --file dateiname(n)    lesen die Bounces aus den uebergebenen Dateien,
697                          auch wenn in der Konfigurationsdatei POP3
698                          eingeschaltet ist. Diese Option wird benoetigt,
699                          falls zwar die Stimmzettel per POP3 eingelesen
700                          werden sollen, nicht aber die Bounces.
701                          Die Dateinamen werden durch Leerzeichen getrennt.
702   -h
703   --help                 zeigen einen Hilfetext an
704
705
706 uvcfv.pl
707
708   Liest Mailboxen ein und beantwortet alle Mails mit personalisierten
709   CfVs (falls personal=1 in usevote.cfg).
710
711   Die Vorlage fuer die ausgegebene Liste ist im templates-
712   Unterverzeichnis konfigurierbar (Datei "ballot-personal").
713
714   Aufrufparamter:
715
716   -c config_file        liest die Konfiguration aus config_file
717                         (usevote.cfg falls nicht angegeben)
718   -t
719   --test                gibt einen Dummy-Wahlschein mit Scheinkennung
720                         an der Standardausgabe aus, zur Pruefungszwecken
721   -h
722   --help                zeigen einen Hilfetext an
723
724
725 uvcount.pl
726
727   Zaehlt Stimmen und gibt Waehlerlisten aus. Dient zur Erstellung
728   von 2.CfV und Result.
729
730   Es werden die folgenden Vorlagen aus dem templates-Unterverzeichnis
731   benutzt:
732
733   - result-multi       Ergebnisauszaehlung bei mehreren Gruppen
734   - result-single      Ergebnisauszaehlung bei nur einem Abstimmungs-
735                        gegenstand (nicht tabellarisch, sondern im
736                        Fliesstext), falls in usevote.cfg multigroup=0
737                        gesetzt ist oder die Option -o verwendet wird
738                        (siehe unten)
739   - voterlist          Reine Auflistung der bisherigen Waehler ohne
740                        Stimmen (fuer 2. CfV)
741   - votes-multi        Stimmenliste im Mehrgruppenformat (eine Liste
742                        mit allen Waehlern, rechts daneben die jeweils
743                        abgegebenen Stimmen)
744   - votes-single       Stimmenliste im Eingruppenformat (getrennte
745                        Listen mit Ja-, Nein- und Enthaltungsstimmen)
746
747   Aufrufparamter:
748
749   -c config_file      liest die Konfiguration aus config_file
750                       (usevote.cfg falls nicht angegeben)
751   -f result_file      liest die Stimmen aus result_file (ueberschreibt
752                       die "resultfile"-Angabe aus der Konfigurationsdatei)
753   -l
754   --list              Geben eine Liste aller Waehler aus (ohne Stimmen).
755   -v
756   --voters            Wie --list, aber mit Angabe der abgegebenen Stimmen.
757   -r
758   --result            Ausgabe des Endergebnisses (kann mit --list oder
759                       --voters kombiniert werden).
760   -m
761   --multigroup        Benutzt auch bei Eingruppenabstimmungen das
762                       Mehrgruppenformat beim Endergebnis (ueberschreibt
763                       die Einstellung aus usevote.cfg).
764                       Nur in Kombination mit --result verwendbar,
765                       schliesst --onegroup aus.
766   -o
767   --onegroup          Benutzt bei Eingruppenabstimmungen immer das
768                       Eingruppenformat beim Endergebnis (ueberschreibt
769                       die Einstellung aus usevote.cfg).
770                       Nur in Kombination mit --result verwendbar,
771                       schliesst --multigroup aus.
772   -n
773   --nodup             Verzichtet auf das Aussortieren von doppelten
774                       Stimmabgaben. Nicht empfohlen!
775   -h
776   --help              zeigen einen Hilfetext an
777
778
779
780 uvvote.pl
781
782   Liest Mailboxen aus einer Datei oder per POP3 ein wertet die Mails
783   als Stimmzettel aus. Erst beim Aufruf mit der Option "clean" werden
784   die Ergebnisse endgueltig gespeichert und die Bestaetigungsmails
785   verschickt.
786
787   Es werden diverse Vorlagen aus dem templates-Unterverzeichnis
788   benutzt, um Bestaetigungs- und Fehlermails zu generieren.
789
790   Aufrufparameter:
791
792   -c config_file       liest die Konfiguration aus config_file
793                        (usevote.cfg falls nicht angegeben)
794   -t
795   --test               fuehrt einen Test der Konfiguration durch und
796                        gibt das ermittelte Ergebnis aus.
797   -h
798   --help               zeigen einen Hilfetext an
799
800
801
802 14. Die Konfigurationsdateien
803 =============================
804
805 mailpatterns.cfg
806 ----------------
807
808 Diese Datei enthaelt einen regulaeren Ausdruck (Perl-Syntax) pro
809 Zeile. Passt die Mailadresse eines Abstimmenden auf eines der Muster,
810 wird dem Wahlleiter bei der Auswertung eine Warnung angezeigt.
811 In der Regel kann man diese ignorieren, weil heutzutage viele
812 Privatleute ihre eigene Domain haben und Role-Accounts wie news@
813 benutzen. Sieht man aber so etwas wie news@t-online.de ist
814 Vorsicht angebracht und man sollte durch Auswahl von "(W)eiter" 
815 die Stimme ungueltig werten und eine entsprechende Fehlermail
816 zurueckschicken lassen.
817
818
819 messages.cfg
820 ------------
821
822 Hier sind alle kuerzeren Texte enthalten, die Usevote ausgibt,
823 unabhaengig davon, ob sie nur dem Wahlleiter bei der Programmausfuehrung
824 ausgegeben werden oder in persoenlichen Mails bzw. dem Result
825 auftauchen. Laengere Textpassagen sind als eigene Dateien im
826 "templates"-Verzeichnis zu finden und bieten weitergehende
827 Formatierungsmoeglichkeiten.
828
829 Jede Zeile in der messages.cfg besteht aus einem Identifier, einem
830 Gleichheitszeichen und dem eigentlichen Text. Der Identifier ist
831 grundsaetzlich in Grossbuchstaben gehalten und vom Programmcode fest
832 vorgegeben. Aenderungen duerfen nur rechts vom Gleichzeichen vorgenommen
833 werden, wenn Dir z.B. Formulierungen nicht gefallen oder Du anders-
834 sprachige Ausgaben haben moechtest.
835
836 Variablen sind ueber ${VARIABLE} einzubauen, allerdings sind die
837 Variablennamen und deren Inhalte vom Programmcode vorgegeben und
838 sollten beibehalten werden. Es gibt keine vordefinierten Variablen,
839 die Du selbst einbauen kannst, es sei denn, Du erweiterst den
840 Programmcode an der entsprechenden Stelle.
841
842 Die einzigen Texte, die fest im Programmcode stehen, sind die
843 Hilfetexte der einzelnen Programme (ueber die Option -h oder --help
844 aufrufbar) sowie die Startmeldungen (Copyright etc.) und initiale
845 Fehlermeldungen (usevote.cfg oder messages.cfg nicht gefunden,
846 ungueltige oder falsch kombinierte Aufrufparameter).
847
848
849 usevote.rul
850 -----------
851
852 Mit dieser Datei koennen spezielle Regeln fuer eine gueltige Stimmabgabe
853 bei Mehrgruppenabstimmungen erstellt werden, z.B. dass man Punkt 3 oder 4
854 waehlen muss, wenn man fuer Punkt 2 gestimmt hat (quasi als weitergehende
855 Auswahlmoeglichkeit). Solche Regeln verkomplizieren aber die Abstimmung
856 und sollten nur in Ausnahmefaellen benutzt werden. Urspruenglich gedacht
857 war diese Moeglichkeit z.B. fuer .misc Gruppen, die zwangsweise bei einer
858 Aufteilung mit angelegt werden mussten. Dadurch, dass das in den
859 Wahlregeln fuer de.* als Automatismus eingebaut ist, kann man sich
860 so etwas meistens sparen. Fuer den Fall, dass bei einer vorgeschlagenen
861 neuen Gruppe der Name noch unklar ist, gibt ebenfalls das Benutzen
862 von speziellen Wahlregeln wenig Sinn, da man auch eine Meinung ueber
863 den Gruppennamen haben kann, wenn man eigentlich gegen die Gruppe ist.
864
865 Wenn Du aber ein Verfahren betreust, in dem Du solche Sonderregeln
866 benoetigst, kannst Du eine Regel pro Zeile in der folgenden Syntax schreiben:
867
868 if .jjjjj then J....
869
870 Eine Regel beginnt immer mit "if", und danach folgen eine Anzahl Symbole;
871 diese Anzahl muss gleich der Anzahl der Gruppen sein, ueber die abgestimmt
872 wird. Oben geht es also um eine Abstimmung ueber sechs Gruppen.
873 Die Symbole hinter "if" geben an, in welchem Fall diese Regel Anwendung
874 finden soll. Falls sie zutrifft, wird die Bedingung hinter "then"
875 geprueft (dort muessen nochmal so viele Symbole folgen, wie Gruppen
876 im Wahlschein vorkommen). Ist diese Bedingung nicht erfuellt, wird
877 der Wahlschein dem Wahlleiter als regelverletzend vorgelegt, und
878 wenn diese mit "(w)eiter" den Fehler bestaetigt, wird eine entsprechende
879 Fehlermeldung zurueckgeschickt und die Stimme als ungueltig gewertet.
880
881 Folgende Symbole sind erlaubt:
882
883    J   eine JA-Stimme
884    N   eine NEIN-Stimme
885    E   eine Enthaltung
886    S   eine JA- oder NEIN-Stimme
887    H   eine Enthaltung oder JA-Stimme
888    I   eine Enthaltung oder NEIN-Stimme
889    .   egal (Ja, nein oder Enthaltung)
890    j   eine oder mehrere der markierten Gruppen hat JA-Stimme
891    n    ""   ""    ""     ""     ""       ""    ""  NEIN-Stimme
892    e    ""   ""    ""     ""     ""       ""    ""  Enthaltung
893    s    ""   ""    ""     ""     ""       ""    ""  Ja- oder Nein-Stimme
894    h    ""   ""    ""     ""     ""       ""    ""  Enthaltung oder Ja-Stimme
895    i    ""   ""    ""     ""     ""       ""    ""  Enthaltung oder Nein-Stimme
896
897 Hier noch ein Beispiel:
898     if S... then .ss.
899     if .S.. then ..E.
900     if ..S. then .E..
901
902 Diese Regeln sagen: Wer fuer die erste Gruppe abstimmt, der muss auch
903 fuer die zweite und dritte Gruppe abstimmen - egal wie. Ausserdem muss er
904 (Regeln 2 und 3) sich bei 3 enthalten, wenn er bei 2 eine Stimme abgibt
905 und umgekehrt. Die vierte Gruppe wird hier gar nicht betroffen.
906
907
908 usevote.cfg
909 -----------
910
911 Dieses ist die zentrale Konfigurationsdatei fuer Usevote. Einige
912 Einstellungen sind nur einmal auf das System und Deine Gewohnheiten
913 anzupassen, andere muessen fuer jede Abstimmung geaendert werden.
914 Alle Einstellungen sind mit mehr oder weniger sinnvollen
915 Standardwerten vorgegeben, die sich bei leerer usevote.cfg mittels
916 "uvvote.pl -t" ermitteln lassen.
917
918 Es lassen sich durch eine Zeile "include dateiname" weitere 
919 Konfigurationsdateien einbinden. Die Stelle, an der dieses geschieht,
920 ist dabei wichtig, da die usevote.cfg von oben nach unten gelesen
921 wird (zusätzlich eingebundene Konfigurationsdateien werden an der
922 Stelle der "include"-Zeile eingefügt) und bei mehrmals vorkommenen
923 Optionen der jeweils letzte gesetzte Wert benutzt wird.
924 Daher sollte eine Datei mit systemweiten Defaults am besten am
925 Anfang der usevote.cfg eingebunden werden, die dort gesetzten
926 Optionen sollten aber unbedingt aus der usevote.cfg geloescht werden,
927 damit die systemweiten Einstellungen nicht gleich wieder ueberschrieben
928 werden.
929
930 Das Format ist allgemein:
931
932 Option = Wert
933
934 Der Wert muss in manchen Faellen 0 (=aus) oder ungleich 0 (=an) sein,
935 in anderen Faellen muss eine exakte Zahl oder Zeichenkette eingegeben
936 werden. 
937
938 Alles, was hinter einem # Zeichen steht, wird als Kommentar gewertet
939 und ignoriert. Steht hinter einem Wert so ein Kommentar, wird
940 normalerweise alles bis zum Kommentarzeichen noch in den String
941 einbezogen. In so einem Fall sollte der Wert von Anfuehrungszeichen
942 umschlossen werden. Im folgenden Beispiel wird ein Dateiname
943 definiert:
944
945 # Der Dateiname endet mit 10 Leerzeichen (bis zum Kommentarzeichen):
946 tpl_mailheader = mailheader          # Kommentar
947
948 # Der Dateiname enthaelt keine Leerzeichen, da mit Anfuehrungsstrichen
949 # begrenzt:
950 tpl_mailheader = "mailheader"        # Kommentar
951
952 Folgt kein Kommentar in der selben Zeile, koennen die Anfuehrungsstriche
953 weggelassen werden.
954
955 Hier eine Auflistung der immer anzupassenden Optionen
956 (BOOL bedeutet, dass 0 (aus) oder 1 (an) eingetragen werden muss):
957
958 votename         Name der Abstimmung
959 group1           Erster Abstimmungsgegenstand
960 group2           Zweiter (und so weiter durchnummerieren)
961 votefile         Mailbox mit eingehenden Stimmen (falls POP3 ausgeschaltet)
962 mailboxtype      Typ der Mailbox (mbox, maildir)
963 personal         Personalisierte Wahlscheine verwenden? [BOOL]
964                  (siehe gesonderten Abschnitt weiter oben)
965 voteaccount      Mailadresse, unter der abgestimmt werden kann
966                  (Reply-To im CfV auf diese Adresse setzen)
967 requestfile      Datei mit Anforderungsmails bei "personal=1", falls
968                  POP3 ausgeschaltet ist
969 bdsg             Datenschutzklausel generieren und auf deren Existenz 
970                  pruefen? [BOOL] (siehe gesonderten Abschnitt weiter oben)
971 replyto          Reply-To Header auswerten? [BOOL] (nicht empfohlen und in
972                  de.* von den GVV nicht praktiziert)
973 voteack          Jede Stimme mit einer Bestaetigungsmail beantworten? [BOOL]
974                  (in de.* so ueblich)
975 mailcc           weitere Mailadresse, an die eine Kopie jeder Bestaetigungs-
976                  oder Fehlermail geschickt wird (fuer Archivzwecke)
977 onestep          Mails direkt verschicken und Ergebnisse speichern? [BOOL]
978                  ("uvvote clean" Aufruf entfaellt)
979 multigroup       Fuer das Ergebnis auch bei Eingruppenabstimmung des
980                  Mehrgruppenformat waehlen? [BOOL]
981 condition1       Bedingungen fuer einen Erfolg der Abstimmung in Perl-Syntax
982 condition2       (normalerweise "$yes>=2*$no" und "$yes>=60"
983 resultfile       Datei fuer Gesamtergebnis (normalerweise ergebnis.alle)
984 idfile           Datei mit Scheinkennungen (bei "personal=1")
985 pop3             POP3 benutzen? [BOOL] (andernfalls Stimmen aus Datei lesen)
986 pop3server       POP3-Server fuer eingehende Wahlscheine
987 pop3port         POP3-Serverport (normalerweise 110)
988 pop3user         Benutzername
989 pop3pass         Passwort
990 pop3delete       Mails nach Abruf vom Server loeschen? [BOOL]
991 pop3uidlcache    Dateiname zum Speichern bereits abgerufener Mail-IDs (UIDL)
992 pop3*_req        entsprechende Optionen fuer Mailbox mit eingehenden
993                  Wahlscheinanforderungen (bei "personal=1")
994 pop3*_bounce     entsprechende Optionen fuer Mailbox mit Bounces (Fehlermails)
995                  fuer die Verarbeitung durch uvbounce.pl
996 smtp             SMTP zum Verschicken von Mails benutzen? [BOOL]
997                  Andernfalls wird direkt an den MTA uebergeben (nur Unix)
998 smtpserver       SMTP-Server
999 smtpport         SMTP-Serverport (normalerweise 25)
1000 smtpauth         SMTP-Authentication nach RFC 2554 benutzen? [BOOL]
1001 smtpuser         SMTP-Benutzername
1002 smtppass         SMTP-Passwort
1003 smtphelo         String fuer die HELO-Greeting bei SMTP (Default: Hostname)
1004 fqdn             String fuer den Host-Teil der Message-ID
1005                  (Fully Qualified Domain Name) (Default: Hostname)
1006 archivedir       Verzeichnis fuer Archivierung von verarbeiteten Stimmen
1007 tmpdir           temporaeres Verzeichnis
1008 templatedir      Verzeichnis mit Templates (Vorlagen) fuer diverse Zwecke
1009                  (normalerweise "templates", dort liegen bereits vordefinierte
1010                  Templates, die i.d.R. nicht angepasst zu werden brauchen)
1011 formats          Konvertierungsfunktionen fuer die Templates, mit Komma getrennt
1012                  (mitgelieferte UVformats.pm muss hier aufgefuehrt werden,
1013                  desweiteren koennen eigene Module mit weiteren Funktionen
1014                  hier eingebunden werden)
1015 controlfile      Name der Steuerungsdatei fuer den Mailversand (tmp/ack.control)
1016 domailfile       Name des Shellscripts zum Versenden der Bestaetigungsmails
1017                  (falls smtp=0, normalerweise tmp/domail)
1018 mailcmd          Aufruf des Mail Transfer Agents (MTA) zum Verschicken der
1019                  Bestaetigungsmails (falls smtp=0), z.B.
1020                  "sendmail -oi -oem -femail@adresse"
1021 sleepcmd         Weiteres Kommando, welches nach jeder Mail aufgerufen werden
1022                  soll (falls smtp=0). Sinnvoll ist ein "sleep x", wobei x bei
1023                  langsamen Systemen hoeher gewaehlt werden sollte.
1024 clearcmd         Shellbefehl zum Loeschen des Bildschirms (Standard: clear),
1025                  muss unter Windows auf "cls" geaendert werden. Falls Shell
1026                  oder Betriebssystem keinen solchen Befehl bereitstellen,
1027                  sollte ein Kommando verwendet werden, welches eine Trennlinie
1028                  oder aehnliches auf dem Bildschirm ausgibt, z.B. mit "echo"
1029 pager            Shellbefehl zum seitenweisen Darstellen von Mails auf dem
1030                  Bildschirm (normalerweise "less"). Unter Windows muss "more"
1031                  benutzt werden, unter Unix hingegen gibt es moeglicherweise
1032                  bei "more" Probleme mit der Umleitung von STDERR in eine Datei
1033                  (wie es z.B. von uvvote.pl benoetigt wird), daher ist "less"
1034                  der Standardwert.
1035 mailfrom         Absender fuer den From-Header der Bestaetigungsmails. Wird
1036                  auch in Bestaetigungsmails als Unterschrift eingefuegt und
1037                  sollte daher am besten in folgendem Format sein:
1038                  Vorname Nachname <gvv@foo.bar>
1039                  (ohne Anfuehrungsstriche, falls rfc-konform moeglich)
1040 envelopefrom     Absender fuer den Envelope (Return-Path) der Bestaetigungsmails
1041                  bei Verwendung von SMTP (bitte nur die Adresse eintragen, ohne
1042                  Klammern und Zusaetze). Wenn SMTP ausgeschaltet ist, muss
1043                  diese Einstellung entsprechend der Mailer-Doku in "mailcmd"
1044                  gesetzt werden (z.B. bei Sendmail und kompatiblen mit -f)
1045 messagefile      Datei mit diversen Meldungen und Textfragmenten (messages.cfg)
1046 rulefile         Datei mit Wahlregeln (usevote.rul)
1047 badaddrfile      Datei mit verdaechtigen Mailadressen (mailpatterns.cfg)
1048 errorfile        Datei fuer Fehlermeldungen beim Programmlauf (errors.log)
1049 mailstart        Einleitungszeile fuer naechste Mail (RegExp), falls Mails
1050                  aus einer Datei eingelesen werden (smtp=0), normalerweise
1051                  "^From"
1052 begin_divider    Trennlinien vor und nach dem Wahlschein
1053 end_divider      ("Alles vor/nach dieser Zeile bitte loeschen")
1054 nametext         Text fuer die Namens-Angabe im Wahlschein. Muss im
1055                  Wahlschein genauso stehen und wird beim Standardtemplate
1056                  auch aus dieser Einstellung uebernommen. Beispieltext:
1057                  "Dein Realname, falls nicht im FROM-Header:"
1058 nametext2        Text fuer Namens-Angabe in Bestaetigungsmails
1059                  (dito, Standardwert "Waehlername:")
1060 addresstext      Text fuer die Adress-Angabe im Wahlschein
1061                  (dito, Standardwert "Waehleradresse:")
1062 ballotidtext     Text für die Angabe der Wahlscheinkennung (falls personal=1)
1063                  (dito, Standardwert "Wahlscheinkennung:")
1064 bdsgtext         Text fuer Datenschutzklausel (falls bdsg=1),  erscheint als
1065                  Abstimmungspunkt (z.B. "Datenschutzklausel - Zustimmung: Ich
1066                  bin mit der Verarbeitung meiner Daten wie oben beschrieben
1067                  einverstanden")
1068 bdsgfile         Datei mit Erklaerungstext fuer BDSG-Klausel (bdsgtext.cfg)
1069 rightmargin      Zeilenbreite bei Ausgaben, die nicht durch Templates
1070                  gesteuert werden. Hat vor allem auf Bildschirmausgaben
1071                  Auswirkung.
1072 name_re          Regulaerer Ausdruck fuer Erkennung eines gueltigen Realnamens.
1073                  Beispiel: "[a-zA-ZäöüáàâéèêíìîóòôúùûÄÖÜÁÁÂÉÈÊÍÌÎÓÒÔÚÙÛß-]{2,} +
1074                  .*[a-zA-ZäöüáàâéèêíìîóòôúùûÄÖÜÁÁÂÉÈÊÍÌÎÓÒÔÚÙÛß]{2,}"
1075                  (muss ohne Umbruch in eine Zeile)
1076
1077 Regulaere Ausdruecke fuer Erkennung der Stimmen
1078 (Gross-/Kleinschreibung spielt keine Rolle):
1079
1080 ja_stimme        Standardwert: (J\s*A|J|(D\s*A\s*)?F\s*U\s*E\s*R)
1081 nein_stimme      Standardwert: (N\s*E\s*I\s*N|N|(D\s*A\s*)?G\s*E\s*G\s*E\s*N)
1082 enth_stimme      Standardwert: (E|E\s*N\s*T\s*H\s*A\s*L\s*T\s*U\s*N\s*G)
1083 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
1084
1085 Definition der verwendeten Templatedateien
1086 (werden im Unterverzeichnis "templates" mitgeliefert):
1087
1088 tpl_mailheader      "mailheader"         # generally used mail header
1089 tpl_bouncelist      "bouncelist"         # used by uvbounce.pl
1090 tpl_result_multi    "result-multi"       # used by uvcount.pl -r -m
1091 tpl_result_single   "result-single"      # used by uvcount.pl -r -o
1092 tpl_votes_multi     "votes-multi"        # used by uvcount.pl -v (multiple groups)
1093 tpl_votes_single    "votes-single"       # used by uvcount.pl -v (single group only)
1094 tpl_voterlist       "voterlist"          # used by uvcount.pl -l (2nd CfV)
1095 tpl_ballot          "ballot"             # used by uvballot.pl (personal = 0)
1096 tpl_ballot_request  "ballot-request"     # used by uvballot.pl (personal = 1)
1097 tpl_ballot_personal "ballot-personal"    # used by uvcfv.pl    (personal = 1)
1098 tpl_addr_reg        "address-not-registered"  # used by uvvote.pl   (personal = 1)
1099 tpl_no_ballotid     "no-ballotid"        # used by uvvote.pl   (personal = 1)
1100 tpl_wrong_ballotid  "wrong-ballotid"     # used by uvvote.pl   (personal = 1)
1101 tpl_bdsg_error      "bdsg-error"         # used by uvvote.pl   (bdsg = 1)
1102 tpl_ack_mail        "ack-mail"           # used by uvvote.pl   (voteack = 1)
1103 tpl_cancelled       "cancelled"          # used by uvvote.pl
1104 tpl_invalid_account "invalid-account"    # used by uvvote.pl
1105 tpl_invalid_name    "invalid-name"       # used by uvvote.pl
1106 tpl_multiple_votes  "multiple-votes"     # used by uvvote.pl
1107 tpl_no_ballot       "no-ballot"          # used by uvvote.pl
1108 tpl_no_votes        "no-votes"           # used by uvvote.pl
1109 tpl_rule_violated   "rule-violated"      # used by uvvote.pl  (siehe usevote.rul)
1110
1111
1112 15. Templates
1113 =============
1114
1115 Die mitgelieferten Templates befinden sich im Verzeichnis "templates".
1116 In usevote.cfg koennen weitere Verzeichnisse definiert werden, in
1117 denen auch nach Templates gesucht wird ("templatedir", kommaseparierte
1118 Liste mit Verzeichnissen). Außerdem koennen dort die Dateinamen der einzelnen
1119 Templates eingestellt werden, wodurch es moeglich ist, in einzelnen
1120 Abstimmungen andere, selbst definierte Templates zu verwenden, die in
1121 einem gesonderten Verzeichnis abgelegt sind.
1122
1123 Eine Templatedatei besteht aus zwei Teilen. Am Anfang werden die
1124 Formatierungen bestimmter Schluessel definiert und nach einem Trenner
1125 folgt der eigentlich Template-Koerper, der dann von Programm bearbeitet
1126 und ausgegeben wird.
1127
1128    format-key := function1 param | function2 param
1129
1130    == TEMPLATE ====================================
1131
1132    Ich bin nun das eigentliche Template:
1133
1134    format-key: [$format-key]
1135
1136 Der Trenner beginnt mit den Zeichen '== TEMPLATE' danach koennen beliebige
1137 Zeichen folgen um die beiden Sektionen optisch voneinander abzugrenzen.
1138
1139 Wenn es keine Formatierungsanweisungen gibt, kann der Trenner auch
1140 weggelassen werden. D.h. wenn kein Trenner gefunden wird, wird der
1141 komplette Text als Template-Koerper betrachtet.
1142
1143
1144 Template-Koerper
1145 ----------------
1146
1147 Im Template-Koerper werden die zu ersetzenden Token durch eckige
1148 Klammern abgegrenzt. Sollen eckige Klammern im Text ausgegeben werden,
1149 muessen diese durch einen Backslash freigestellt werden.
1150
1151    [$termersetzung] [@schleife] nur eine \[ Klammer
1152
1153
1154 Termersetzung:
1155
1156     Ersetzt den Token durch den Wert des angegeben Schluessels:
1157
1158       [$formatierung] [$schluessel]
1159
1160     Es wird zuerst nach einer Formatierung mit den entsprechenden
1161     Bezeichner gesucht. Ist diese vorhanden, werden die entsprechenden
1162     Funktionen ausgefuehrt (siehe folgender Abschnitt).
1163
1164     Kann kein Format gefunden werden, wird direkt in der im Programmcode
1165     gefuellten Datenstruktur nach einem Schluessel mit dem angegeben
1166     Bezeichner gesucht und sein Wert eingesetzt. Alle Einstellungen
1167     aus der usevote.cfg sind automatisch als Schluessel definiert, es
1168     kann also z.B. [$nametext] jederzeit verwendet werden. Eingesetzt
1169     wird an der Stelle der mit "nametext = " definierte Text aus
1170     usevote.cfg.
1171
1172     Schlussendlich ist es noch moeglich einen default-Wert zu
1173     definieren, der eingesetzt wird, wenn keiner der obigen Wege
1174     erfolgreich war:
1175
1176       Hallo [$name|Unbekannter]!
1177
1178     Diese Zeile gibt, wenn kein Name definiert wurde, das Wort
1179     "Unbekannter" aus.
1180
1181
1182 Bedingte Verzeigung:
1183
1184     Ueberprueft ob der Wert des angegebenen Formats/Schluessel boolsch
1185     WAHR ist. Dementsprechend wird der then oder else Block eingefuegt:
1186
1187       [?if|then|else] oder auch nur [?if|then]
1188
1189     Die then/else Bloecke werden natuerlich auch auf Tokens geparst und
1190     diese dementsprechend ersetzt.
1191
1192
1193 Schleifen/Listen:
1194
1195     Der nachfolgende Textblock wird fuer alle Elemente des durch den
1196     Schluessel bezeichneten Arrays ausgefuehrt und eingefuegt.
1197
1198       [@schluessel|block] oder [@schluessel|block|sep]
1199
1200     Als zweiter Parameter kann ein Separtor definiert werden, mit dem
1201     sich z.B. kommaseparierte Listen erzeugen lassen, da der Separator
1202     eben nur zwischen den Elementen eingefuegt wird.
1203
1204     Auch fuer Schleifen koennen Formatierungen genutzt werden.Allerdings
1205     darf kein String zurueckgegeben werden, sondern ein Array mit einer
1206     Menge von UVtemplate-Objekten.
1207
1208
1209 Kommentare:
1210
1211     Token die nach der Bearbeitungen entfernt werden:
1212
1213        [# mich sieht man nicht]
1214
1215
1216 Sonstiges:
1217
1218     Um in Listen einen Zeilenumbruch zu erzwingen, muss lediglich ein
1219     '\n' eingefuegt werden, falls eine kompakte Definition der Liste
1220     erfolgen soll.
1221
1222        [@names|[name] [email]\n]
1223
1224
1225 Formatierungen
1226 --------------
1227
1228 Eine Formatierung besteht eigentlich nur aus dem entsprechenden
1229 Namen und einer beliebigen Anzahl von Funktionsaufrufen:
1230
1231    format := funktion param1 "param 2" | funktion param
1232
1233 Aehnlich der Unix-Shell-Funktionalitaet, wird dabei die Ausgabe
1234 einer Funktion an die folgende weitergeleitet. So ist es moeglich,
1235 verschiedenste simple Formatierungen zu kombinieren um nicht fuer
1236 jeden Spezialfall eine neue Funktion schreiben zu muessen.
1237
1238 Die jeweilige Formatierungsfunktion erhaelt als Input die
1239 Datenstruktur, den Output der vorherigen Funktion und die definierten
1240 Parameter in der entsprechenden Reihenfolge.  
1241
1242 Zahlen und einfache Bezeichner koennen direkt definiert werden.
1243 Sollen Sonderzeichen oder Leerzeichen uebergeben werden, muessen
1244 diese gequotet werden. Dazu kann ' oder " verwendet werden.
1245
1246 Die Funktionen geben im Allgemeinen einen String zurueck. Im Rahmen
1247 von Listen können auch Arrays uebergeben werden.
1248
1249 Die erste Funktion duerfte ueblicherweise 'value' sein. Sie gibt
1250 den Wert des angegeben Schluessel zurueck, der dann von den
1251 folgenden Funktionen definiert wird:
1252
1253    name-60 := value name | fill-right 60
1254
1255 Das Format "name-60" definiert also den Wert des Schluessel "name",
1256 der um Leerzeichen aufgefuellt wird, bis eine Laenge von 60 Zeichen
1257 erreicht wird.
1258
1259    name-email := value name | justify-behind mail 72
1260
1261 "name-email" resultiert in einem String, der zwischen den Werten von
1262 "name" und "email" genau so viele Leerzeichen enthaelt, damit der
1263 gesamte String 72 Zeichen lang ist.
1264
1265 Wird dieses Format in einer Liste angewandt, erhaelt man eine Tabelle
1266 in der die linke Spalte linksbuendig und die rechte Spalte
1267 entsprechend rechtsbuendig ist.
1268
1269 Soweit ein kleiner Ueberblick ueber die Formatierungen. Ausfuehrliche
1270 Funktionsbeschreibungen und weitere Beispiele finden sich in der
1271 POD-Dokumentation des Moduls UVformat ("perldoc UVformat.pm").
1272
1273 Es ist moeglich, selbst eigene Module mit Formatierungsfunktionen
1274 zu schreiben und ueber die Option "formats" in usevote.cfg einzubinden.
1275 Am besten kann dazu UVformats.pm als Vorlage genommen werden.
1276 Wichtig: der Name einer Formatierungsfunktionen darf nur aus
1277 Gross- und Kleinbuchstaben, Zahlen und Minuszeichen bestehen.
1278 Unterstriche, Punkte etc. sind nicht erlaubt!
1279
1280 Falls eine elementare Funktion fehlt, kannst Du Dich auch gerne
1281 bei mir melden und ich pruefe, wie sie sich einbauen laesst.
1282
1283 Marc Langer, im Oktober 2005
This page took 0.203669 seconds and 2 git commands to generate.