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