Initial commit

1 files changed, 397 insertions, 0 deletions

diff --git a/support/db2tex/db2tex.tex b/support/db2tex/db2tex.tex
new file mode 100644
index 0000000000..265427bfb2
--- /dev/null
+++ b/support/db2tex/db2tex.tex
@@ -0,0 +1,397 @@
+\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}