path: root/macros/latex/contrib/akletter/lettereng.tex

\documentclass[a4paper]{article}
\usepackage{german}
\setlength{\unitlength}{1mm}

\title{Akletter.cls\\Manual}
\author{Axel Kielhorn\\a.kielhorn@tu-bs.de}

\begin{document}
\maketitle

\section{Preface}

In the beginning there was Lindner-\TeX\ for the Atari St computer. It 
came with a letter style called \verb+liletter.sty+. I adapted the 
style to my liking and saw that everything was good.

On the second day, my roommate came, saw my letters and wanted a 
similar style for his correspondence, thus a second letter style was 
created and everything was good.

On the third day, I had to write an official letter for the students 
group I was working with and I had to create a third letter style. 
And I said onto myself ``Well, that's a fine mess you got yourself 
into.''

And than came the June of 1994 and They released \LaTeXe. I realized 
immediately that I had to adjust my letter styles. And I decided to 
separate the class from the user defined settings and put the class 
into a \verb+.cls+ file and the user defined settings into a 
\verb+.cfg+ file. And again everything was good.

After someone asked in \verb+de.comp.text.tex+ for a letter class 
suitable for ISO A4 paper that will work with envelopes with windows, I 
said onto my letter class ``Go out into the world and show the people 
out there how to print letters with \LaTeX.'' And my letter class was 
distributed throughout the internet to every user who has to print 
letters on A4 paper. And it was not only used in the german speaking 
countries but spread even to Norway and Italy where the german tongue 
was not well known, except in some holiday centers where you find 
few \LaTeX\ users.

And a cry came onto me ``Dear Axel, who has made \verb+akletter.cls+, 
can you give us, who do not read nor speak german, an english version 
of the documentation to your class?'' And I said onto me ``Oh bugger, 
that will be a lot of work, but it is raining outside and I have 
nothing better to do, so why not?'' And this is the story of this 
document. If you don't like it try \verb+scrlettr.cls+ from the 
Koma-Script packages which is a very nice letter class and even 
shares some code with \verb+akletter.cls+.

\section{What does \texttt{akletter.cls} do?}

\texttt{akletter} implements a fixed layout for the first page of a 
letter. This layout consists of boxes at fixed positions with a more 
or less variable contents. This picture will give you an impression 
about how the layout looks:

