Debian Codegraph @

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

raw
1 %% \CheckSum{108}
2 % \iffalse meta-comment
3 %
4 % File: mailmerge.dtx
5 %
6 % Copyright (C) 2009 Miguel V. S. Frasson ([email protected])
7 %
8 % The LaTeX package mailmerge provides an interface to produce text from
9 % a template where fields are replaced by actual data, like in a
10 % database. It is useful to produce several letters from a template,
11 % certificates or other such documents. It allows to access the entry
12 % number, number of entries and so on.
13 %
14 %<*driver>
15 \documentclass{ltxdoc}
16 \usepackage{doc}
17 \usepackage{amstext,makeidx,ae,mailmerge}
18 \makeindex
19 \newcommand{\ttabrechaves}{\char123}
20 \newcommand{\ttfechachaves}{\char125}
21 \let\ac\ttabrechaves
22 \let\fc\ttfechachaves
23 \begin{document}
24 \DocInput{mailmerge.dtx}
25 \end{document}
26 %</driver>
27 % \fi
28 %
29 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 %
31 % \StopEventually
32 %
33 % \changes{1.0}{2009/09/23}{initial version}
34 %
35 % \MakeShortVerb+
36 %
37 % \title{\textsf{mailmerge}: repeat amount of text merging fields}
38 % \author{Miguel Vin\'\i cius Santini Frasson}
39 % \date{2009--09--23 version 1.0}
40 %
41 % \maketitle
42 %
43 %
44 % \tableofcontents
45 %
46 % \section{Introduction}
47 %
48 % The \LaTeX\ package \textsf{mailmerge} provides an interface to
49 % produce text from a template where fields are replaced by actual
50 % data, like in a database. It is useful to produce several letters
51 % from a template, certificates or other such documents. It allows to
52 % access the entry number, number of entries and so on.
53 %
54 % \section{Usage}
55 %
56 % In short, one needs to:
57 % \begin{enumerate}
58 % \item declare field names,
59 % \item define the repetition and
60 % \item provide entries, each one being a set of values for the fields.
61 % \end{enumerate}
62 % It is important to define the repetition with
63 % \texttt{\string\mailrepeat} \emph{before} provide any entry. We
64 % present the usage in more detail now.
65 %
66 % \begin{enumerate}
67 % \item \DescribeMacro{\mailfields} Declare the names of the fields,
68 % with the command \\\mbox{\qquad}
69 % \texttt{\string\mailfields\ac\textit{name1},\textit{name2},...\fc}\\
70 % The order declared here is the order in which the values must be
71 % provided in the parameter of +\mailentry+ (see below.)
72 %
73 % \item
74 % \DescribeMacro{\mailrepeat}
75 % \DescribeMacro{\field}
76 % The block of text to be repeated is given as the parameter of
77 % macro +\mailrepeat+ as in\\\mbox{\qquad}
78 % \texttt{\string\mailrepeat\ac\textit{...\ text to be
79 % repeated...\fc}}\\
80 % Inside the text to be repeated, which can be several paragraphs
81 % long, each instance of \texttt{\string\field\ac\textit{name}\fc}
82 % is replaced by the respective value, this for each entry.
83 %
84 % \DescribeMacro{\numberoffields} \DescribeMacro{\numberofentries}
85 % \DescribeMacro{\entrynumber} The command +\numberoffields+ is
86 % replaced by the number of fields and +\numberofentries+ is
87 % replaced by the number of entries, but it is necessary two runs to
88 % update the value. The command +\entrynumber+ is replaced by the
89 % current entry number. This can be used, for example, in
90 % determining if current entry has an odd or even number.
91 %
92 % For conditional text, depending on field value, one can compare
93 % value's contents, for example, with the +\ifthenelse+ command
94 % provided by
95 % the \textsf{ifthen} package.
96 %
97 % \item \DescribeMacro{\mailentry} For each entry, provide a
98 % command\\\mbox{\qquad}
99 % \texttt{\string\mailentry\ac\textit{value1},\textit{value2},...\fc}\\
100 % where \texttt{\textit{value1}} is the value of field named
101 % \texttt{\textit{name1}}, \texttt{\textit{value2}} is the value of
102 % field named \texttt{\textit{name2}}, and so on. The values can be
103 % several paragraphs long. If the value has a comma with it, better
104 % enclose the value between curly brackets, like in
105 % \begin{verbatim}
106 % \mailfields{name,friends,drives}
107 % \mailentry{John,{Bart,Robert},yes}
108 % \mailentry{Michael,{Jean,Phillip,Maria},no}
109 % \end{verbatim}
110 %
111 %
112 % \item \DescribeMacro{\mailnewdata} In case of intention of use of
113 % several databases in the same file, use the command +\mailnewdata+,
114 % which resets entries. New uses of +\mailfields+ overhide previous
115 % field names.
116 % \end{enumerate}
117 %
118 % \section{Example}
119 %
120 % \begin{verbatim}
121 % \usepackage{ifthen,mailmerge}
122 %
123 % % \ifequal{A}{B}{what if A=B}{what if A<>B}
124 % \newcommand{\ifequal}[2]{\ifthenelse{\equal{#1}{#2}}}
125 %
126 % \mailfields{name,friends,drives}
127 %
128 % \mailrepeat{\section*{\field{name}'s profile}
129 %
130 % \field{name} has
131 % \ifequal{\field{friends}}{}
132 % {no friends}
133 % {\field{friends} as friends}.
134 % \ifequal{\field{drives}}{yes}{Drives.}{Doesn't drive.}
135 %
136 % (entry \entrynumber\ of \numberofentries)
137 %
138 % % \newpage optional
139 % }
140 %
141 % \mailentry{John,{Bart and Robert},yes}
142 % \mailentry{Sara,{Jean, Phillip and Maria},no}
143 % \mailentry{Edward,,yes}
144 % \end{verbatim}
145 %
146 % \noindent what produces the following output:
147 %
148 % \newcommand{\ifequal}[2]{\ifthenelse{\equal{#1}{#2}}}
149 %
150 % \mailfields{name,friends,drives}
151 %
152 % \mailrepeat{\section*{\field{name}'s profile}
153 %
154 % \field{name} has
155 % \ifequal{\field{friends}}{}
156 % {no friends}
157 % {\field{friends} as friends}.
158 % \ifequal{\field{drives}}{yes}{Drives.}{Doesn't drive.}
159 %
160 % (entry \entrynumber\ of \numberofentries)
161 %
162 % ^^A \newpage optional
163 % }
164 %
165 % \mailentry{John,{Bart and Robert},yes}
166 % \mailentry{Sara,{Jean, Phillip and Maria},no}
167 % \mailentry{Edward,,yes}
168 %
169 % \section{Idea of implementation}
170 %
171 % \begin{itemize}
172 % \item Each new data initialization (call od +\mailnewdata+) defines
173 % a tag command with values `a', `aa', `aaa', and so on, saved in
174 % command +\MAILMcurrtag+.
175 % \item A +\mailfields+ saves field names to commands +\MAILMfieldI+,
176 % +\MAILMfieldII+, +\MAILMfieldIII+, etc (ending with upcase roman
177 % numbers), and at the end, saves in the \texttt{.aux} file the
178 % number of fields in a command determined by the data tag.
179 % \item The +\mailrepeat+ command just saves its parameter to a command.
180 % \item Each \texttt{\string\field\ac\textit{name}\fc} is expanded to
181 % a command \texttt{\string\MAILMthefield\textit{name}}.
182 % \item +\numberoffields+ expands to a command whose name is composed
183 % by \texttt{MAILMnumberfields} plus ``tag''. The same for +\numberofentries+.
184 % \item Each +\mailentry+ defines the comands
185 % \texttt{\string\MAILMthefield\textit{nameN}} to expand to
186 % \texttt{\textit{valueN}}, using
187 % \texttt{\string\MAILMfield\textit{N-in-roman}} to compose the name
188 % of the command and expand an entry of the repetition command.
189 % Now, when the +\field+, +\numberoffields+ and +\numberofentries+
190 % are expanded, they have ppropriated values.
191 % \end{itemize}
192 %
193 %
194 % \section{Code}
195 %
196 %
197 % Identidication of the package and use of the package \textsf{ifthen}.
198 % \begin{macrocode}
199 \NeedsTeXFormat{LaTeX2e}
200 \ProvidesPackage{mailmerge}[2009/09/23 v1.0 repeat amount of text merging fields]
201 \RequirePackage{ifthen}
202 % \end{macrocode}
203 %
204 % \subsection{(Re)initialization}
205 %
206 % Reset counters and update tag command +\MAILMcurrtag+. Inicialize once.
207 % \begin{macrocode}
208 \def\MAILMcurrtag{}
209 \newtoks\MAILMtok
210 \newcounter{MAILMcount}% aux counter
211 \newcounter{MAILMentry}%
212 \newcommand{\mailnewdata}{%
213 \setcounter{MAILMentry}{0}%
214 \xdef\MAILMcurrtag{a\MAILMcurrtag}}
215 \mailnewdata
216 % \end{macrocode}
217 %
218 % \subsection{Saving the repetition in a command}
219 %
220 % \DescribeMacro{\mailrepeat}
221 % \begin{macrocode}
222 \newcommand{\mailrepeat}[1]{\gdef\MAILMrepetition{#1}}
223 % \end{macrocode}
224 %
225 % \subsection{Restoring data from aux file}
226 %
227 % \DescribeMacro{\MAILMsetnumfields}
228 % \DescribeMacro{\MAILMsetnumentries}
229 % \DescribeMacro{\numberoffields}
230 % \DescribeMacro{\numberofentries}
231 % Commands that extract info from aux file (saved by +\mailfields+ and
232 % +\mailentry+) and commands that use this information when repeting.
233 % \begin{macrocode}
234 \newcommand{\MAILMsetnumfields}[2]
235 {\expandafter\xdef\csname MAILMnumberoffields#1\endcsname{#2}}
236 \newcommand{\MAILMsetnumentries}[2]
237 {\expandafter\xdef\csname MAILMnumberofentries#1\endcsname{#2}}
238 \newcommand{\numberoffields}
239 {\csname MAILMnumberoffields\MAILMcurrtag\endcsname}
240 \newcommand{\numberofentries}
241 {\csname MAILMnumberofentries\MAILMcurrtag\endcsname}
242 % \end{macrocode}
243 %
244 % \subsection{Saving field names}
245 %
246 % \begin{macrocode}
247 \newcommand{\mailfields}[1]{%
248 \setcounter{MAILMcount}{0}%
249 % \end{macrocode}
250 % \noindent Initiate a loop, where for each entry, the command
251 % +\MAILMaux+ is set to entry name.
252 % \begin{macrocode}
253 \@for\MAILMaux:=#1\do{%
254 % \end{macrocode}
255 % \noindent The next line is to extract white space after comma.
256 % \begin{macrocode}
257 \edef\MAILMaux{\expandafter\@firstofone\MAILMaux\@empty}%
258 % \end{macrocode}
259 % \noindent Define command
260 % \texttt{\string\MAILMfield\textit{Roman-number}}.
261 % \begin{macrocode}
262 \stepcounter{MAILMcount}%
263 \expandafter\edef\csname MAILMfield\Roman{MAILMcount}\endcsname
264 {\MAILMaux}%
265 \edef\numberoffields{\arabic{MAILMcount}}%
266 }%
267 % \end{macrocode}
268 % \noindent Write to \texttt{aux} +\MAILMsetnumfields{tag}{num}+
269 % \begin{macrocode}
270 \immediate\write\@mainaux{\string\MAILMsetnumfields
271 {\MAILMcurrtag}{\theMAILMcount}}%
272 }
273 % \end{macrocode}
274 %
275 % \subsection{Repeating within an entry}
276 %
277 % \DescribeMacro{\field}
278 % Defining +\field+, that expands to
279 % \texttt{\string\MAILMthefield\textit{name}}.
280 % \begin{macrocode}
281 \newcommand{\field}[1]{\csname MAILMthefield#1\endcsname}
282 % \end{macrocode}
283 %
284 % \DescribeMacro{\mailentry}
285 % \noindent Each entry increments counter (reset in initialization),
286 % saves entry number to aux, saves each value to the command expanded
287 % by +\field+ and expand the repetition, stored in +\MAILMrepetition+.
288 % The implementation is similar to +\mailfields+.
289 % \begin{macrocode}
290 \newcommand{\mailentry}[1]{%
291 \stepcounter{MAILMentry}%
292 \edef\entrynumber{\theMAILMentry}%
293 \immediate\write\@mainaux{\string\MAILMsetnumentries
294 {\MAILMcurrtag}{\theMAILMentry}}%
295 \setcounter{MAILMcount}{0}%
296 \@for\MAILMentryfield:=#1\do{%
297 \MAILMtok=\expandafter{\MAILMentryfield}%
298 \stepcounter{MAILMcount}%
299 \expandafter\long\expandafter\edef
300 \csname MAILMthefield%
301 \csname MAILMfield\Roman{MAILMcount}\endcsname
302 \endcsname {\the\MAILMtok}%
303 }%
304 \MAILMrepetition
305 }
306 % \end{macrocode}
307 %
308 % \Finale \PrintIndex %\PrintChanges
309 %
310 %% \CharacterTable
311 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
312 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
313 %% Digits \0\1\2\3\4\5\6\7\8\9
314 %% Exclamation \! Double quote \" Hash (number) \#
315 %% Dollar \$ Percent \% Ampersand \&
316 %% Acute accent \' Left paren \( Right paren \)
317 %% Asterisk \* Plus \+ Comma \,
318 %% Minus \- Point \. Solidus \/
319 %% Colon \: Semicolon \; Less than \<
320 %% Equals \= Greater than \> Question mark \?
321 %% Commercial at \@ Left bracket \[ Backslash \\
322 %% Right bracket \] Circumflex \^ Underscore \_
323 %% Grave accent \` Left brace \{ Vertical bar \|
324 %% Right brace \} Tilde \~}
325 %
326 \endinput
327
328
329