Debian Codegraph @

texmf-dist/source/latex/mailing/mailing.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright 1999-2026 Johannes L. Braams. All rights reserved.
4 %
5 % This file is part of the mailing package.
6 % -----------------------------------------
7 %
8 % It may be distributed and/or modified under the
9 % conditions of the LaTeX Project Public License, either version 1.3c
10 % of this license or (at your option) any later version.
11 % The latest version of this license is in
12 % http://www.latex-project.org/lppl.txt
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2008 or later.
15 %
16 % This work has the LPPL maintenance status "maintained".
17 %
18 % The Current Maintainer of this work is Johannes Braams.
19 %
20 % The list of all files belonging to the supertabular package is
21 % given in the file `MANIFEST.
22 %
23 % The list of derived (unpacked) files belonging to the distribution
24 % and covered by LPPL is defined by the unpacking scripts (with
25 % extension .ins) which are part of the distribution.
26 % \fi
27 %
28 % \CheckSum{157}
29 %
30 %\iffalse
31 %% Copyright (C) 1999-2026 Johannes L. Braams texniek at texniek.nl
32 %%
33 %%
34 %<*dtx>
35 \ProvidesFile{mailing.dtx}
36 %</dtx>
37 \NeedsTeXFormat{LaTeX2e}
38 %<package>\ProvidesPackage{mailing}
39 %<driver>\ProvidesFile{mailing.drv}
40 %\fi
41 %\ProvidesFile{mailing}
42 [2026/01/02 v1.0d Send letters to multiple addresses]
43 %\iffalse
44 %<*driver>
45 \documentclass{ltxdoc}
46 \begin{document}
47 \pagestyle{myheadings}
48 \DocInput{mailing.dtx}
49 \end{document}
50 %</driver>
51 %\fi
52 % \changes{v1.0c}{2024/07/20}{Updated contact info}
53 % \changes{v1.0d}{2026/01/02}{Updated copyright info}
54 %
55 % \GetFileInfo{mailing}
56 % \title{Creating a mailing\thanks{This file
57 % has version number \fileversion, last
58 % revised \filedate.}}
59 % \author{Johannes Braams}
60 % \date{\filedate}^^AA original date{september 7, 1994}
61 % \maketitle
62 %
63 % \markboth
64 % {mailing package version \fileversion\space as of \filedate}
65 % {mailing package version \fileversion\space as of \filedate}
66 %
67 % \section{Introduction}
68 %
69 % This package is intended to be used when you want to send a large
70 % number of letters, all with (almost) the same text.
71 %
72 % This package is based on the former style option \texttt{merge}
73 % by Graeme McKinstry, but is is a reimplementation with a
74 % different user interface.
75 %
76 % \section{The user interface}
77 %
78 % \DescribeMacro{\addressfile}
79 % The commands |\addressfile| takes a filename as its argument.
80 % When the file can't be found by \LaTeX, the user will be asked to
81 % supply a different name.
82 %
83 % The address file should have the following format:
84 % \begin{verbatim}
85 %Name of addressee
86 %Street\\town
87 %Opening text of the letter
88 %(optional definitions)
89 %<blank line>
90 %Name of addressee
91 %Street\\town
92 %Opening text of the letter
93 %(optional definitions)
94 %<blank line>
95 %...
96 % \end{verbatim}
97 % The various addresses are separated by a blank line in the file
98 % (multiple blank lines in between addresses are allowed).
99 % It is also possible to have multiple lines with definitions; they
100 % will all be executed.
101 %
102 % \DescribeMacro{\mailingtext}
103 % The text of the mailing is entered as the argument of
104 % |\mailingtext|. A difference with the original \texttt{merge.sty}
105 % is that this package allows control sequences in the argument of
106 % |\mailingtext|. These control sequences should then be defined in
107 % the file with the address information.
108 %
109 % \DescribeMacro{\makemailing}
110 % When |\makemailing| is called the letters are produced, combining
111 % the information found in the address file with the text of the
112 % mailing.
113 %
114 % \StopEventually{}
115 %
116 % \section{The implementation}
117 %
118 % \subsection{User interface}
119 %
120 % \begin{macro}{\addressfile}
121 % The argument to |\adressfile| is the name of the file with the
122 % address information.
123 % \begin{macrocode}
124 \newcommand{\addressfile}[1]{%
125 \def\M@filename{#1}}
126 % \end{macrocode}
127 % \end{macro}
128 %
129 % \begin{macro}{\mailingtext}
130 % The argument to this macro contains the entire text of the
131 % mailing. The text may contain control sequences to be able to
132 % make variations in the text.
133 % \begin{macrocode}
134 \long\def\mailingtext#1{\global\mailing@text={#1}}
135 % \end{macrocode}
136 % \end{macro}
137 %
138 % \begin{macro}{\makemailing}
139 % The command |\makemailing| will produce the mailing, reading
140 % addresses, openings and optional definitions of variable text
141 % parts from an external file.
142 % \begin{macrocode}
143 \def\makemailing{%
144 \M@openadrfile
145 \loop
146 \read@info
147 \if@notready
148 \begin{letter}{\M@toname\\\M@toaddress}%
149 \opening{\M@opening}%
150 \vskip\baselineskip
151 \the\mailing@text
152 \end{letter}
153 \fi
154 \if@notready
155 \repeat}
156 % \end{macrocode}
157 % \end{macro}
158 %
159 % \subsection{Allocations}
160 %
161 % \begin{macro}{\M@adrfile}
162 % We need to allocate an input stream for the file with the address
163 % information.
164 % \begin{macrocode}
165 \newread\M@adrfile
166 % \end{macrocode}
167 % \end{macro}
168 %
169 % \begin{macro}{\mailing@text}
170 % The contents of the letter are stored in a token register
171 % \begin{macrocode}
172 \newtoks\mailing@text
173 % \end{macrocode}
174 % \end{macro}
175 %
176 % \begin{macro}{\if@notready}
177 % A switch which indicates if the file |\M@adrfile| has been
178 % exhausted.
179 % \begin{macrocode}
180 \newif\if@notready
181 \newif\if@notemptyoreof
182 % \end{macrocode}
183 % \end{macro}
184 %
185 % \subsection{Internal macros}
186 %
187 % \begin{macro}{\M@openadrfile}
188 % The macro |\M@openadrfile| tries to open |\M@filename|. It that
189 % doesn't succeed it asks the user to supply a new name. This is
190 % done untill a file is found.
191 % \begin{macrocode}
192 \def\M@openadrfile{%
193 \openin\M@adrfile\M@filename\relax
194 \ifeof\M@adrfile
195 \loop
196 %\PackageWarning{mailing}{I can't find the file \M@filename}
197 \typeout{I can't find the file \M@filename!}
198 \closein\M@adrfile
199 \typein[\M@filename]{Enter a new name}
200 \openin\M@adrfile\M@filename
201 \ifeof\M@adrfile
202 \repeat
203 \fi}
204 % \end{macrocode}
205 % \end{macro}
206 %
207 % \begin{macro}{\read@info}
208 % The macro |\read@info| takes care of the reading of all the
209 % information from |\M@adrfile|, needed to format another letter.
210 % \begin{macrocode}
211 \def\read@info{%
212 \skip@empty@lines
213 % \end{macrocode}
214 % The macro |\skip@empty@lines| leaves the non-empty line it found
215 % in |\M@lines|. If it found an end of file condition the
216 % |\if@notready| flag will be set to |\iffalse|.
217 % \begin{macrocode}
218 \if@notready
219 \let\M@toname\M@line
220 \read\M@adrfile to\M@toaddress
221 \read\M@adrfile to\M@opening
222 \test@eof
223 \if@notready\read@defs\fi
224 \fi
225 }
226 % \end{macrocode}
227 % \end{macro}
228 %
229 % \begin{macro}{\read@defs}
230 % Reads definitions of control sequences from the file |\M@adrfile|
231 % until either an empty line is found or the end of file is
232 % reached. Each line is stored in a control sequence and it is
233 % executed after all definitions are read.
234 % \begin{macrocode}
235 \def\read@defs{%
236 \def\M@defns{}%
237 {\loop
238 \endlinechar=-1
239 \read\M@adrfile to\M@line
240 \endlinechar=`\^^M
241 % \end{macrocode}
242 % We need to get the expansion of |\M@line| into the definition of
243 % |\M@defns|, not |\M@line| itself. Therefore |\M@line| is expanded
244 % before |\M@defns|.
245 % \begin{macrocode}
246 \expandafter\toks@\expandafter\expandafter
247 \expandafter{\expandafter\M@defns\M@line}%
248 \xdef\M@defns{\the\toks@}%
249 \test@emptyoreof
250 \if@notemptyoreof
251 \repeat}%
252 \M@defns
253 }
254 % \end{macrocode}
255 % \end{macro}
256 %
257 % \begin{macro}{\test@eof}
258 % The macro |\test@eof| tests the status of of the input file.
259 % \begin{macrocode}
260 \def\test@eof{%
261 \ifeof\M@adrfile
262 \@notreadyfalse
263 \else
264 \@notreadytrue
265 \fi}
266 % \end{macrocode}
267 % \end{macro}
268 %
269 % \begin{macro}{\test@emptyoreof}
270 % The macro |\test@emptyoreof| checks whether we reached an empty
271 % line \emph{or} the end of the file.
272 % \begin{macrocode}
273 \def\test@emptyoreof{%
274 \@notemptyoreoftrue
275 \ifx\M@line\@empty
276 \global\@notemptyoreoffalse
277 \fi
278 \ifeof\M@adrfile
279 \global\@notemptyoreoffalse
280 \global\@notreadyfalse
281 \fi}
282 % \end{macrocode}
283 % \end{macro}
284 %
285 % \begin{macro}{\skip@empty@lines}
286 % This macro skips empty lines until it finds either a non-empty
287 % line or the end of the file. If necessary it sets the
288 % |\if@notready| flag. The last line read is left in |\M@line|.
289 % \begin{macrocode}
290 \def\skip@empty@lines{%
291 {\loop
292 \endlinechar=-1
293 \ifeof\M@adrfile
294 \global\@notreadyfalse
295 \@tempswafalse
296 \else
297 \global\@notreadytrue
298 \global\read\M@adrfile to\M@line
299 \ifx\M@line\@empty
300 \@tempswatrue
301 \else
302 \@tempswafalse
303 \fi
304 \fi
305 \if@tempswa
306 \repeat}%
307 }
308 % \end{macrocode}
309 % \end{macro}
310 %
311 % \Finale
312 \endinput