\documentstyle[prelim,german,11pt]{article} \def\db2tex{db2\TeX} %\input{/u1/tex/art_kopf.tex} % lokale Din-A4-Anpassung \addtolength{\textheight}{-1cm} % damit "Entwurf" gedruckt werden kann \sloppy \title{Erstellung von Serienbriefen o.\"a.~mit Hilfe des Programms \db2tex-1.3\footnote{Datei: {\tt db2tex.deu}, Satzprogramm: \TeX/\LaTeX, Computer: Targon/35}} \author{Dr.~Henning Astheimer} \begin{document} \maketitle \input{/u1/tex/ag_edv.tex} e-Mail: astheimer@imdm.uke.uni-hamburg.dbp.de \tableofcontents \listoffigures \newpage \section{Einleitung} Das Programm \db2tex\ kann z.B.~zur Erstellung von Serienbriefen verwendet werden. Es f\"ugt tabellierte Angaben -- Text und/oder Zahlen -- zeilenweise an den gew\"unschten Stellen in ein Formular ein. Je Tabellenzeile entsteht dabei ein Exemplar des Serienbriefes. Als Formulare verwenden wir ein \LaTeX-Dokument, z.B.~einen Brief im hauseigenen "`UKE-Stil"', der den f\"ur alle Empf\"anger gleichlautenden Text sowie die Platzhalter enth\"alt. Die Tabelle kann per Hand erstellt werden oder eine Datenbank-Ergebnistabelle sein, welche als Betriebssystemdatei gespeichert wurde. Folgende Schritte werden durchlaufen: \begin{enumerate} \item Erstellen des \LaTeX-Formulars mit den Namen der einzuf\"ugenden Tabellenfelder (Beisp.~{\tt formular.tex}). \item \"Andern des \LaTeX-Formulars zum Gebrauch mit \db2tex\ (Beisp.~{\tt brief.tex}). \item Erstellen der Tabelle (Beisp.~{\tt adressen.tab}) \dots \begin{itemize} \item als Datenbankextrakt oder \item im Editor \end{itemize} \item \"Ubergabe des Formulars und der Tabelle an \db2tex \item Anschauen oder Ausdrucken der Serientexte \end{enumerate} Diese Gebrauchsanleitung ist \"uberwiegend allgemeing\"ultig gehalten; einige wenige lokale Randbemerkungen sind in Fu\ss{}noten untergebracht. \section{Erstellen des \LaTeX-Formulars} Anhand eines einfachen Beispiels (Rundschreiben an drei gute Bekannte) soll im folgenden die Verwendung des Programms \db2tex\ demonstriert werden. Das Verfahren ist nat\"urlich mit beliebigen \LaTeX-Dokumentstilen verwendbar, wobei die jeweils dort g\"ultigen Regeln zu beachten sind. Zur Planung eines neuen Schreibens -- als Beispiel siehe Abb.~\ref{formular} -- empfieht es sich, die zu verwendenden Tabellenfelder in Gro\ss{}buchstaben einzuf\"ugen. Das ist sehr anschaulich und auch zur Dokumentation der eigenen Arbeit n\"utzlich. Der erstellte Formbrief wird in gewohnter Weise\footnote{(bei uns mit dem \TeX-Men\"u {\tt te\/})} solange ver\"andert (editiert -- ausgedruckt -- angesehen), bis er gef\"allt. %\_\hrulefill\ \\ \begin{figure}[h] \caption{Beispielformular {\tt formular.tex}} \label{formular} \begin{verbatim} \documentstyle[german,11pt]{article} \begin{document} An \\ VORNAME NAME \\ STRASSE \\ PLZ ORT \bigskip Wir laden Sie hiermit herzlich zu unserer Weihnachtsfeier ein! \\ Mit freundlichen Gr\"u\ss{}en, ... \end{document} \end{verbatim} \end{figure} %\_\hrulefill\ \\ Danach schreibt man in die erste Zeile, d.h.~noch vor {\tt documentstyle ...} die Namen der im Formular verwendeten Platzhalter -- in der Reihenfolge, wie sie in der Tabelle erscheinen! -- beginnend mit {\tt \%\$}, z.B. \begin{verbatim} %$ NAME VORNAME STRASSE PLZ ORT \end{verbatim} Die Platzhalter selbst m\"ussen nun im restlichen Formular ebenfalls durch vorangestellte {\tt \%\$} als solche dem Programm \db2tex\ kenntlich gemacht werden (siehe Abb.~\ref{brief}). Die Gro\ss{}- und Kleinschreibung der Spaltennamen sollte einheitlich sein; "`{\tt Name}"' und "`{\tt NAME}"' sind f\"ur \db2tex\ zwei unterschiedliche W\"orter. \begin{figure}[h] \caption{Beispielbrief {\tt brief.tex}} \label{brief} %\_\hrulefill\ \\ \begin{verbatim} %$ NAME VORNAME STRASSE PLZ ORT \documentstyle[german,11pt]{article} \begin{document} An \\ %$VORNAME %$NAME \\ %$STRASSE \\ %$PLZ %$ORT \bigskip Wir laden Sie hiermit herzlich zu unserer Weihnachtsfeier ein! \\ Mit freundlichen Gr\"u\ss{}en, ... \end{document} \end{verbatim} %\_\hrulefill\ \\ \end{figure} \section{Erstellen der Tabelle} Als \"Uberschrift stehen in der ersten Zeile die Spaltennamen; in der zweiten Zeile folgen Gedankenstriche {\tt ---}, an deren L\"ange \db2tex\ die Feldbreiten der Spalten erkennt; darunter folgen die Daten, je ein Datensatz pro Zeile. Man kann die Tabelle entweder manuell mithilfe eines beliebigen Editors erstellen oder als "`Datenbankextrakt"'; der beschriebene Aufbau mu\ss{} in beiden F\"allen gegeben sein. Falls Daten aus der Datenbank in den Formbrief eingesetzt werden sollen, mu\ss{} man diese als Ergebnistabelle einer Datenbankanfrage in eine Betriebssystemdatei schreiben. Dies geht z.B.~mit Hilfe der Abfragesprache SQL folgenderma\ss{}en: \begin{verbatim} SELECT name, vorname, strasse_hausnr, plz, ort FROM datenbanktabelle WHERE plz BETWEEN 2300 AND 8000 REPORT; PUT 'adressen.tab' \end{verbatim} Dabei werden alle ausgew\"ahlten Namen, Vornamen, usw.~aus einer (richtig zu benennenden) Datenbanktabelle in die Datei {\tt adressen.tab} geschrieben. \begin{figure}[h] \caption{Beispieltabelle {\tt adressen.tab} f\"ur den Mahnbrief} \label{tabelle} %\fbox{ %\_\hrulefill\ \\ \begin{verbatim} NAME VORNAME STRASSE-HAUSNR PLZ ORT -------- --------- --------------- ---- ------------ Mueller Jan Neustr. 19 2300 Kiel 1 Meier Hannes Altstr. 29 6000 Frankfurt 60 Schulze Alois Mittelstr. 22 8000 Muenchen 44 \end{verbatim} %\_\hrulefill\ \\ % } \end{figure} In der {\tt SELECT}-Anweisung sollte man die genaue Reihenfolge der Spaltennamen beachten, da sie mit der Reihenfolge der Spaltenvariablen in der ersten Zeile des Formbriefes \"ubereinstimmen mu\ss{}. Die Benennung mu\ss{} nicht genau \"ubereinstimmen! Der Abstand zwischen den Spalten\footnote{Bitte im Setup des Programms {\tt QUERY} den "`Separator"' ber\"ucksichtigen und in der {\tt ini.}-Datei definieren!} sollte mindestens drei Leerzeichen betragen oder gem\"a\ss{} der Definition in der {\tt .ini}-Datei (siehe Abb.~\ref{ini}) definiert sein. Fehlende Werte sollten nach Wunsch -- aber \TeX-kompatibel -- gekennzeichnet werden; die verwendete Kennzeichnung wird nat\"urlich nicht nur in die Ergebnistabelle \"ubernommen, sondern sp\"ater auch im Serienbrief genau so ausgedruckt! Das Nichteinhalten dieser Regeln hat nach dem Aufruf des Programms \db2tex\ meist eine Flut von Warnungen und Fehlermeldungen zur Folge. Dabei gilt, da\ss{} grobe Formatverst\"o\ss{}e mit Fehlermeldungen und Programmabbruch beantwortet werden, w\"ahrend leichtere Vergehen (wie z.B. bei Verwendung unbekannter Spaltennamen im Formblatt) nur Warnungen ohne Programmabbruch hervorrufen. \section{\"Ubergabe des Formulars und der Tabelle an \db2tex } \subsection{Programmaufruf ohne Parameter} Wird \db2tex\ ohne Parameter aufgerufen, so werden die Standard-Dateinamen (default file names) verwendet, d.h.~\db2tex\ erwartet, da\ss{} es im aktuellen Verzeichnis die Tabelle in einer Datei namens {\tt db2tex.rep} findet und das \LaTeX-Formular in einer Datei namens {\tt db2tex.tex}. \begin{verbatim} Betriebssystem> db2tex \end{verbatim} \subsection{Aufruf mit Tabellen- und Formularname} In den meisten F\"allen, z.B.~um in einem Verzeichnis mehrere Formulare und Tabellen benennen zu k\"onnen, ist es sinnvoller, das Programm mit den Namen der Tabelle und des Formbriefes aufzurufen: \begin{verbatim} Betriebssystem> db2tex adressen.tab brief.tex \end{verbatim} \subsection{Sonstiges} Die allgemeine Form des Programmaufruf sieht folgenderma\ss{}en aus: \begin{verbatim} Betriebssystem> db2tex [-chq] [-n rep-lines] [-o out-file] [TeX-file] [rep-file] \end{verbatim} Eine Kurzbeschreibung der Aufrufm\"oglichkeiten des Programms \db2tex\ erh\"alt man durch \begin{verbatim} Betriebssystem> db2tex -h \end{verbatim} Danach bekommt man auf dem Bildschirm folgende Auskunft: %\fbox{ \begin{verbatim} Options: -c : compile only -n : set max. report lines -o : set output file name -q : quiet running -h : this help text Default file name: db2tex.tex \end{verbatim} %} {\bf Erl\"auterungen:} \begin{description} \item[-c] Bei Verwendung dieser Option ruft \db2tex\ das \TeX-System nicht auf. Aus diesem Grund bleiben alle Zwischendateien, die w\"ahrend des Programmlaufs erzeugt wurden, erhalten. Diese Option ist f\"ur Kontrollzwecke gedacht, um die Zwischenergebnisse noch einmal genau unter die Lupe nehmen zu k\"onnen, n\"amlich den bearbeiteten Formbrief mit der Endung {\tt .def}, in unserem Beispiel {\tt brief.def} und die Tabellendaten mit der Endeung {\tt .inp}, in unserem Beispiel {\tt brief.inp}. \item[-n AnzahlZeilen] Mit dieser Option l\"a\ss{}t sich der Wert f\"ur die maximale Anzahl der aus der Report-Datei einzulesenden Zeilen festlegen. Dies ist ganz hilfreich, um sich kleine Probeausgaben zu erstellen; in der Testphase gen\"ugen sicher 2-3 Serienexemplare aus einer u.U.~recht langen Adre\ss{}liste. \item[-o Ausgabedatei] Hiermit kann man den Namen der Ausgabedatei festlegen. Die interaktive Abfrage nach Bildschirm- oder Druckerausgabe entf\"allt. \item[-q] Mit dieser Option l\"auft das Programm ohne jede Bildschirmausgabe und eignet sich z.B.~als Hintergrundproze\ss{}. Beispiel: {\tt db2tex -q brief.tex beispiel.tex \&; /usr/games/rogue}. Ergebnis: w\"ahrend \db2tex\ arbeitet, bleibt Zeit f\"ur ein kleines Spielchen. Warnungen und Fehlermeldungen werden werden allerdings nicht unterdr\"uckt. Auch hier entf\"allt die interaktive Abfrage nach Bildschirm- oder Druckerausgabe; das Ergebnis wird automatisch auf den Drucker geleitet. \item[-h] Ausgabe des Hilfstextes (siehe oben). \end{description} W\"ahrend des Programmlaufs gibt \db2tex\ eine Liste der verarbeiteten Dateien aus und erwartet (nach fehlerfreier Ausf\"uhrung) eine Eingabe des Benutzers (e, b oder d) auf die Frage, ob abgebrochen oder das Ergebnis auf den Bildschirm oder auf den Drucker geleitet werden soll. \section{Die Datei {\tt db2tex.ini}} Einige Grundeinstellungen sind im Programm \db2tex\ fest vorgegeben. Um etwas flexibler zu sein, werden \"Anderungsm\"oglichkeiten auf zwei Ebenen angeboten: \begin{enumerate} \item Systemweit von den Vorgaben abweichende Einstellungen k\"onnen in einer Datei {\tt db2tex.ini} definiert werden, die im selben Verzeichnis wie das Programm selbst stehen mu\ss{}. \item Benutzerbezogen kann eine zweite Datei {\tt db2tex.ini} im aktuellen Verzeichnis stehen, von wo aus das Programm aufgerufen wird und wo sich auch die Tabellen- und Formulardateien befinden. \end{enumerate} Ein Beispiel f\"ur die Datei {\tt db2tex.ini} befindet sich in der Abb.~\ref{ini}; die Syntax ist angelehnt an die Konventionen von UNIX-Shellskripten. \section{Besonderheiten} \subsection{Fehlende Werte in der Tabelle} Fehlende Werte werden in einer Datenbank f\"ur gew\"ohnlich speziell behandelt ({\em NULL-Wert\/}). Bei der Ausgabe (Bildschirm, Datei oder Drucker) mu\ss{} f\"ur sie ein Symbol vereinbart werden, z.B.~`\dag'. Zum Zweck der Datensichtung ist dieses Verfahren gut brauchbar, da fehlende Werte deutlich gekennzeichnet sind. Nur in den seltensten F\"allen ist das Zeichen `\dag' \ allerdings in einem Serientext sinnvoll. Im einfachsten Fall kann man -- falls die Tabelle noch nicht existiert -- in der Datenbank ein Leerzeichen als Nullwert definieren, oder -- falls eine Tabelle schon existiert -- ersetzt man die unerw\"unschten Nullwerte im Editor durch Leerzeichen. Schwieriger wird es, falls eine ganze Textpassage des Formbriefes sinnvollerweise entfallen m\"usste, wenn einzusetzende Daten in dieser Passage des Serientextes Nullwerte aufweisen. Vielleicht ist es in einzelnen F\"allen noch ertr\"aglich, dann fehlende Zahlen im Text als {\em ` \dots Nicht gemessen! \dots '\/} auszugeben; wenn jedoch Text fehlt, wird es schon schwieriger, eine f\"ur alle Spalten passende Formulierung zu finden. Zudem ist es meist nicht m\"oglich, mehrere fehlende Werte f\"ur verschiedene Spalten zu vereinbaren. \subsection{Individuelle Anreden} Falls man einen Rundbrief verschicken und einen Teil der Adressaten mit {\em Du\/}, den anderen Teil mit {\em Sie\/} anreden m\"ochte, mu\ss{} man diese Aufgabe in zwei Durchg\"angen erledigen. In der Datenbank ben\"otigt man einen Schalter, der anzeigt, wie man jede Person anredet. Im ersten Durchgang schreibt man dann einen Formbrief mit der {\em Du-\/}Anrede und extrahiert nur die passenden {\em Du-\/}Adressen. Im zweiten Durchgang ver\"andert man die Anrede im Formbrief und f\"uttert \db2tex\ mit den {\em Sie-\/}Adressen. Meines Erachtens gibt es f\"ur dieses Problem keine automatisierbare L\"osung, da verschiedene Anreden auch grammatikalische \"Anderungen im Text des Formularbriefes mit sich bringen. \section{Hinweise f\"ur die Installation von \db2tex} \subsection{Programmentwicklung} Das Programm wurde von Dr.~Henning Astheimer konzipiert, von Bernd Paradies programmiert und wird z.Zt.~von Klaus Rath betreut. Es ist in "`C"' geschrieben und wurde unter dem Betriebssystem AT\&T-UNIX V mit einem Kernighan/Ritchie-Compiler getestet. Es ist seit Ende 1990 bei uns in Gebrauch. Wir stellen das Programm im Sinne der Copyright-Bestimmungen der {\em Free Software Foundation -- GNU\/} als "`public domain - Programm"' zur Verf\"ugung und w\"urden uns freuen, wenn andere Personen dazu beitragen wollten, durch geeignete Erg\"anzungen eine Lauff\"ahigkeit auf anderen Computern zu erm\"oglichen. Der Programmname, die Dokumentation und die Quelltexte d\"urfen nur f\"ur den eigenen Gebrauch lokal ver\"andert werden; die Herkunft mu\ss{} dennoch weiterhin ersichtlich sein. \"Anderungen d\"urfen nicht direkt weitergegeben werden, sondern sollen an den Autor r\"uckgemeldet werden. Bitte protokollieren Sie die vorgenommenen \"Anderungen, z.B.~Precompiler-defines oder Optionen im Makefile und schicken Sie eine Kopie an die o.g.~Adresse, am besten per e-mail (astheimer@imdm.uke.uni-hamburg.dbp.de). Falls das Programm sich bew\"ahrt und gen\"ugend Bedarf gegeben scheint, kann es in der Zukunft \"uber einen Fileserver, z.B.~von DANTE e.V., anderen Interessenten zur Verf\"ugung stehen. \subsection{Ben\"otigte Dateien} \begin{figure}[h] \caption{Beispiel f\"ur die Initialisierungsdatei {\tt db2tex.ini}} \label{ini} %\fbox{ %\_\hrulefill\ \\ \begin{verbatim} # ----------------------- # INI-File fuer : db2tex # ----------------------- # - Kommentare wie in Shell-Skripten oder auch ganz frei, solange nicht # ab der ersten Spalte eines der z.Zt. 15 Schluesselwoerter mit einem # folgenden Gleichheitszeichen steht. Kommentare auf derselben Zeile # wie Options-Setzungen muessen durch mindestens ein BLANK getrennt # werden. # # - Setzung der Optionen immer am Zeilenanfang in der ersten Spalte: # VAR=wert <<<---------------- ohne BLANKS, wie in Shellskripten # # - Die Schluesselwoerter PRINTER und TEXPOOL duerfen auch mit Umgebungs- # variablen belegt werden, z.B.: # PRINTER=$TEXDRUCKER <<------ siehe auch weiter unten # DATEI-NAMEN TEXT=dbwork.txt # REPORT=dbwork.rep # DEF=dbwork.def # Zwischendatei INPUT=dbwork.inp # Zwischendatei DVI=dbwork.dvi # #OUTPUT=dbwork.out # optional # OPTIONEN QUIET=noe # Einzig wirksame Belegung: yes COMPILE_ONLY=nein # Einzig wirksame Belegung: yes SEP=" " #OUTDEV=/dev/tty # TEX !! TEXPOOL muss vor VIRTEX und DVIxxx definiert werden !! # !! da diese relativ zu TEXPOOL angegeben werden !! TEXPOOL=/usr/local/lib/tex VIRTEX=virtex "&"lplain DVITPS=dvitps/dvitps -d forward -E 0 -H-16mm -V-30mm -q #DVITPS=dvijep -b -eTEXFONTS=/u1/tex/fonts -q -x5mm -y9mm DVITTY=dvitty -Fpg #PRINTER=${TEXDRUCKER:-mdlraw} # z.B. hpk5raw UMLT2TEX=umlt2tex \end{verbatim} %\_\hrulefill\ \\ % } \end{figure} \begin{figure}[h] \caption{Die ben\"otigten Dateien} \label{datei} \begin{center} \begin{tabular}{|l|l|} \hline Dateiname & Bedeutung \\\hline\hline Makefile & Kompilierdatei \\ adressen.tab & Beispieladressen \\ brief.tex & Beispielbrief \\ convent.h & Precompilerdatei \\ db.bat & Aufrufdatei \\ db2tex.c & Hauptprogramm \\ db2tex.tex/deu& Dokumentation \\ db2tex.h & Headerdatei \\ db2tex.ini & Initialisierungsdatei \\ db\_tex.c & Funktionen f\"ur \TeX-Ausgabe \\ formular.tex & Beispielformular \\ \hline \end{tabular} \end{center} \end{figure} \end{document}