summaryrefslogtreecommitdiff
path: root/macros/generic/formlett/user_manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/formlett/user_manual.tex')
-rw-r--r--macros/generic/formlett/user_manual.tex1113
1 files changed, 1113 insertions, 0 deletions
diff --git a/macros/generic/formlett/user_manual.tex b/macros/generic/formlett/user_manual.tex
new file mode 100644
index 0000000000..b317848477
--- /dev/null
+++ b/macros/generic/formlett/user_manual.tex
@@ -0,0 +1,1113 @@
+% USER MANUAL in Plain TeX
+
+\input formlett.sty
+
+% FONTS
+\font\hbold=cmbx10 at 17.28pt
+\font\lbold=cmbx10 at 14.4pt
+\font\bbold=cmbx10 at 12pt
+\font\small=cmr8
+\font\tiny=cmr5
+\font\stt=cmtt9
+\catcode`\@=11\relax
+%
+%
+%
+% OTHER MACROS
+%
+\catcode`\~=11\relax \def\t{{\tt ~}}
+\catcode`\~=\active\relax
+\catcode`\!=0\relax !catcode`!\=11!relax
+!def!esc{\}!def!escs{\! }
+!catcode`!\=0!relax \catcode`\!=12\relax
+\def\rqs{\rq\ }
+\def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{\font\sc=cmcsc10\sc a}\kern-.15em
+ T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
+
+% makeshift macro
+\catcode`\^^M=13\relax%
+\def\setraw{\bgroup\rm@ligature\set@space\set@tab%
+\set@cr\stt\raw@chars[11][13][13][13][13]\def^^M{\strut\par}\setraw@@}%
+\edef\temp@macro{%
+ \noexpand\long\noexpand\def\noexpand\setraw@@\noexpand##1^^M##2%
+ \esc@ unsetraw{##1##2\noexpand\egroup}}\temp@macro %
+\catcode`\^^M=5\relax%
+
+
+\font\ninerm=cmr9 \font\eightrm=cmr8
+\font\ninei=cmmi9 \font\eighti=cmmi8
+\font\ninesy=cmsy9 \font\eightsy=cmsy8
+\font\ninebf=cmbx9 \font\eightbf=cmbx8
+\font\ninett=cmtt9 \font\eighttt=cmtt8
+\font\nineit=cmti9 \font\eightit=cmti8
+\font\ninesl=cmsl9 \font\eightsl=cmsl8
+
+\font\sixrm=cmr6
+\font\sixi=cmmi6
+\font\sixsy=cmsy6
+\font\sixbf=cmbx6
+
+\skewchar\ninei='177 \skewchar\eighti='177 \skewchar\sixi='177
+\skewchar\ninesy='60 \skewchar\eightsy='60 \skewchar\sixsy='60
+\hyphenchar\ninett=-1 \hyphenchar\eighttt=-1 \hyphenchar\tentt=-1
+
+\font\tentex=cmtex10
+\font\inchhigh=cminch
+\font\titlefont=cmssdc10 at 40pt % titles in chapter openings
+\font\eightss=cmssq8 % quotations in chapter closings
+\font\eightssi=cmssqi8 % ditto, slanted
+\font\tenu=cmu10 % unslanted te~t italic
+\font\manual=manfnt % METAFONT logo and special symbols
+\font\magnifiedfiverm=cmr5 at 10pt % to demonstrate magnification
+
+\newskip\ttglue
+\def\eightpoint{\def\rm{\fam0\eightrm}% switch to 8-point type
+ \textfont0=\eightrm \scriptfont0=\sixrm \scriptscriptfont0=\fiverm
+ \textfont1=\eighti \scriptfont1=\sixi \scriptscriptfont1=\fivei
+ \textfont2=\eightsy \scriptfont2=\sixsy \scriptscriptfont2=\fivesy
+ \textfont3=\tenex \scriptfont3=\tenex \scriptscriptfont3=\tenex
+ \textfont\itfam=\eightit \def\it{\fam\itfam\eightit}%
+ \textfont\slfam=\eightsl \def\sl{\fam\slfam\eightsl}%
+ \textfont\ttfam=\eighttt \def\tt{\fam\ttfam\eighttt}%
+ \textfont\bffam=\eightbf \scriptfont\bffam=\sixbf
+ \scriptscriptfont\bffam=\fivebf \def\bf{\fam\bffam\eightbf}%,
+ \tt \ttglue=.5em plus.25em minus.15em
+ \normalbaselineskip=9pt
+ \setbox\strutbox=\hbox{\vrule height7pt depth2pt width0pt}%
+ \let\sc=\sixrm \let\big=\eightbig \normalbaselines\rm}
+
+
+%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%
+%
+% END OF EXTRA MACROS AND FONTS
+%
+%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%
+
+
+
+
+\catcode`\@=11\relax
+\PAGENO=1
+\voffset=-0.3in
+
+
+\ifx\pageno\undefined
+\errmessage{Please run TeX if you want this article on how to use
+<formlett.sty> to be processed as well!}
+\fi
+
+
+\parindent=0pt
+\hsize=469.75499pt % the default
+\vsize=9.6in %8.83in
+
+\def\makefootline{\baselineskip=24pt \line{\the\footline}}
+\footline={\lower5pt
+\hbox to \hsize
+ {{\tenrm Jiang Z ~~~{\tensl Mail merge with the use of formlett.sty}
+\hss \folio}}}
+
+\leftline{\hbold Mail merge with the use of formlett.sty}
+\bigskip
+
+
+{\advance\leftskip by13mm \overfullrule=0pt
+\advance\rightskip by 20mm %28mm
+\sl
+\noindent Zhuhan JIANG\par
+\noindent School of Computing and Information Technology,
+ University of Western Sydney, Victoria Road, Parramatta NSW 2150, Australia.
+{\sl ~~Email}:~z.jiang@uws.edu.au\par
+\medskip
+\rm\smooth
+\noindent (Last updated on 26 May 2003)\par
+\medskip
+
+\noindent
+In this article, the author explains how to use a form-letter or mail
+merge style {\tt formlett.sty}, designed for plain \TeX\space and
+\LaTeX\space or \LaTeX2e. {\tt formlett.sty} supports different
+parameter input methods, parameter naming and defaulting mechanism, as
+well as facilities for previewing parameter positions and printing
+labels. It is written for the purpose of being powerful, robust and
+above all easy to use.\par }
+
+
+\begincolumns
+
+{\lbold Introduction}
+
+\smallskip
+
+Our purpose here is to describe a comprehensive implementation of a
+macro system, handling form letters or mail merge under plain \TeX\space
+or \LaTeX\space2.09 or \LaTeX2e. The main objective is to provide an
+easy way to output many form letters with their own parameters, with or
+without the use of multiple files. There will be a coherent and simple
+format for putting parameters inside a form letter, with a number of
+helping facilities for such as naming parameters and previewing their
+positions. A minimum support for printing mailing labels is also
+provided.
+
+
+\medskip
+
+The concept of macros [1] for form letters is not new: there already
+exist macros in this connection such as {\tt merge}, {\tt textmerg} and
+{\tt address} to name a few, see [2,3] for further details. Our stress
+here is therefore laid on the ease to use, along with the power and the
+robustness of the macros.
+
+\bigskip
+
+
+{\lbold Basic format}
+
+
+%%%%%%%%%%%%
+% letter top
+%%%%%%%%%%%%
+
+ \beginletter
+\sl
+\hsize=3.1in\relax
+\medskip
+ \paranames % optional
+ \tt<<FULL NAME>>;%
+ \tt<<ADDRESS-01>>;%
+ \tt<<ADDRESS-02>>;%
+ \tt<<GIVEN NAME>>;%
+ \tt<<MISSING ITEM>>;%
+ \tt<<PHONE NUMBER>>!
+ \loaddefaultparas % optional
+
+ \NOPAGENUMBERS\parindent=0pt\overfullrule=0pt
+ \paras[1]\par\paras[2]\par\paras[3]\par\medskip
+
+ Dear \paras[4],
+
+ \smallskip
+ We have been looking for
+ \paras[5] for quite a while
+ without any luck, could you help
+ us out? If so, please ring
+ \paras[6]. \par\medskip
+ Cheers!\hfill Michael\par %\vfill\eject
+\medskip
+ \endletter
+
+%%%%%%%%%%%%
+% letter end
+%%%%%%%%%%%%
+
+
+Suppose we would like to write a form letter for mail merge in the
+following form
+
+\showparas
+
+where the text inside the double arrow brackets are to be replaced by
+the parameters specific to each individual letter. If we number these
+parameters one by one in a single group, then the letter template will
+be organised as
+
+\preview
+
+and we need just 6 parameters to personalise an individual letter. A
+simplest example of supplying a set or a {\sl cluster} of these
+parameters to output a merged form letter is to use
+
+\setraw
+\moreletter
+ Mrs L Stenson;\#1-20 Sunset Street;%
+ Hills, Norway;Louise;a Bible;220-8888!
+\unsetraw
+
+For more letters to be merged this way, just use again the
+command {\tt\string\moreletter} in the above format, in which each
+parameter is separated by a semicolon `{\tt ;}' and the whole parameter
+cluster is ended by an exclamation mark `{\tt !}'. The actual code in
+\LaTeX\space for making the above form letter, along with an extra
+merged letter, may read as follows
+
+
+\edef\setrawcount{\stt\noexpand
+ \beginrawlist[][][4][][][3.3in]{\esc@ unsetraw}}
+
+\linecount=1\relax
+\setrawcount
+ \documentstyle[formlett]{article}
+ \begin{document}
+ \beginletter
+ \NOPAGENUMBERS\parindent=0pt
+ \paras[1]\par\paras[2]\par
+ \paras[3]\par\medskip
+ Dear \paras[4], \par\medskip
+ We have been looking for
+ \paras[5] for quite a while
+ without any luck, could you help
+ us out? If so, please ring
+ \paras[6]. \par\medskip
+ Cheers!\hfill Michael\vfill\eject
+ \endletter
+
+ \moreletter % letter one
+ Mrs L Stenson;\#1-20 Sunset Street;%
+ Hills, Norway;Louise;a Bible;220-8888!
+ \moreletter % letter two
+ S Wales;UMIST;Manchester;Sir or Madam;%
+ a \TeX\ package{+}manual;225-9905!
+ \end{document}
+\unsetraw
+\rm
+
+The line numbers in the above and later on are for quick reference only:
+they are not a part of the program code. The letter template in lines
+4-13 is defined by the {\tt\string\beginletter} and {\tt\string\endletter}
+pair in line 3 and line 14, with each use of {\tt\string\moreletter}
+generating a new merged letter. We note that command {\tt \string\paras[{\it
+m}]} represents the $m^{th}$ merged parameter (of the first group, see
+later), and the command {\tt\string\NOPAGENUMBERS}
+will remove the page numbering for both \LaTeX\space and plain
+\TeX. We also note that if one replaces lines 1-2 by
+{\tt\string\input\space formlett.sty}, then the program will be
+compilable under plain \TeX\space as well.
+
+
+\medskip
+
+Although the mail merge mechanism in the above will be sufficient for
+most simple applications, {\tt formlett} provides in fact many more
+features. We shall thus in the followings introduce the main features
+one by one, from the most useful to the less likely encountered.
+
+\medskip
+
+To start with, we notice that in the above example there are exactly two
+parameters to be used for the address. This is inconvenient to say the
+least, even if we allocate say three more extra parameters for the
+purpose. This naturally calls for the separation of the whole {\sl
+cluster} of parameters into several {\sl groups}, so that the numbering
+of the parameters in every group will be resynchronised. We thus use
+{\tt\string\paras[{\it m}][{\it n}]} to denote the $m^{th}$ parameter of
+the $n^{th}$ group of a whole cluster of merging parameters. In fact we
+may use {\tt\string\blockparas[{\it m}][{\it n}][{\it pre}][{\it post}]}
+to represent parameters in the $n^{th}$ group, from the $m^{th}$ to the
+last parameter of that group, where the tokens denoted by {\it pre} and
+{\it post} are those to be added in front and behind respectively each
+of the legitimate parameters. The defaults for {\it pre} and {\it post}
+are {\tt\string\noindent} and {\tt\string\par} respectively. It is
+therefore more sensible to specify the merging parameters of the earlier
+example via
+
+
+%%%%%%%%%%%%
+% letter top
+%%%%%%%%%%%%
+
+ \beginletter
+\sl
+\hsize=3.1in\relax
+\medskip
+ \paranames % optional
+ \tt<<FULL NAME>>\hfill
+ \tiny\fillzeros[4]\linecount\global\advance\linecount1\relax\par;%
+ \tt<<ADDRESS-etc>>\hfill
+ \tiny\fillzeros[4]\linecount\global\advance\linecount1\relax\par;%
+ +\tt<<GIVEN NAME>>;%
+ \tt<<MISSING ITEM>>;%
+ \tt<<PHONE NUMBER>>!
+ \loaddefaultparas % optional
+
+ \NOPAGENUMBERS\parindent=0pt\overfullrule=0pt
+ \noindent{\it\paras[1]}\par
+ \blockparas[2]\par\medskip
+
+ Dear \paras[1][2],
+
+ \smallskip
+ We have been looking for
+ \paras[2][2] for quite a while
+ without any luck, could you help
+ us out? If so, please ring
+ \paras[3][2]. \par\medskip
+ Cheers!\hfill Michael\par %\vfill\eject
+\medskip
+ \endletter
+
+%%%%%%%%%%%%
+% letter end
+%%%%%%%%%%%%
+
+\showparas
+
+where {\tt <<ADDRESS-etc>>} will be produced by
+{\tt\string\blockparas[2][1]}, i.e. all the parameters of the first
+group, starting from the 2nd parameter. We note that the missing
+square-bracketed macro parameters for {\tt\string\blockparas} are
+automatically provided: in fact macro parameters in {\tt formlett} are
+systematically defaulted. Hence for example, {\tt \string\paras[1][1]}
+is equivalent to any of the following commands
+
+\setraw
+ \paras, \paras[1], \paras[][1],
+ \paras[1][], \paras[][]
+\unsetraw
+
+As for the more precise position of the merging parameters, they can
+always be viewed via the command {\tt\string\preview}, which in this
+case gives the following positioning
+
+\preview
+
+This way, the mail merge for the above letter template can also be done
+(in plain \TeX) in the following more flexible way
+
+\setrawcount
+ \input formlett.sty
+ \beginletter
+ \NOPAGENUMBERS\parindent=0pt
+ \noindent{\it\paras[1]}\par
+ \blockparas[2]\par\bigskip
+ Dear \paras[1][2],\par\medskip
+ We have been looking for
+ \paras[2][2] for quite a while
+ without any luck, could you help
+ us out? If so, please ring
+ \paras[3][2]. \par\medskip
+ Cheers!\hfill Michael\vfill\eject
+ \endletter \preview
+
+ \beginpilemode
+ Mrs L Stenson;\#1-20 Sunset Street
+ Hills, Norway+Louise;a Bible;220-8888!
+
+ S Wales;UMIST;Manchester+%
+ Sir or Madam;a \TeX\space
+ package{+}manual;225-9905!
+ \endpilemode
+ \end
+\unsetraw
+\rm
+
+
+We note that by default we used plus sign `{\tt +}' to separate
+different groups inside a cluster of parameters, and each cluster inside
+a {\tt\string\beginpilemode} and {\tt\string\endpilemode} pair will
+output a merged letter, as if it were produced by command
+{\tt\string\moreletter} followed by that cluster of parameters.
+The output of the first merged letter in fact reads
+
+\moreletter
+ Mrs L Stenson;\#1-20 Sunset Street
+ Hills, Norway+Louise;a Bible;220-8888!
+
+
+\medskip
+
+It is often desirable to supply parameters line by line, i.e. one line
+as one parameter. Hence the two merged letters produced by lines 25-47
+can also be made by replacing the content included in the
+{\tt\string\beginpilemode} and {\tt\string\endpilemode} pair (lines
+39-46) by the following new code
+
+\setrawcount
+\blockmarks
+\beginblockmode
+Mrs L Stenson
+\#1-20 Sunset Street
+Hills, Norway
+-----
+Louise
+a Bible
+220-8888
+======
+
+S Wales
+UMIST
+Manchester
+----
+Sir or Madam
+a \TeX\ package+manual
+225-9905
+====
+\endblockmode
+\defaultmarks
+\unsetraw
+\rm
+
+where obviously we have used lines with `{\tt----}' to separate groups
+and used lines with `{\tt====}' to end a cluster of parameters. This was
+done by the use of {\tt\string\blockmarks} which changes the group
+delimiter `{\tt +}' and cluster delimiter `{\tt !}' into the above two
+new ones, with the {\tt\string\defaultmarks} at the end setting them
+back. If the whole cluster of parameters are categorised into a single
+(first) group, then we may even use a block of consecutive nonempty
+lines to provide the merging parameters. This is done by the use of
+command pair {\tt\string\beginlinemode} and {\tt\string\endlinemode}.
+Hence we may also conduct the above mail merge in for instance \LaTeX2e
+by
+
+
+\setrawcount
+\documentclass{article}
+\usepackage{formlett}
+\begin{document}
+ \beginletter
+ \NOPAGENUMBERS\parindent=0pt
+ \paras[4]\par\blockparas[5]
+ \par\medskip
+ Dear \paras[1], \par\medskip
+ We have been looking for
+ \paras[2] for quite a while
+ without any luck, could you help
+ us out? If so, please ring
+ \paras[3]. \par\medskip
+ Cheers!\hfill Michael\vfill\eject
+ \endletter
+
+\beginlinemode
+Louise
+a Bible
+220-8888
+Mrs L Stenson
+\#1-20 Sunset Street
+Hills, Norway
+
+Sir or Madam
+a \TeX\ package+manual
+225-9905
+S Wales
+UMIST
+Manchester
+\endlinemode
+\end{document}
+\unsetraw
+\rm
+
+Notice that we have changed the numbering order of the parameters so
+that the number of address lines output by {\tt\string\blockparas} is
+more flexible.
+
+
+\bigskip
+{\lbold Advanced features}
+
+The advanced features to be discussed below are mainly for the purpose
+of (i) writing {\sl long} form letter; (ii) making {\sl many} different
+form letters; (iii) reading mail merge parameters that are in {\sl
+crude} ASCII form; and (iv) generating mail labels.
+
+\medskip
+
+It is in general better to keep the letter template, i.e. the content
+between {\tt\string\beginletter} and {\tt\string\endletter} like those
+in lines 4-13, in a separate file, say {\tt myletter.let}, and use
+{\tt\string\inputletter$\{$myletter.let$\}$} to load in the letter
+template. The advantage of this over the previously used method is that
+the letter template can now be arbitrarily large without any risks of
+causing computer memory problem.
+
+\medskip
+
+Suppose we have a collection of letter templates, we may wish to remind
+ourselves what each parameter represents. For this purpose, we may add
+at the top of the letter template a command {\tt\string\paranames} {\it
+cluster}{\tt !}, where {\it cluster} is a cluster of parameters each
+giving a name to the corresponding parameter. Command
+{\tt\string\paranames} takes its macro parameters in the same way
+{\tt\string\moreletter} does. After a letter template is read in,
+command {\tt\string\showparas} will output a form letter with its
+parameters replaced by the corresponding names. The mainly italic
+passage containing lines 23-24, for instance, is the output of
+{\tt\string\showparas} for the letter template in lines 102-109 given
+explicitly later on.
+
+\medskip
+
+We may also use {\tt\string\paradefaults} {\it cluster}{\tt !} to
+provide default parameters, i.e. the parameters to replace the empty or
+not entered ones, and use {\tt\string \loaddefaultparas} inside letter
+template to activate the parameter defaulting. We note that in general
+commands {\tt\string\paranames} and {\tt\string\loaddefaultparas}, if
+present, should be at the top of the letter template, with
+{\tt\string\loaddefaultparas} below the command {\tt\string\paranames}.
+Hence for our previous mail merge, we may re-do it via
+
+
+\setrawcount
+ \input formlett.sty
+ \beginletter
+ \paranames % optional
+ \tt<<FULL NAME>>;\tt<<ADDRESS-etc>>;%
+ +\tt<<GIVEN NAME>>;\tt<<MISSING ITEM>>;%
+ \tt<<PHONE NUMBER>>!
+ \loaddefaultparas % optional
+\unsetraw
+
+\ \ \ {\it $\{$letter details given in lines 27-36$\}$}
+\hfill{\tiny\fillzeros[4]\linecount\global\advance\linecount1\relax}
+
+\setrawcount
+ \endletter
+ \preview \showparas
+
+ \paradefaults % optional
+ To whom this may concern
+ +Sir or Madam;something;%
+ 061-225-9905!
+
+\blockmarks
+\beginrawblockmode{}
+Mrs L Stenson
+#1-20 Sunset Street
+Hills, Norway
+------
+Louise
+a Bible
+220-8888
+=========
+
+......
+
+Above empty line active
+\endrawblockmode
+\defaultmarks
+\end{document}
+\unsetraw
+\rm
+
+We note that in {\sl blockmode} with {\tt\string\blockmarks}, a line
+with `{\tt ....}' marks the immediate start of a parameter block,
+whether or not the lines immediately following it are empty or not. Also
+that in {\it rawblockmode} enclosed by {\tt\string \beginrawblockmode}
+and {\tt\string\endrawblockmode}, all characters are input in their
+original ASCII form. In other words, the special characters for
+\TeX\space will be ignored here.
+
+\medskip
+
+If the merging parameters are given by exactly $m$ lines per cluster, as
+is often the case when they are produced by a database utility, then we
+may use the {\tt\string\begindatamode} and {\tt\string\enddatamode} pair
+to mark the beginning and the end of the merging parameters. For more
+details, see the Appendix at the end.
+
+\medskip
+
+We may keep the letter template and the merging parameters in two
+separate files. For instance, if we save lines 103-108 to file {\tt
+myletter.let}, lines 39-46 or lines 48-68 to file {\tt myletter.adr},
+then we can produce via \LaTeX\ the mail merge by
+
+\setrawcount
+ \documentstyle[formlett]{article}
+ \begin{document}
+ \inputletter{myletter.let}
+ \showparas \preview % utility demo
+ \paradefaults To whom it may concern!
+ \inputfile{myletter.adr}
+ \beginlabels % 1st group as address
+ \inputfile{myletter.adr} % for labels
+ \endlabels
+ \end{document}
+\unsetraw
+\rm
+
+where the lines 140-142 will generate the address labels using the first
+group (as is intended here) of parameters. More precise format of
+{\tt\string\beginlabels} and etc can be found in the Appendix.
+
+\medskip
+
+Another way of making labels, if no separate files for the parameters
+are present, is to re-read the document itself and make labels instead
+of merged form letters in the second reading. We may thus use {\tt
+\string\input \ formlett.sty \string\initstyle\ [{\it styles}]$\{${\tt
+article}$\}\{${\it preamble}$\}$} to replace {\tt \string\documentstyle\
+[formlett, {\it styles}]$\{$article$\}$ {\it preamble}
+\string\begin$\{$document$\}$}, which will be valid for \LaTeX\ but
+ignored for \TeX\ , and will enable one to use {\tt \string\labelsquit}
+at the end to read in the current document again with all the letters
+there converted into the corresponding labels. Though
+{\tt\string\initstyle} is valid for plain \TeX, \LaTeX2.09 as well as
+\LaTeX2e, {\tt\string\initclass} will generate
+{\tt\string\documentclass} instead of {\tt\string\documentstyle} when
+\LaTeX2e is the processing environment. If you only want to execute
+certain commands the first time round (i.e. before {\tt
+\string\labelsquit} re-reads the file again), use {\tt
+\string\firstread$\{${\it commands}$\}$} for this purpose. For more
+detailed use and examples, read the {\sl programmer's document} attached
+to the style file {\tt formlett.sty} and the example files it generates.
+In fact, many details and extra features that are not contained in this
+article may be found there.
+
+\medskip
+
+We already noted that if a form letter is large, we have to use
+{\tt\string\inputletter} to load in the template. However, it is often
+still desirable to keep everything inside a single file, while allowing
+it to make new (scratch) files when it is being compiled. We may thus
+use for example
+
+\setraw
+ \beginfile{myletter.let}
+\unsetraw
+
+\ \ \ {\it $\{$letter template of lines 103-108$\}$}
+
+\setraw
+ \endfile
+\unsetraw
+\rm
+
+to create a letter template file {\tt myletter.let}. Likewise, the
+merging parameters can be saved to another run-time created file {\tt
+myletter.adr}.
+
+
+\medskip
+
+We have so far only used the default delimiters `{\tt ;}', `{\tt +}' and
+`{\tt !}' to separate single, group and cluster of parameters, with
+temporary change via {\tt\string\blockmarks} to `{\tt ....}', `{\tt
+----}' and `{\tt ====}' respectively. However we may change the
+delimiters to any characters by {\tt
+\string\delimiters$\{S\}\{G\}\{C\}$}, where $S$, $G$ and $C$ are the
+tokens to delimit single, group and cluster of parameters respectively,
+and change the delimiters back to the default by
+{\tt\string\defaultmarks} or equivalently by
+{\tt\string\delimiters$\{$;$\}\{$+$\}\{$!$\}$}.
+
+\medskip
+
+
+To conclude this section, let us finally look below at an `ideal' and
+`finished' mail merge application code,. It is currently in a form
+compilable under \LaTeX2e, and is also valid for plain \TeX\space if the
+first three lines (lines 144-146) are removed.
+
+\setrawcount
+\documentclass{article}
+\usepackage{formlett} % LaTeX2e
+\begin{document}
+
+%%%% MAKE file scr@tch@.let
+\beginfile{scr@tch@.let} % letter content
+\paranames <<name>>;<<address>>+<<items>>!
+\loaddefaultparas
+\parindent=0pt\blockparas\bigskip\bigskip
+Dear \paras, \par\bigskip
+This part is typically the letter content.
+It now displays all the items in the 2nd
+parameter group. They are \par
+\blockparas[][2] \vfill\eject
+\endfile
+
+%%%% MAKE file scr@tch@.adr
+\beginfile{scr@tch@.adr} % address file
+\blockmarks
+\beginblockmode
+T Teng
+UMIST
+Manchester M60 1QD
+=====
+
+Z Jiang
+UNE
+Armidale NSW 2351
+Australia
+------
+Email: zhuhan@neumann.une.edu.au
+=====
+\endblockmode
+\defaultmarks
+\endfile
+
+% MAIN BODY
+\paradefaults To Whom It May Concern
+ +No further info available{!}!
+\inputletter{scr@tch@.let}
+\inputfile{scr@tch@.adr}% for letters
+\beginlabels
+\inputfile{scr@tch@.adr}% for labels
+\endlabels
+\end{document}
+\unsetraw
+\rm
+
+We note that if we replace lines 144-146 by {\tt\string\input\space
+formlett.sty \string\initstyle$\{\}\{\}$}, then the mail merge can be
+processed by either plain \TeX\space or \LaTeX\space (including
+\LaTeX2e). It is likewise if {\tt\string\initstyle} in the replaced
+line is replaced furthermore by {\tt\string\initclass}, except that now
+the native \LaTeX2e environment is preserved, when applicable, rather
+than turning it into the compatibility mode of \LaTeX2.09.
+
+\bigskip
+{\lbold Programmer's tips}
+
+\smallskip
+
+First we note that all the macro parameters that are to appear inside
+square brackets of {\tt formlett}'s commands are defaulted, just like
+how {\tt\string\paras[$m$][$n$]} is defaulted earlier on. The actual
+default values can be found in the Appendix.
+
+\medskip
+
+For those wizard users who want to do everything their own way, we point
+out that if for instance the 3rd letter parameter of the 2nd group of a
+cluster is given as {\tt<A>}, then {\tt \string\LET2*3\t} will contain
+{\tt \string\b@group \string\relax {\tt<A>}\string\e@group} right after
+a cluster is read in. {\tt \string\DEF2*3\string~}, on the other hand,
+contains the corresponding default parameter in the same fashion.
+Furthermore, the command {\tt\string\checkparas[$m$][$n$]$\{$LET$\}$}
+will copy the content of {\tt\string\paras[$m$][$n$]}, minus the
+`wrapping' extra tokens {\tt\string\b@group\string\relax} and
+{\tt\string\e@group}, to {\tt\string\cachedata} and set
+{\tt\string\ifemptyparas} to true or false depending on whether the
+content is empty or not. This way, a user may even change the
+characteristics of his letter template by first testing the content of
+the supplied individual parameters. However, we note that if {\tt\string
+\loaddefaultparas} is executed, then the {\tt LET} array, when some of
+its elements are not supplied, will contain the corresponding elements
+of the {\tt DEF} array. Hence care must be exercised under such
+circumstances, when interpreting the {\tt\string\cachedata} generated by
+{\tt\string\checkparas[$m$][$n$]$\{$LET$\}$}. If necessary, we may use
+{\tt\string\delparadefaults} to delete current default parameter array
+{\tt DEF} so as to conduct {\tt\string\checkparas$\{$LET$\}$} more
+precisely.
+
+\medskip
+
+There are also a number of generic macro utilities in {\tt formlett},
+including a user stack and a multi-dimensional array mechanism.
+
+\medskip
+
+{\tt formlett} was written for all \TeX\space dialects, its format is
+thus more close to that of plain \TeX. In fact, we deliberately avoided
+mixing up {\tt formlett} with the standard letter environment of \LaTeX.
+This is largely due to the fact that the limited facilities of
+\LaTeX\space letter environment are easy to come by anyway, and are not
+really worth writing buckled code to make {\tt formlett} a type of
+extension of the environment. Nevertheless, one can still use the letter
+environment of \LaTeX\space inside the form letter template. Besides,
+the applicability of {\tt formlett} is not restricted for making form
+{\sl letters}; it can also be used to merge other type of articles or
+passages.
+
+
+
+
+\bigskip
+{\lbold References}
+
+\smallskip
+{\parindent=2em
+\item{[1].} Knuth D E, {\sl The \TeX book}, Reading, Mass.,
+Addison-Wesley, 1992. \par
+\item{[2].} Piff M, Text merges in \TeX\ and \LaTeX, {\sl TUGboad},
+13(4):518, 1993. \par
+\item{[3].} Damrau J and Wester M, Form letters with 3-across
+labels capacity, {\sl TUGboat}, 13(4):510, 1991.
+\par
+}
+
+
+
+
+\penalty -50\bigskip
+
+{\lbold Appendix}
+
+
+
+\smallskip
+
+
+In the followings, we give a brief summary of the main commands given by
+{\tt formlett} version 2.1.
+
+\medskip
+
+Let $m$ and $n$ be numbers, $p$, $q$ and $r$ be dimensions, $A$,
+$B$, $S$, $G$, $C$ and $T$ be tokens, and $X$ be a box.
+Furthermore, we shall denote by $R$ a full set of letter
+parameters ended by \lq{\tt !}\rq, with \lq{\tt;}\rqs separating
+parameters inside a same group and \lq{\tt+}\rqs separating
+different parameter groups. We moreover denote $R$ by $F$, when
+\lq{\tt ; + !}\rqs there can be replaced by \lq$S$ $G$ $C$\rqs
+respectively if {\tt \string\delimiters$\{S\}\{G\}\{C\}$} is
+issued. In the commands tabulated below, the macro parameters
+contained in squared brackets support default. In particular, the
+defaults are $m$={\tt 1}, $n$={\tt 1}, $p$={\tt 8truecm},
+$q$={\tt 1.5em}, $r$={\tt 3pt}, $A$={\tt\string\noindent} and
+$B$={\tt\string\par}.
+
+
+
+\newdimen\tempdimone
+\newdimen\tempdimtwo
+\tempdimone=\hsize
+\advance\tempdimone by-0.2pt
+\tempdimtwo=\hsize
+\advance\tempdimtwo by-1.8in
+\def\hruler{\hrule width \tempdimone}
+\long\def\entry#1#2{%
+\par\hbox to \tempdimone{\noindent
+ \vrule~\textbox[1.7in]{#1}~\hss
+ \vrule~\textbox[\tempdimtwo]{\raggedright#2}~\vrule}%
+ \par}
+
+\long\def\longentry#1#2#3{%
+\par\hbox to \tempdimone{\noindent
+ \vrule~\textbox[3in]{#1}~\hss~\vrule}\par
+ {\kern-8pt \advance\tempdimtwo0.10in
+ \vrule width1.7in height0pt \vrule width\tempdimtwo height 0.4pt \par
+ \kern-3pt}
+ \entry{#2}{#3}}
+
+\long\def\Longentry#1#2#3{%
+\par\hbox to \tempdimone{\noindent
+ \vrule~\textbox[3in]{#1}~\hss~\vrule}\par
+ {\advance\tempdimtwo0.08in\kern-1pt
+ \vrule~\hfill\vrule width \tempdimtwo height 0.4pt \vrule\par
+ \kern-2.5pt}%
+ \entry{#2}{#3}}
+
+
+
+\bigskip %\bigskip
+\penalty-1000 \vskip 0pt plus4in
+
+{\eightpoint
+\nointerlineskip\parskip=0pt
+
+\hruler
+\entry{{\tt\string\paras[$m$][$n$]}}%
+ {$m^{th}$ parameter of $n^{th}$ group }%
+
+\entry{{\tt\string\blockparas[$m$][$n$][$A$][$B$]}}%
+ {$m^{th}$ to the last parameter of $n^{th}$ group, each
+preceded by $A$ and followed by $B$, wrapped by $\{$\penalty
+1000$\}$ if
+$B$={\tt\string\relax}}
+
+\entry{{\tt\string\addressparas[$m$][$n$][$p$][$q$]}}%
+ {$m^{th}$ to the last parameter of $n^{th}$ group, each put
+into a box of width $p$ with indent $q$ for wrapped portions}
+
+
+\entry{{\tt\string\loaddefaultparas}}%
+ {fill empty parameters with defaults}
+
+%\hruler \penalty-1000
+\hruler
+
+
+\entry{{\tt\string\checkparas[$m$][$n$]$\{T\}$}}%
+ {$m^{th}$ parameter of $n^{th}$ group copied to {\tt\string\cachedata};
+ {\tt\string\ifemptyparas} is true if element is empty; $T$ is often
+ {\tt LET} or {\tt DEF}}%
+
+
+\hruler
+
+
+\entry{{\tt\string\moreletter\ $F$}}%
+ {use parameters $F$ to output a new letter}
+
+
+\entry{{\tt\string\paranames\ $R$}}%
+ {use $R$ as parameter names}
+
+\entry{{\tt\string\paradefaults\ $R$}}%
+ {use $R$ as default parameters}
+
+\entry{{\tt\string\delparadefaults}}%
+ {delete default parameters}
+
+\hruler
+
+
+\entry{{\tt\string\delimiters$\{S\}\{G\}\{C\}$}}%
+ {use $S$, $G$, $C$ as delimiters}
+
+
+\entry{{\tt\string\defaultmarks}}%
+ {use \lq{\tt ; + !}\rqs as delimiters}
+
+
+\entry{{\tt\string\blockmarks}}%
+ {use \lq{\tt ....}\rq, \lq{\tt ----}\rq, \lq{\tt ====}\rqs as delimiters}
+
+%\hruler \penalty -1000
+\hruler
+
+\entry{{\tt\string\preview}}%
+ {highlight parameter positions}
+
+\entry{{\tt\string\showparas}}%
+ {display parameter names, if any}
+
+\hruler
+
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginfile[$T$]$\{{\it
+file.ext}\}$}\cr
+\hbox{\tt\string\endfile\ \ \ \ \ \ \ \ \ \ \ \ \ }\cr}\right.$\par
+ \ \ \ {\tiny }}%
+ {write text verbatim to file {\it file.ext} (empty implies {\tt
+scr@tch@.tex}), nonempty $T$ replaces {\tt
+\string\endfile} to mark last full line}
+
+
+
+\entry{{\tt\string\inputletter$\{file.ext\}$}}%
+ {input letter content}
+
+\entry{{\tt\string\inputfile$\{file.ext\}$}}%
+ {input $file.ext$}
+
+\hruler \penalty -5000 %\vskip0pt plus 1cm
+\hruler
+
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginletter}\cr
+\hbox{\tt\string\endletter~~}\cr}\right.$ }%
+ {delimiters for letter content (template)}
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginpilemode}\cr
+\hbox{\tt\string\endpilemode~~}\cr}\right.$ }%
+ {normal letter parameters cluster-wise}
+
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginblockmode}\cr
+\hbox{\tt\string\endblockmode~~}\cr}\right.$ }%
+ {for line-by-line blocks of parameters, empty lines active
+within each cluster}
+
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginlinemode}\cr
+\hbox{\tt\string\endlinemode~~}\cr}\right.$ }%
+ {for line-by-line parameters, empty lines delimit clusters}
+
+\hruler \penalty-1000
+%\hruler
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginrawblockmode$\{T\}$}\cr
+\hbox{\tt\string\endrawblockmode\ \ \ \ \ }\cr}\right.$ }%
+ {raw text mode; nonempty $T$ replaces {\tt\string\endrawblockmode}
+ to mark end}
+
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\beginrawlinemode$\{T\}$}\cr
+\hbox{\tt\string\endrawlinemode\ \ \ \ \ \ }\cr}\right.$ }%
+ {raw text parameters and active spaces etc}
+
+\entry{%
+$\left\{\matrix{ \hbox{\tt\string\begindatamode[$T$]$\{m\}$}\cr
+\hbox{\tt\string\enddatamode\ \ \ \ \ \ \ \ }\cr}\right.$ }%
+ {$m$ raw text lines for one form letter}
+
+
+%\hruler \penalty-2000
+\hruler
+
+
+\entry{{\tt\string\PAGENO=1}}%
+ {page number reset to 1}
+
+
+\entry{{\tt\string\NOPAGENUMBERS}}%
+ {no page numbers}
+
+
+\entry{{\tt\string\textbox[$p$]$\{text\}$}}%
+ {$text$ into box of width $p$}
+
+
+\entry{{\tt\string\boxmore[$r$]$\{X\}$}}%
+ {add borderline to box $X$ at a distance $r$}
+
+
+\entry{{\tt\string\addressbox[$p$][$q$]$\{text\}$}}%
+ {$text$ into box of width $p$, with wrapped options indented
+by $q$}
+
+
+\hruler
+
+\Longentry{%
+$\left\{\matrix{ \hbox{\tt\string\beginlabels
+ [$a$][$b$][$c$][$d$][$e$][$f$]}\cr
+ \hbox{\tt\string\endlabels\hskip3cm}\cr}\right.$ }%
+ {\strut\par{\sl defaults:}\everypar={\hbox{\ \ \ }}\par\par
+ $a$={\tt 20pt}, \par $b$={\tt\string\tt\string\raggedright},
+ \par $c$={\tt1}, $d$={\tt1}, \par
+ $e$={\tt2.6in}, $f$={\tt2em}}%
+ {form letters become labels: address taken from $c^{th}$ to
+last parameter of $d^{th}$ group, with width $e$, indent
+$f$, borderspace $a$ and font toks $b$}
+
+\hruler
+
+
+\entry{{\tt\string\firstread$\{T\}$}}%
+ {toks $T$ will not be read if the file is re-read via {\tt
+ \string\labelsquit}}
+
+
+\entry{{\tt\string\initstyle[$a$]$\{b\}\{c\}$}}%
+ {initiation for {\tt\string\labelsquit},with styles $a$,
+ documentstyle $b$ and preamble $c$}
+
+
+\entry{{\tt\string\initclass[$a$][$o$]$\{b\}\{c\}$}}%
+ {similar to {\tt\string\initstyle} ($o$ is \LaTeX2e options),
+ but retains native \LaTeX2e when applicable}
+
+
+\hruler \vskip0.5pt
+\Longentry{%
+$\matrix{\hbox{\tt \string\labelsquit
+ [$a$][$b$][$c$][$d$][$e$][$f$]$\{$\it file.ext$\}$}\cr
+ \hbox{}\cr}$}%
+ {\strut\par{\sl defaults:}\everypar={\hbox{\ \ \ }}\par\par
+ see that for {\tt\string\beginlabels}}
+ {quit after converting letters to labels by reading the current
+ document or {\it file.ext}}
+
+\hruler
+
+}
+
+\footline={\lower5pt
+\hbox to \hsize
+ {{\rm Jiang Z ~~~{\sl Mail merge with the use of formlett.sty}
+ \hss {\sl $\bullet$End of Document$\bullet$}
+\hss \folio}}}
+
+
+\vrule height2.9in width0pt depth0pt
+\endcolumns
+\vfill\eject
+
+
+
+\end{document}
+
+
+
+