\begin{picture}(100.00,140.00)
\put(5.00,5.00){\framebox(90.00,130.00){}}
\put(5.00,120.00){\framebox(90.00,15.00){}}
\put(70.00,135.00){\framebox(0.00,0.00){}}
\put(65.00,120.00){\framebox(30.00,15.00){}}
\put(65.00,85.00){\framebox(30.00,35.00){}}
\put(5.00,85.00){\framebox(45.00,25.00){}}
\put(5.00,80.00){\framebox(90.00,5.00){}}
\put(5.00,75.00){\framebox(60.00,5.00){}}
\put(65.00,75.00){\framebox(30.00,5.00){}}
\put(5.00,110.00){\framebox(45.00,5.00){}}
\put(5.00,65.00){\framebox(45.00,5.00){}}
\put(5.00,25.00){\framebox(45.00,5.00){}}
\put(5.00,5.00){\framebox(90.00,20.00){}}
\put(10.00,126.5){{FIRM}}
\put(10.00,111.5){{Firmreturn}}
\put(10.00,96.5){{Addressfield}}
\put(10.00,81.5){{Ref"|line}}
\put(10.00,76.5){{Subject}}
\put(10.00,66.5){{Opening}}
\put(10.00,26.5){{Closing}}
\put(10.00,16.5){{Firmfoot}}
\put(70.00,126.5){{Firmaddress}}
\put(70.00,106.5){{Right-}}
\put(70.00,101.5){{box}}
\put(70.00,76.5){{Date}}
\end{picture}

Some of these boxes are static. They are created once (at the 
\verb+\begin{document}+ command) and cannot be changed later.

\begin{itemize}
\item FIRM
\item Firmaddress
\item Firmreturn
\item Firmfoot.
\end{itemize}

The other boxes are created for each letter (did you know that you can 
have more letters in one document? Well, don't bother, it is easier to 
have one document for each letter).

\begin{itemize}
\item Ref"|line
\item Subject
\item Opening
\item Closing
\end{itemize}

The layout of these boxes is defined in the \texttt{cfg} file. You can
select different \texttt{cfg} files with the \verb+\usename+ command.
If you omitt it, \texttt{akletter.cfg} will be used. Thus all the user
specific data is separated from the class file and you should be able
to update the class without changing the \texttt{cfg} file. This
didn't always work because I change the interface to allow for new
configuration options but in theory it was a good idea.

\section{The \texttt{cfg} file}

This file contains all the user specific options. You should never 
have to edit the class file.\footnote{This may not be true if you want 
to add a new language or some fancy option.} You usually create this 
file once when you install \texttt{akletter.cls} and never touch it 
again. (Unless you move, change your ISP, marry or whatever). You 
should keep a copy of \texttt{akletter.cfg} because it contains a lot 
of small code-fragments that you may want to use later.

\begin{verbatim}
\makeatletter
\end{verbatim}

You may have to redefine some internal commands.

\begin{verbatim}
\telephone{0800 / 12 34 56 }
\telefax  {}
%% You may include logos and other graphic-material into
%% your letterhead:
%%
%%\RequirePackage[dvips]{graphics}
\end{verbatim}

Define your phone and fax number, thus you don't have to type it for 
every new letter. If you want to include a picture in your 
letterhead (or a scanned signature) you may need the graphics-package.

\begin{verbatim}
%% You may redefine the following variables
%%

%\renewcommand*{\yourrefname}   {Ihr Zeichen:}
%\renewcommand*{\yourmailname}  {Ihr Schreiben vom:}
%\renewcommand*{\myrefname}     {Unser Zeichen:}
%\renewcommand*{\mymailname}    {Unser Schreiben vom:}
%\renewcommand*{\customername}  {Kundennummer }
%\renewcommand*{\invoicename}   {Rechnungsnummer }
%\renewcommand*{\subjectname}   {}  %{Betr.}
%\renewcommand*{\ccname}        {Kopien an:}
%\renewcommand*{\enclname}      {Anlagen:}
%\renewcommand*{\headtoname}    {An}
%\renewcommand*{\datename}      {Datum}
%\renewcommand*{\pagename}      {Seite}
%\renewcommand*{\telephonename} {Telefon}
%\renewcommand*{\telefaxname}   {FAX}
\end{verbatim}

You can change the text \texttt{akletter.cls} inserts into your letter. 
This does only work with \texttt{german.sty}. When you use \texttt{babel.sty} 
you may need to add some more code to your \texttt{cfg} file to make 
it work. The code below may help you getting it to work:

\begin{verbatim}
\let\savedcaptions\captionsgerman
\def\captionsgerman{\savedcaptions
   \renewcommand*{\myrefname}	{Mein Zeichen:}
   }
\end{verbatim}


\begin{verbatim}
%% Alternate definitions for the reference-line.
%% Use this if you do not need a mymail-entry.
%% In fact you can do a lot of things with these
%% 4 entries, e.g. setting \mymailname to {InvoiceNo}
%% and using \mymail to display an invoiceno.
%% You may change these lines but make sure that
%% the combined length of the 3 fields is 1\leftfield
%% or less.
%\def\yref#1{\def\@yref{\parbox[t]{.33\leftfield}
%    {\scriptsize \yourrefname\\ \normalsize #1}}
%     reftrue}
%\def\ymail#1{\def\@ymail{\parbox[t]{.33\leftfield}
%    {\scriptsize \yourmailname\\ \normalsize #1}}
%     reftrue}
%\def\myref#1{\def\@myref{\parbox[t]{.33\leftfield}
%    {\scriptsize \myrefname\\ \normalsize #1}}
%     reftrue}
%\let\mymail=\@gobbleone
\end{verbatim}

The reference line is build according to DIN~676 but can be redefined 
according to your needs. The normal layout uses 4 fields unless you 
use the \verb+refdate+ option, then it uses 5 fields. The code above 
changes that to 3 fields.


\begin{verbatim}
%%% Top of first page: left
\sbox{\FIRM}
   {\parbox[t]{\leftfield}
   {\fontsize{17.28}{22pt}\fontseries{bx}\selectfont%
    Mein Name\hfill}}
%%% Top of first page: right
\sbox{\firmaddress}
% Use either Text:
   {\parbox[t]{\rightfield}{%
    \fontsize{9}{10pt}\selectfont\normalfont
    Meine Stra{\ss}e 1\\ 12345 Meindorf}}
% or graphic:
% {\includegraphics{ourlogo}}
% and don't forget to adjust FIRM and firmaddress:
%%% Top of first page: left + right
%%% You may want to adjust the raisebox
\sbox{\FIRMHEAD}
   {\usebox{\FIRM}\raisebox{3mm}{\usebox{\firmaddress}}}
\end{verbatim}

The letterhead on the first page consists of the two boxes
\texttt{FIRM} and \texttt{firmaddress} which will be put together into
\texttt{FIRMHEAD}. I use this approach because it enables me to shift
the \texttt{firmaddress} up and down to make it look correct and to
make it easier to include a logo in one of the boxes.

\begin{verbatim}
%%% Top of every other page
\sbox{\firm}
   {\fontsize{10}{12pt}\selectfont\normalfont
    Mein Name}
\end{verbatim}

The following pages do not need such an elaborated layout, simply put 
your name on it. If you really want to use some fancy headings look 
into the \verb+cfg+ file for suggestion or use \verb+fancyhdr.sty+.

\begin{verbatim}
% \if@twoside % Twoside definition
%   \def\ps@headings{%
%       \def\@oddfoot{\hfil Text on the odd page}
% 	  \def\@evenfoot{Text on the even page\hfil}
%       \def\@oddhead{\usebox{\firm}
%          \headfont\hfil\@date\hfil\pagename\ \pnumfont\thepage}%
%       \let\@evenhead\@oddhead}
% \else % Oneside definition
%   \def\ps@headings{%
%       \def\@oddfoot{\hfil Text for one-side layout\hfill}
%       \def\@oddhead{\usebox{\firm}
%          \headfont\hfil\@date\hfil\pagename\ \pnumfont\thepage}}
% \fi
\end{verbatim}

\begin{verbatim}
%%% Return address
%%% one line version
\sbox{\firmreturn}
   {\underline{\fontsize{7}{8pt}\selectfont
    \hskip5mm Mein Name $\cdot$ Meine Stra{\ss}e 1
    $\cdot$ D--12345 Meindorf\hskip5mm}}
%%% two line version
%\sbox{\firmreturn}
%   {\underline{
%      \fontsize{7}{8pt}\fontfamily{\sfdefault}\selectfont
%      \hskip3mm\parbox{65mm}
%      {\makebox[65mm][c]
%	  {Fachschaft -- Maschinenbau $\cdot$
%	   \mbox{\raise .75ex \hbox{c}\kern -.15em /\kern -.125em
%	       \smash{\lower .3ex \hbox{o}}}
%		AStA TU Braunschweig}
%	\makebox[65mm][c]
%	   {Katharinenstra{\ss}e 1 $\cdot$ D--38106 Braunschweig}}
%   \hskip3mm}}
\end{verbatim}

It is always nice for the addressee to see the sender of the letter 
before opening it. If you don't happen to have envelopes with your 
name and corporation printed on them, you may want to use a line 
above the address to show who you are. 

\begin{verbatim}
%%% Firstpage footer
%%% The code should be controlled by @banklo
\sbox{\firmfoot}
   {\fontsize{9}{11pt}\selectfont
%%% The following line may look nice in a FAX.CFG :-)
%%% If you have a bad telephone-line try snail-mail!\\
     \if@banklo
       \ifnum\language = \l@german
	  Bankverbindung:
	  \hspace{5mm}
	  \parbox[t]{\rightfield}{\raggedright
	  Undeutsche Landesbank Frankfurt,
	  BLZ~123\,456\,78, Konto~1\,111\,007\\}%
	  \hspace{5mm}
	  \parbox[t]{\rightfield}{\raggedright
	  Die Sparkasse Meindorf,
	  BLZ~007\,123\,10, Konto~08\,15\\}
       \fi
     \fi}
\end{verbatim}

The footer of the first page is quite complex because it contains 
vital information if you are a company. (But then you will have your 
own stationary and don't have to print this every time.) According to 
DIN this is where information about your bank connection, the type of 
your company, the registration number in the register of commerce and 
all this should go. Since you won't need this information for a 
private letter, there is a switch to enable it. Use the option 
\texttt{banklow} if you want this information to appear.

Some amateur designers put this information in the letter head, 
right of the address. Since this place is dedicated for a 
``received'' rubber stamp it should remain free. But if you want to 
use it, see below:

\begin{verbatim}
%%% Text displayed below the header on the right side
%%% This should be controlled by @bankhi
%%% This is the only place that will be re-evaluated for
%%% every letter! Everything that changes for different
%%% letters (in the same document) must go either here
%%% or in the ref-line.
\newcommand{\rightbox}
    {\parbox[t]{\rightfield}
    {\fontsize{9}{11pt}\selectfont
     \raggedright
     \ifx\fromname\@empty
     \else
       \ifnum \language = \l@german
	  Sachbearbeiter:
       \fi
       \fromname\\
     \fi
     \ifx\telephonenum\@empty
	 \ifnum \language = \l@german
	   \telephonename: 040 / 44\,17\,77
	 \else
	   \telephonename: 49--40--44\,17\,77
	 \fi
     \else
	 \telephonename: \telephonenum
     \fi\\[1.5ex]
     \ifx\telefaxnum\@empty
	 \ifnum \language = \l@german
	   \telefaxname: 040 / 44\,17\,77
	 \else
	   \telefaxname: 49--40--44\,17\,77
	 \fi
     \else
	 \telefaxname: \telefaxnum
     \fi\\[1.5ex]
     \ifx\@email\@empty
	 e-mail Kein Mehl\\[1.5ex]
     \else
	 e-mail: \@email \\[1.5ex]
     \fi
     \if@bankhi
       \ifnum \language = \l@german
	  Bankverbindung:\\[1ex]
	  Undeutsche Landesbank Frankfurt,
	  BLZ~123\,456\,78, Konto~1\,111\,007\\[.5ex]
	  Die Sparkasse L\"uneburg,
	  BLZ~007\,123\,10, Konto~08\,15 \\[.5ex]
       \fi
     \fi
     %% Finally fixed it!
     %% If you want to have the date here, set the
     %% rightdate option.
     %% (With a big excuse to Markus and many others, who
     %% had to wait that long)
     \if@rightdate
       \vspace{0.5ex}
       \normalsize\@date
     \fi    
      }}
\end{verbatim}

This rather complex code prints some text to the right of the address 
field. It will be evaluated for every new letter thus things that 
change from letter to letter has to go here. Some of the text shown 
in the example above should really be in the footer, but since people 
keep asking me how to put it into the rightfield I include it here. 
You have to set the \texttt{bankhigh} option to enable some of the 
code above. Note that \texttt{banklow} and  \texttt{bankhigh} are 
not exclusive, you can define both if you want.

\begin{verbatim}
%% The labels defined in akletter.cls are what my printer likes:
%% Onecolumn, 100mm * 50mm, 3mm separation.
%% If you have different lables edit here:

%\renewcommand*{\startlabels}{\labelcount\z@
%   \pagestyle{empty}\let\@texttop\relax
% The margins are calculated from the 1in,1in point,
% thus negative values will occur if the margins are smaller
%   \topmargin -60\p@
%   \headsep \z@
%   \oddsidemargin -35\p@
%   \evensidemargin -35\p@
%   \textheight 10in
%   \@colht\textheight	\@colroom\textheight \vsize\textheight
%   \textwidth 550\p@
% You may have to increase columnsep if you use twocolumn
% This is what letter.cls uses.
%   \columnsep 26\p@
% This does almost nothing since there is an explicit 
% fontsize-command in the text written.
%   \ifcase \@ptsize\relax
%     \normalsize
%   \or
%     \small
%   \or
%     \footnotesize
%   \fi
%   \baselineskip \z@
%   \lineskip \z@
%   \boxmaxdepth \z@
%   \parindent \z@
% This is obvious, isn't it?
%   \twocolumn
%   \relax}

%% This is how the label will look like when printed.
%% Note that specialmail will be written to the .aux-file
%% when the letter is processed. The width used here is
%% what letter.cls uses. 

%\renewcommand*{\mlabel}[2]{%
%  \parbox[b][2in][c]{262\p@}{%
%     \strut\ignorespaces\usebox{\firmreturn}\\
%     \fontsize{12}{14pt}\selectfont
%     \parbox[t][1.2in][c]{3in}{#2}
%   }\par%
%}
\end{verbatim}

The code above overrides the normal code for printing address labels. 
It has to be adjusted for the kind of labels you use. You may even 
have to include some specials to tell the printer to select the labels 
from a different tray. This is left as an exercise to the reader. (But 
note that you can get envelops with windows in C5 and C4 (if that 
means anything to you) thus you may never need to print labels.)

\begin{verbatim}
\makeatother
\endinput
\end{verbatim}

You may want to include something like the following into your
\texttt{.cfg} file:

\begin{verbatim}
\email{A.Kielhorn@tu-bs.de}
\mailbox{}
\name{A. Kielhorn } 
\signature{(Axel Kielhorn)}

\end{verbatim}

\section{The first letter}

You can't define everything in the \texttt{cfg} file, otherwise you 
would be writing the same letter again and again. Thus there are many 
settings you have to define in every letter:

The following commands have to appear in the preamble, before
\verb+\begin{document}+.

\begin{description}
	
\item [\texttt{usename{default}}] selects the \texttt{cfg} file.

\item [\texttt{pagestyle\{headings\}}] Style of the following pages,
can be headings, plain or empty.

\item [\texttt{makelabels}] Do you really want to generate labels?

\item [\texttt{selectlanguage\{english\}}] The language you want to
use (obvious, isn't it?) You \emph{have} to set it in the preamble
because the boxes containing the fixed text are defined by the
\verb+\begin{document}+ command and they have to know the language of
the letter.

\end{description}

Since version 1.5e there are some additional options to change the 
layout of the letter, if you really want to (These commands have been 
added to enable one user to copy a certain WinWord design):

\begin{description}
	\item[\texttt{reffont}]  \verb+\renewcommand*\reffont{}+ changes the 
	font that \texttt{akletter} uses to print the text in the reference 
	line, the default is \texttt{normalfont}

	
	\item[\texttt{reftextfont}] \verb+\renewcommand*\reftextfont{}+ 
	changes the font used to print the arguments (i. e. the user supplied 
	text) in the reference line, default is \texttt{normalfont}

	\item[\texttt{headfont}] \verb+\renewcommand*\headfont{}+ changes 
	the font used to print the heading on every page but the first. This 
	will only work with the pagestyle headings, default is \texttt{slshape}

	\item[\texttt{pnumfont}] \verb+\renewcommand*\pnumfont{}+ changes the 
	font used to print the pagenumber, default is \texttt{normalfont}
	
\end{description}

The following commands are letter specific. If you change them 
inside a letter environment they will not affect subsequent letters.

\begin{description}
\item [\texttt{telephone\{0800 - 12 34 56\}}] Overriding the default 
telephone number
\item [\texttt{telefax\{0800 - 12 34 57\}}] the fax number,
\item [\texttt{email\{A.Kielhorn@tu-bs.de\}}] email address
\item [\texttt{mailbox\{ \}}] and mailbox.
\item [\texttt{name\{A. Kielhorn\}}] When you have \texttt{.cfg} file for the 
whole company, you may want to set the name of the individual user 
here instead of generating lots of cfg files.
\item [\texttt{signature\{(Axel Kielhorn)\}}] usually the name, but 
you can specify any signature.
\item [\texttt{specialmail\{Recommand\'e\}}] This will be printed in 
bold above the recipients address. (Hey, I know some french!) 
\item [\texttt{refdatename\{Braunschweig, den\}}] The location where 
the letter was written. 
\item [\texttt{yref\{ \}}]
\item [\texttt{ymail\{1.6.1994\}}]
\item [\texttt{myref\{ak/AK\}}]
\item [\texttt{mymail\{1.6.1994\}}]
\item [\texttt{subject\{LaTeX2e Letter-style\}}] 
\item [\texttt{invoice\{Invoice number\}}] still experimental
\item [\texttt{customer\{Customer number\}}] still experimental
\item [\texttt{opening\{Dear friends,\}}] This command generates the 
letterhead you must not omit it, but you can use an empty argument if 
you don't want to address the reader.

\end{description}

Here comes the text\dots

The end:
\begin{description}
\item [\texttt{closing\{mfg\}}] This command closes the letter, it 
must not be omitted but may contain an empty argument.
\item [\texttt{cc\{comp.text.tex\}}] A copy for the archive
\item [\texttt{encl\{akletter.cfg\}}] And an enclosure
\item [\texttt{ps}] Hey, the letter is finished. No long postscriptum 
please.
\end{description}

\section{Mass mailings}

Version 1.4 of \texttt{akletter} introduced a way to generate 
mass mailings. This is compatible to \texttt{scrlettr.cls} from the 
Koma-Script package. If you want to know how to use it read the 
Koma-Script manual.

\section{Options}

\texttt{akletter.cls} understands some options

\begin{description}
\item [\texttt{a4paper}] Selects the page format. A4 is the default.

\item [\texttt{a4offset}] This layout ist shiftet 24 points to the 
right and 24 points narrower than a4paper. It looks better when you 
put the letter into a binder that covers the left margin of the page. 
These binders are often used for job applications.

\item [\texttt{letterpaper}] This options adapts the layout to US 
letter paper. Since I haven't seen an envelope with a window for the 
address in the US I'm not sure if it is usable, but you can put the 
letter into a german DIN 680 DL envelope.

\item [\texttt{banklow}] and
\item [\texttt{bankhigh}] are two switches to enable some code that
depends on these switches. In the cfg file distributed with
\texttt{akletter} this set the bank connections either at the bottom
or in the right field.

\item [\texttt{foldmarks}] This shows where to fold the letter to make
it fit into the envelop. It doesn't work on some printers like my
Deskwriter:-(

\item [\texttt{refdate}] The date will be printed in the reference
line thus changing the layout to 5 items.

\item [\texttt{subjectdate}] The date is printed in the same line as
the subject (default).

\item [\texttt{rightdate}] Prints the date in the rightfield unless
you change the code:-)

\end{description}

Version 1.5 h of \texttt{akletter} supports the date format according 
to ISO 8601 which looks like YYYY-MM-DD, e.g. 2000-05-28 for the 28th 
of May 2000. You can activate this format with \verb+\dateiso+ in the 
preamble. When you change the language the format is reset to the 
default for that language, thus you have to put the \verb+\dateiso+ 
after the \verb+\selectlanguage+ command. This format is recommeded 
by the Chicago Manual of Style.

\section{Thanks}

I would like to thank Donald E. Knuth and Leslie Lamport for creating 
\TeX\ and \LaTeX, Stefan Lindner for porting it to the Atari, Andrew 
Trevorrow for porting it to the Mac and the \LaTeX3-Team.

Special thanks to the beta testers who found lots of bugs in previous 
versions and suggested a lot of new features thus keeping me busy on 
rainy afternoons.

\end{document}