summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/adrconv/adrguide.tex
blob: ef5cd5ab908e0b3193d9bab4731b3d0a61ae0a52 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
%% adrguide.tex
%% Copyright 2006 Axel Kielhorn
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2003/12/01 or later.
%
% This work has the LPPL maintenance status "maintained".
% 
% This Current Maintainer of this work is Axel Kielhorn (A.Kielhorn@web.de)
%
% This work consists of the files adrconv.ins, adrconv.dtx, adrguide.tex
% and the derived file adrguide.pdf. 
%
% Use
%   tex adrconv.ins
% or
%   latex adrconv.ins
% to generate the other files, which are indirect parts of the
% bundle. Use
%   latex adrconv.dtx
% to generate the implementation documentation. Use
%   latex adrguide.tex
% to generate the user documentation.

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage{ae}
\usepackage{german}

\newcommand*{\File}[1]{\texttt{#1}}
\newcommand*{\Class}[1]{\textsf{#1}}
\newcommand*{\Macro}[1]{\texttt{\textbackslash #1}}

\DeclareRobustCommand{\KOMAScript}{\textsf{K\kern.05em O\kern.05em%
      M\kern.05em A\kern.1em-\kern.1em Script}}

\title{ADRconv Anleitung\\Version 1.2c}
\author{Axel Kielhorn\thanks{A.Kielhorn@web.de}}
\date{19. April 2006}
\begin{document}

\maketitle

\section{Adressdatenbanken}\label{sec:adrconv.database}

Wenn Sie Adressdateien zum Briefschreiben verwenden m"ussen Sie sich selbst
um die Ordnung in einer solchen Datei k"ummern. Falls Sie nur gelegentlich
und mit einem leicht "uberschaubaren Adressatenkreis per Brief
korrespondieren, werden Sie mit den bisher gezeigten M"oglichkeiten meist
auch zufrieden sein. Wenn jedoch die Menge der Adressen zunimmt und auch der
Umfang der Adressinformationen "uber die blo"se Postanschrift hinausw"achst,
beginnt die Verwaltung der Adressen zu einem eigenen Problem zu werden.
Dieses Problem besteht zun"achst ganz unabh"angig davon welche Briefklasse
Sie verwenden, und so war auch die L"osung, die Gerd Neugebauer 1994
vorstellte, nicht auf \KOMAScript{} und dessen Vorg"anger, sondern auf
Bib\TeX{} bezogen. Sein Bibliographie-Stil \File{address.bst} in Verbindung
mit einem speziell definierten Eintragstypen f"ur Bib\TeX-Datenbanken und
einer \File{tex}-Datei machte sich den Umstand zunutze, dass Bib\TeX{} in
der Lage ist, strukturierte Daten zu sortieren und in konfigurierbaren
Listen auszugeben. Bib\TeX{} kann somit als Hilfsprogramm eingesetzt werden,
das f"ur Ordnung in Adressdatenbest"anden sorgt.

Damit Bib\TeX{} eine Datei bearbeiten kann, muss diese in einem 
bestimmten Format vorliegen. Normalerweise besitzt eine solche Datei 
die Dateinamenserweiterung \File{bib} und enth"alt bibliographische 
Daten. Diese Daten werden nach Eintragstypen klassifiziert. Es ist 
m"oglich, neue Eintragstypen zu bilden und von Bib\TeX{} auswerten zu 
lassen.%
\footnote{Die f"ur \LaTeX{} standardm"a"sig definierten Eintragstypen,
ihr formaler Aufbau und die Funktionsweise von Bib\TeX{} "uberhaupt
k"onnen hier nicht beschrieben werden. F"ur sie sei auf die
Originaldokumentation in \textsf{btxdoc} und \textsf{btxhak}
sowie auf die Beschreibung im \LaTeX-Handbuch verwiesen.}

Unter einer \emph{Adressdatenbank} verstehen
wir eine Bib\TeX-konforme Datei.
\begin{verbatim}
  @address{...}
\end{verbatim}

F"ur Eintr"age in einer Adressdatenbank gibt es den 
speziellen Eintragstyp \verb|@address|. Das folgende Beispiel 
beschreibt das Format eines \verb|@address|-Eintrags 
in einer \File{bib}-Datei:


\begin{small}
\begin{verbatim}
  @address{HMUS,
     name =      {Hans Mustermann},
     title =     {Mag. art.},
     organization = {Verband der Vereine},
     city =      {Heimstatt},
     zip =       01234,
     country =   {Germany},
     street =    {Mauerstra{\ss}e 1},
     phone =     {01234 / 5 67 89},
     fax =       {01234 / 5 67 89},
     mobile =    {0171 / 45 67 89},
     email =     {hm{@}work.com},
     url =       {http://www.work.com},
     note =      {Alles nur Erfindung},
     key =       {HMUS},
     birthday =  {13. August anno muri},
     nbirthday = {0813}
  }
  @address{OEKZ,
     name =      {{{"O}kologisches Zentrum~e.\,V.}},
     sortas =    {Okologisches Zentrum},
     organization = {Verband der Vereine},
     city =      {Heimstatt},
     zip =       01234,
     country =   {Germany},
     street =    {Mauerstra{\ss}e 1},
     phone =     {01234 / 5 67 89},
     fax =       {01234 / 5 67 89},
     email =     {hm{@}work.com},
     key =       {OEKZ},
  }
\end{verbatim}
\end{small}

"Ahnliche Mustereintr"age wie diesen finden Sie in der Datei
\File{example.bib}. Die Adresseintr"age
dort sind jedoch weniger umfangreich. Die hier dargestellte
ausf"uhrliche Form zeigt die Version~1.2.

\begin{description}
	\item[name]  Der Name im normalen Bib\TeX\ Format: Vorname von 
	Nachname
	
	\item[sortas] Wenn der Name mit einem Umlaut beginnt, wird er falsch
	einsortiert, bei der Verwendung von UTF-8 kodierten Datenbanken kommt
	es sogar zu einem Bib\TeX\ Fehler. \texttt{sortas} hat Vorrang vor
	\texttt{name}. (Neu in Version 1.2c.)

	\item[title] Akademischer Titel oder "ahnliches (Wird z.\,Zt.  
	nicht unterst\"{u}tzt)
	
	\item[organization] Organisation, Firma, Gewerkschaft, Verein 
	(Wird z.\,Zt.  nicht unterst\"{u}tzt)
	
	\item[city]  Stadt
	
	\item[country] Das L"anderkennzeichen (Wird z.\,Zt.  nicht 
	unterst\"{u}tzt)

	\item[zip]  Postleitzahl (ZIP-Code ist die US Bezeichnung)

	\item[street]  Stra"se

	\item[phone]  Telefonnummer
	
	\item[mobile] Zweite Telefonnummer, z.\,B. f"ur Mobiltelefon

	\item[fax] Telefaxnummer, wird von \File{adrfax.bst} zum 
	Erstellen eines Telefaxbuches verwendet.
	
	\item[email] E-mail Adresse, wird von \File{email.bst} zum 
	Erstellen eines E-mail Verzeichnisses benutzt.
	
	\item[url] Ein Link auf die Homepage. Hier w"are jetzt ein Konverter 
	nach HTML gefragt.
	
	\item[key]  Das K"urzel unter dem der betreffende Name in 
	{\KOMAScript} Briefklasse aufgerufen werden kann. Dieses K"urzel muss
	f"ur alle \texttt{bib} Dateien eindeutig sein. 

	\item[note]  Notiz (Wird z.\,Zt. nicht unterst\"{u}tzt)
	
	\item[birthday] Geburtstagstext, so wie er gedruckt wird
	
	\item[nbirthday] Numerischer Geburtstag, wird zum Sortieren 
	verwendet. Format: Monat zweistellig Tag zweistellig (MMDD)
\end{description}

\section{Adressdatenbankkonverter}%

Bib\TeX{} erzeugt aus \File{bib}-Dateien (Datenbanken) \File{bbl}-Dateien.
Eine \File{bbl}-Datei besteht im wesentlichen aus einer sortierten Liste.
Welche Elemente einer \File{bib}-Datei hierf"ur ausgewertet werden und wie
die resultierende \File{bbl}-Datei im einzelnen aufgebaut ist, wird dabei
jeweils durch einen Bibliographie-Stil (eine \File{bst}-Datei) gesteuert. 

Die standardm"a"sig f"ur die Erzeugung von Literaturverzeichnissen mit
\LaTeX{} eingesetzten Bibliographie-Stile k"onnen freilich weder
\verb|@address|-Eintragstypen auswerten noch Adressdateien im
\File{adr}-Format erzeugen.  Um eine Adressdatenbank in eine Adressdatei zu
konvertieren, wird also ein eigens daf"ur eingerichteter Bibliographie-Stil
ben"otigt.  Es wurden daf"ur mehrere Bibliographie-Stile entwickelt, die als
Konverter von Adressdatenbanken in Adressdateien dienen k"onnen.

\begin{description}

	\item[\File{adrconv.bst}] Erzeugt eine Adressdatei, die sowohl mit
	der {\KOMAScript} Briefklasse zum Einf"ugen von Adressen in
	Briefe als auch mit den Programmen \File{dir.tex} und
	\File{phone.tex} zur Erzeugung von Adress- und
	Telefonverzeichnissen verwendet werden kann. Es werden dabei
	jeweils die ersten vier Felder sowie das achte Feld der
	Adress-Eintr"age (\emph{Name}, \emph{Vorname},
	\emph{Adresse}, \emph{Telefonnummer} und \emph{K"urzel})
	belegt. Die Adress-Eintr"age in der Datei werden
	alphabetisch nach den Namen sortiert und die
	\Macro{adrchar}-Eintr"age werden am Beginn jeder
	Buchstabengruppe automatisch eingesetzt. Das K"urzel wird
	als Ged"achnisst"utze mit ausgegeben. Mit diesem K"urzel
	kann der Eintrag in der Briefklasse aus {\KOMAScript}
	aufrufen werden.
	
     \item[\File{adrfax.bst}]  Ein Konvertierer zum Erstellen von
     Faxb"uchern. Statt der \emph{Telefonnummer} wird hier jedoch
     die \emph{Faxnummer} benutzt. 
     
     \item[\File{birthday.bst}] Erzeugt eine Adressdatei, die mittels
     \File{dir.tex} als Geburtstagsverzeichnis ausgegeben werden
     kann.  Hierf"ur werden die Eintr"age nach Monat und Tag
     sortiert. Damit das funktioniert, mu"s ein \emph{nbirthday}
     Eintrag vorhanden sein. Dieser wird als Sortierschl"ussel
     genutzt.

     \item[\File{email.bst}] Erzeugt eine Adressdatei, die durch Bearbeitung
     mit \File{dir.tex} ein E-Mail-Verzeichnis ergibt. Sie ist alphabetisch
     nach Namen sortiert.

\end{description}

\section{Ablauf der Konvertierung}

Damit Bib\TeX{} eine Adressdatenbank mit Hilfe eines 
Bibliographie-Stils in eine Adressdatei konvertieren kann, ben"otigt 
es noch Informationen dar"uber, welche der Eintr"age aus der 
\File{bib}-Datei auf diese Weise bearbeitet werden sollen. 
Diese Informationen entnimmt Bib\TeX{} der \File{aux}-Datei, die beim 
\TeX-Lauf "uber eine \File{tex}-Datei entsteht und die 
Schl"usselw"orter f"ur Bib\TeX{} enth"alt, welche normalerweise durch 
\Macro{cite}-Befehle in der \File{tex}-Datei erzeugt werden.

In unserem Fall gibt es keine derartige \File{tex}-Datei.
Stattdessen m"ussen wir uns eine Hilfsdatei anlegen.
\begin{verbatim}
    \citation{*}
    \bibstyle{adrconv}  % oder adrfax, birthday, email
    \bibdata{example}   % koennen auch mehrere Dateien sein
\end{verbatim}

\verb+\citation{*}+ w"ahlt alle Eintr"age der Datenbank aus, 
\verb+\bibstyle+ den gew"unschten Stil und \verb+\bibdata+ die 
Datenbank(en). Es k"onnen auch mehrere Datenbanken gleichzeitig 
ausgew"ahlt werden. Dadurch kann man private und berufliche Adressen 
in unterschiedlichen Datenbanken pflegen und bei Bedarf eine 
gemeinsame Adressliste erstellen.

Die von Bib\TeX\ erstellte \File{bbl} Datei muss dann nur noch in 
\File{adr} umbenannt werden und schon kann sie mit \File{dir.tex} 
in ein Adressbuch umgewandelt werden. Das beiliegende \File{adrdir.tex} 
enth"alt eine etwas modifizierte Version von \File{dir.tex}. Diese 
Version kann "uber Konfigurationsdateien f"ur verschiedene Formate 
angepasst werden:

\begin{description}
    \item[adrdir]  Das Originalformat aus \File{dir.tex}, die 
    Einzelseiten sind DIN A6 gro"s und k"onnen so platzsparend auf DIN 
    A4 ausgedruckt werden.

    \item[adrschmal]  Ist ein etwas schmaleres Format, das in viele 
    Taschenkalender passt, z. B. in den Kalender den mir meine 
    Sparkasse jedes Jahr schenkt.

    \item[adrplaner]  Diese Woche hatte Aldi einen Taschenkalender im 
    Angebot, wie "ublich auch mit Adressbuch. Aber warum soll ich 
    jetzt alle Adressen von Hand eintragen, also musste eine neue 
    Konfigurationsdatei her. Die sollte problemlos auch in andere 
    Organizer passen. (Ich w"urde mich "uber R"uckmeldungen freuen.)
\end{description}

In den Konfigurationsdateien befinden sich auch die Parameter f"ur 
DVIDVI, damit man die Einzelseiten problemlos auf ein Blatt A4 
verteilen kann. Die interaktive \TeX-Programme mit den
Namen \File{adrconv.tex}, \File{birthday.tex} und \File{email.tex},
k"onnen die jeweils passende \File{aux}-Dateien selbst erzeugen.

Die Konvertierung einer Adressdatenbank in eine Adressdatei l"auft
daher in drei Schritten ab:

\begin{enumerate}
        \item Vorbereitung der Konvertierung durch Erzeugen der 
        \File{aux}-Datei f"ur die entsprechende \File{bib}-Datei.
        
        \item Konvertierung der \File{bib}-Datei mittels Bib\TeX.
        
        \item Umbenennung der entstandenen \File{bbl}-Datei in die 
        \File{adr}-Namensform f"ur Adressdateien
\end{enumerate}


Angenommen, Sie haben einen neuen Eintrag in Ihre 
Adressdatenbank mit Namen \File{adressen.bib} aufgenommen,
der so aussehen k"onnte:

\begin{small}        
\begin{verbatim}
  @address{DANTE,
  name      = {{DANTE~e.\,V.}},
  sortas    = {Dante},
  street    = {Postfach 10 18 40},
  zip       = {69008},
  city      = {Heidelberg},
  phone     = {0 62 21 / 2 97 66},
  fax       = {0 62 21 / 16 79 06},
  email     = {dante{@}dante.de},
  url       = {http://www.dante.de},
  key       = {DANTE},
  birthday  = {14. April 1989},
  nbirthday = {0414}
  }
\end{verbatim}
\end{small}

Wenn Sie eine Adressdatei f"ur Briefe und ein 
Adressverzeichnis
brauchen, w"ahlen Sie den Konverter \File{adrconv} und erzeugen
die \File{aux}-Datei. Die Protokolldatei \File{adrconv.log}
zeigt, wie das abgelaufen ist:

\begin{small}        
\begin{verbatim}
  sh>tex adrconv.tex             
  This is TeX, Version 3.14159 (Web2C 7.3.2x) (format=tex 
  2001.8.1)  13 AUG 2001 05:26
  **adrconv.tex
  (/texmf/tex/latex/koma-script/adrconv.tex
  Now you have to typein the name of the BibTeX 
  adressfile, you want to convert to 
  script-adress-file-format (without extension `.bib'):
  Geben Sie nun den Namen der BibTeX-Adressdatei ein, die 
  Sie in das Script-Adressdateiformat konvertieren wollen 
  (ohne `.bib'):

  adressfile=adressen
  \auxfile=\write0
  \openout0 = `adressen.aux'.


  After running BibTeX rename file `adressen.bbl' to 
  `adressen.adr'!
  Nach dem BibTeX-Lauf benennen Sie bitte die Datei 
  `adressen.bbl' in `adressen.adr' um!
  [1] )
  Output written on adrconv.dvi (1 page, 224 bytes).
\end{verbatim}
\end{small}

Als zweiten Schritt rufen Sie Bib\TeX{} zur 
Konvertierung auf. Wir 
zeigen das Protokoll \File{adressen.blg}: 

\begin{small}
\begin{verbatim}
  sh>bibtex adressen
  This is BibTeX, Version 0.99c (Web2C 7.3.2x)
  The top-level auxiliary file: adressen.aux
  The style file: adrconv.bst
  Database file #1: adressen.bib
\end{verbatim}
\end{small}

Zuletzt benennen Sie die Datei um:

\begin{small}
\begin{verbatim}
  sh>mv adressen.bbl adressen.adr
\end{verbatim}
\end{small}

Die konvertierte Adressdatei hat folgenden Inhalt:

\begin{small}
\begin{verbatim}
  \adrchar{K}
  \adrentry{Kalkweiss}{Achim}
  {Langer Weg 17 \\ 
   38118 Braunschweig}{0531 / 113 34 89}{}{}{}{}
  \adrentry{Kohlmeise}{Rudolf}
  {Stra{\ss}e des 11.~September 73 \\ 
   12345 Neu Jorg}{0513 / 89 55 66}{}{}{}{}
  \adrentry{Kuchennascher}{Mattse}
  {Fichtenstra{\ss}e 1 \\ 
   98765 Brummelsbach}{}{}{}{}{}

  \adrchar{M}
  \adrentry{Mustermann}{Hans}
  {Einbahnstra{\ss}e 1 \\ 
   01234 Heimstatt}{01234 / 5 67 89}{}{}{}{}

  \adrchar{D}
  \adrentry{{DANTE~e.\,V.}}{}
  {Postfach 10 18 40 \\ 
   69008 Heidelberg}{0 62 21 / 2 97 66}{}{}{}{DANTE}
\end{verbatim}
\end{small}

In Version 1.2~c musste man den \Macro{adrchar}-Eintrag noch von Hand korrigieren, durch den \texttt{sortas}-Eintrag erfolgt das nun automatisch.

Einen Brief an DANTE~e.\,V. k"onnen Sie  
mit Hilfe der \KOMAScript{} Briefklasse so beginnen:

\begin{small}
\begin{verbatim}
  \documentclass{scrlttr2}
  \usepackage{german}
  \begin{document}
  \begin{letter}{\DANTE}
  ...
\end{verbatim}
\end{small}

Um Ihre Adressdateien aktuell zu halten, m"ussen Sie diese drei 
Schritte jedesmal wiederholen, wenn Sie "Anderungen an Ihrer 
Adressdatenbank vorgenommen haben.

Bitte beachten Sie dabei, dass die drei Programme zum Erzeugen der
\File{aux}-Datei (\File{adrconv.tex}, \File{birthday.tex} und
\File{email.tex}) sowohl mit (Plain)\TeX{} als auch mit \LaTeX{} aufgerufen
werden k"onnen, w"ahrend die beiden Programme \File{dir.tex} und
\File{phone.tex}, die Sie nach erfolgreicher Konvertierung auf Ihre
Adressdatei anwenden k"onnen, um daraus fertige Adress-, E-Mail- bzw.
Telefonverzeichnisse zu produzieren, nur mit \LaTeX{}
funktionieren.

\end{document}