path: root/Master/texmf-dist/doc/latex/cdpbundl/cdp-ver-0-36.tex

\begin{filecontents}{myarticletter.cls}
\NeedsTeXFormat{LaTeX2e}[1998/06/01] % LaTeX2e is required!
\ProvidesClass{myarticletter}
              [2018/02/08 v0.03 (development)]
\LoadClassWithOptions{articoletteracdp}[2018/02/08]
\input{mylogo.def}
\endinput
\end{filecontents}



\begin{filecontents}{mylogo.def}
\ProvidesFile{mylogo.def}[2018/02/08 v0.03 (development)]

\RequirePackage[customletterhead]{cdpaddon}[2018/02/08]
\RequirePackage{color}

\DeclareFontFamily{T1}{my@calli}{}
\DeclareFontShape{T1}{my@calli}{m}{n}{<->s*[1.44]callig15}{}
\definecolor{my@lh@color}{rgb}{0,.4,.4}

\begin{customletterhead}{\textwidth}
    \color{my@lh@color}
    \fontsize{17}{21}\usefont{T1}{my@calli}{m}{n}
    \leftline{%
        \setlength{\unitlength}{1cm}%
        \begin{picture}(0,0)
            \put(-2,0){\framebox(1.8,1.2){%
                \normalsize\ttfamily My Logo%
            }}
        \end{picture}%
        My Company'\,s Letterhead\enspace
        \hrulefill\hspace{-2cm}%
    }
\end{customletterhead}

\settowidth{\longindentation}{%
    \fontsize{17}{21}\usefont{T1}{my@calli}{m}{n}%
    My Company'\,s Letterhead\enspace
}

\begin{customletterfoot}{\textwidth}
    \color{my@lh@color}
    \fontsize{5}{6}\usefont{T1}{pplx}{m}{n}
    \raggedleft
    \ruleacrossheadorfoot[-2cm]
    My (almost unreadable) \textsc{small print},\\
    aligned along the \textit{right} edge\\
    of the main text.
\end{customletterfoot}

\renewcommand*{\foldingtagrule}{%
    \color{my@lh@color}\CDPFactoryFoldingTagRule
}

\endinput
\end{filecontents}



\documentclass
    [twoside,boldsubject,italicsignature,shortindent,signaturerule]
    {myarticletter}[2018/02/08]
\usepackage[T1]{fontenc}
\usepackage[english]{cdpbabel}
\usepackage[bookmarksnumbered,hypertexnames=false]{hyperref}
\usepackage{lipsum}

\name{Gustavo Mezzetti}
\signature{Gustavo Mezzetti}
\address{
    Gustavo \textsc{Mezzetti}\\
        \protect\href
            {mailto:gustavo.mezzetti@istruzione.it}
            {\nolinkurl{gustavo.mezzetti@istruzione.it}}
}
\date{February~8, 2018}

\hypersetup{
    pdftitle        = {The C.D.P. Bundle version 0.36},
    pdfauthor       = {G. Mezzetti},
    pdfsubject      = {Instructions on how use the C.D.P. Bundle},
    pdfcreationdate = {D:20180208120000},
    pdfmoddate      = {D:20180208120000}
}

\pagestyle{headings}
\setcounter{tocdepth}{2}

\newcommand*{\pdfbslash}{}
{\catcode`\|=0 |catcode`|\=12 |gdef|pdfbslash{\\}}

\DeclareRobustCommand*{\packlass}[1]{{\normalfont\sffamily #1}}
\DeclareRobustCommand*{\opz}[1]{{\normalfont\ttfamily #1}}
\DeclareRobustCommand*{\env}[1]{%
    {\texorpdfstring{\normalfont\ttfamily}{}#1}%
}
\DeclareRobustCommand*{\sty}[1]{{\normalfont\ttfamily #1}}
\DeclareRobustCommand*{\filedir}[1]{{\normalfont\ttfamily #1}}
\DeclareRobustCommand*{\cntr}[1]{{\normalfont\ttfamily #1}}
\DeclareRobustCommand*{\command}[1]{%
    {\texorpdfstring{\normalfont\ttfamily \char\escapechar}{\pdfbslash}#1}%
}
\newcommand*{\meta}[1]{\(\langle\textit{#1}\rangle\)}
\newcommand*{\strongemph}[1]{\textbf{#1}}
\newcommand*{\zerolistvertspaces}{%
    \setlength{\parskip}{0pt}%
    \setlength{\topsep}{\parskip}%
    \setlength{\partopsep}{\parskip}%
}

\newcommand*{\lcdp}{\packlass{letteracdp}}
\newcommand*{\acdp}{\packlass{articoletteracdp}}
\newcommand*{\hyre}{\packlass{hyperref}}
\newcommand*{\cdpa}{\packlass{cdpaddon}}
\newcommand*{\adic}{\packlass{lettcdpadi}}
\newcommand*{\adip}{\packlass{adiseal}}
\newcommand*{\babel}{\packlass{babel}}
\newcommand*{\cdpbabel}{\packlass{cdpbabel}}
\newcommand*{\Bundle}{C.D.P. Bundle}
\newcommand*{\oclh}{\opz{customletterhead}}
\newcommand*{\eclh}{\env{customletterhead}}
\newcommand*{\eclf}{\env{customletterfoot}}

\makeatletter

\newcounter{listing}[letter]
\renewcommand*\thelisting{\@arabic\c@listing}
\@ifdefinable\fps@listing{\def\fps@listing{tbp}}
\@ifdefinable\ftype@listing{\def\ftype@listing{4}}
\@ifdefinable\ext@listing{\def\ext@listing{lol}}
\@ifdefinable\fnum@listing{\def\fnum@listing{\listingname~\thelisting}}
\newenvironment*{listing}
               {\@float{listing}}
               {\end@float}
\newenvironment*{listing*}
               {\@dblfloat{listing}}
               {\end@dblfloat}
\newcommand*\listoflistings{%
  \section*{\listlistingname \sectionmark\listlistingname}%
  \if@loX@in@toc@
    \addcontentsline{toc}{section}{\protect\listlistingname}%
  \fi
  \@starttoc{lol}%
}
\@ifdefinable\l@listing{\let\l@listing\l@figure}
\newcommand*\listlistingname{List of listings}
\newcommand*\listingname{Listing}
\@ifdefinable\toclevel@listing{\def\toclevel@listing{\toclevel@figure}}
% Note that we use "\def" here, not "\let".

\newcommand*\cleantop{%
    \dimen@ \baselineskip
    \advance \dimen@ -\topskip
    \prevdepth \dimen@
}
\newcommand*\cleanbot{%
    \dimen@ \baselineskip
    \advance \dimen@ -\topskip
    \advance \dimen@ -\prevdepth
    \vskip \dimen@
    \prevdepth \z@
}
\newcommand*\cleanbotp{%
    \vskip -\prevdepth
    \prevdepth \z@
}

\makeatother

\hfuzz = 0pt
\vfuzz = 0pt






\begin{document}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                              %
%       Letter no. 1           %
%                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{letterhead}[Whom it may concern]{
    To whom may be concerned\\
    with writing letters with \LaTeX\\
    (and want them to bear a letterhead
    of \emph{their own} choice!)
}[
    The \Bundle\ version 0.36.
]

\opening{Dear friends:}

This letter describes the new ``bells and whistles'' that have been made
available in version~0.36 of the \Bundle.  This version is just a provisional
patch applied on what essentially remains ``fossil'' code, in need of a thorough
redesign; nonetheless, it does provide some long-awaited features, most
prominently the ability to modify, with reasonable ease, the letterhead produced
by the \env{letterhead} environment.

The author wishes to thank Lorenzo Pantieri for having promoted, in his
excellent work
``\href{http://www.lorenzopantieri.net/LaTeX_files/Complementi.pdf}
{\emph{Complementi all'Arte di scrivere con \LaTeX}}'' (``Additions to The art
of writing with \LaTeX''), the use of the \lcdp\ document class, which is the
main component of the \Bundle.  This letter (indirectly) uses the \acdp\
document class.



\tableofcontents
\listoflistings



\setcounter{secnumdepth}{0}

\section{Introduction}

The \Bundle\ was essentially written between 1999 and 2000 (for an Italian
audience), and even at that time it contained code that was already deprecated;
even worse, its design was flawed since the beginning, because it had been
conceived for a specific and limited application (the letters of the C.D.P.,
exactly), and was adapted for more general use only as an afterthought.

A thorough redesign would therefore be needed; on the other hand, some users
have suggested, or asked for, improvements and additions, in particular for what
concerns the use of the bundle with other languages besides Italian (see
Section~\ref{S:Languages}), that can be implemented rather easily by means of
provisional patches.  I~have already been deferring the introduction of these
comparatively harmless enhancements for five years, waiting for the right moment
to undertake the task of redesigning the bundle from scratch, but now I~have
resolved to simply patch up the existing version.

The version herein presented, therefore, is far from being optimal: no serious
attempt has been made to remove ``fossil'' code, nor to bring it up to date with
modern \LaTeX\ usage.  I~have removed, however, the \adip\ package and the
\adic\ document class, of which, probably, nobody besides me even remembers the
purpose.

Though\marginpar{\hfill\strongemph{$*{*}*\;$WOW!!$\;*{*}*$}},
% Yes, I know, I should use \textasteriskcentered...
\strongemph{good news} are coming for all those users who asked for a means to
\strongemph{customize the letterhead} produced by the \Bundle: a reasonably
viable method for doing so has been provided at
last!~\facesmile\facesmile\facesmile\space The method requires the use of the
\cdpa\ package, passing in the new option \oclh.  You can specify the contents
of your custom head and foot by means of two new environments, called \eclh\ and
\eclf, which are similar, to a certain extent, to the \env{minipage}
environment.  This should give you the maximum freedom in designing the
letterhead (having recourse to \env{picture}s and images, if you wish to),
whilst adopting an interface you are surely well familiar with.  See
Section~\ref{S:Letterhead} for more information.

Another nifty feature is the ability to draw a thin rule to guide your hand in
signing your letters: you ask for this behavior by passing the new
\opz{signaturerule} option to the \lcdp\ document class.  See
Section~\ref{S:Options} for more information.

Finally, some minor corrections of an aesthetic nature have also been brought
in, which are concisely discussed in Section~\ref{S:Adjustments}.



\setcounter{secnumdepth}{2}

\section{My own letterhead, at last!}
\label{S:Letterhead}

One of the questions that users ask most frequenty about the \Bundle\ is perhaps
``How the hell can I~put \emph{my own} letterhead in the place of that silly
greenish thing?''; so, let's start with this one!

%%%%
\begin{listing}[p]
    \cleantop
\begin{verbatim}
\documentclass
    [twoside,boldsubject,italicsignature,shortindent,signaturerule]
    {letteracdp}[2018/02/08]
\usepackage[T1]{fontenc}
\usepackage[english]{cdpbabel}
\usepackage[customletterhead]{cdpaddon}[2018/02/08]
\usepackage{url,lipsum}

\address{
    Gustavo \textsc{Mezzetti}\\
    \protect\url{gustavo.mezzetti@istruzione.it}
}
\signature{Gustavo Mezzetti}
\date{February~8, 2018}
\place{Padova}



% Definition of your letterhead occurs here:

\begin{customletterhead}{\textwidth}
    \centering \Huge
    My Huge Centered Letterhead
\end{customletterhead}
\begin{customletterfoot}{\textwidth}
    \raggedleft \tiny
    \ruleacrossheadorfoot
    My (almost unreadable) small print\\
    flushed against the right margin.
\end{customletterfoot}



\begin{document}

\begin{foldedletterhead}[Whom it may concern]
    {To whom it may concern}
    [My own letterhead, at last!]

\makepresentation
\maketopdate\relax

\lipsum[1-2]

\makesignature

\end{foldedletterhead}

\end{document}
\end{verbatim}
    \caption{How to customize the letterhead}
    \label{lis:customletter}
    \cleanbotp
\end{listing}
%%%%



\paragraph{For the impatient}
\label{P:LetterHeadImpatient}

Listing~\ref{lis:customletter} explains what you have to do, in order to define
a simple customized letterhead, by means of a practical example.  It shows the
complete contents of the \LaTeX\ source file: by mimicking this code, you should
easily obtain what suits your needs.  Let us skim briefly through it.

First of all, note that we load the \cdpa\ package, with the \oclh\ option (as
well as a few other useful packages that, of course, have nothing to do with
letterheads).  Then come the usual declarations concerning the sender, the date,
etc.

Still in the preamble---as we will soon see, we could do this in other places
too, but also the preamble is absolutley OK\@---we start a \eclh\ environment.
This environment has the following synopsis:
%
\begin{flushleft}
    \verb|\begin{customletterhead}{|\meta{wdth}\verb|}|\quad
    \meta{text}\quad
    \verb|\end{customletterhead}|
\end{flushleft}
%
As you can see, it resembles a \env{minipage} environment, except that you
cannot specify the vertical alignment of the material contained therein (because
you don't need to: the mini page you are producing has not to be aligned with
any nearby constructs); and indeed, it creates a ``mini page'' of width
\meta{wdth} containing the \meta{text} you specify.  This \meta{text} should be
your letterhead: for example, the code shown here will produce a letterhead,
centered between the margins of the body of the main text, which reads ``My Huge
Centered Letterhead''---and actually looks like that!~\facesmile

Next, we do the same for the footer, using the \eclf\ environment, which is
syntactically identical to \eclh:
%
\begin{flushleft}
    \verb|\begin{customletterfoot}{|\meta{wdth}\verb|}|\quad
    \meta{text}\quad
    \verb|\end{customletterfoot}|
\end{flushleft}
%
By examining the code, you can easily tell that, this time, the footer will be
aligned against the right margin (\verb|\raggedleft|) and set in \verb|\tiny|
type---which is what the text itself says, after all.  But what does the
\verb|\ruleacrossheadorfoot| command do?  Well, it simply draws a horizontal
rule, which\ldots\ yes, extends across the whole footer.  You could use one of
the standard commands for producing rules, here (\LaTeX's \verb|\rule|, plain
\TeX's \verb|\hrule|), but this one has been specifically crafted for use inside
the two abovementioned environments; it consumes no vertical space, and does not
alter the distance (\verb|\baselinekip|) between the baselines of adjacent lines
of text.  Moreover, it can take optional arguments to modify its appearance, as
we shall see \hyperref[P:FinePoints]{in a minute}.

You can try out this example by yourself (I~advise you to do so), but for your
convenience the output it typesets is reproduced in a separate letter that you
find enclosed with this one, just after it in this same file.  If you have a
look at the result, you will be glad to note that the thin sign that the
\env{foldedletterhead} environment is supposed to draw along the right edge of
the sheet, to mark the exact point where it should be folded, is drawn also when
the original letterhead is replaced by yours.  This is just fine (but see also
Paragraph~\ref{P:FinePoints}).



\paragraph{A deeper look}
\label{P:Deeper}

As you, certainly, have already guessed, the two environments introduced
\hyperref[P:LetterHeadImpatient]{above} simply save their contents into a box;
the \oclh\ option causes these two boxes to be used in place of the header and
the footer, respectively, that had been originally defined by the \lcdp\
document class.  More precisely, when the \oclh\ option is in force, a copy of
those boxes is centered, with first-order infinite glue, in the header (resp.,
in the footer) line, pretending that they have zero height and depth, with the
bottom (resp., top) margin of the box defined by \eclh\ (resp., \eclf) aligned
along the baseline of the header (resp., of the footer) line of the page.  Note
that the \cdpa\ package defines the \eclh\ and \eclf\ environments, and their
associated storage boxes, even if you do \emph{not} specify the \oclh\ option:
this option simply dictates whether or not those two boxes should be \emph{used}
for the letterhead.  This is good, since it means that the presence or absence
of the \oclh\ option will not affect the \emph{syntax} of your document, but
only the appearance of the typeset output, which is how options should behave.



\paragraph{The letterhead is defined locally}
\label{P:Local}

As we indicated in Paragraph~\ref{P:LetterHeadImpatient}, the output produced by
listing~\ref{lis:customletter} is shown in a separate letter enclosed after this
one; you may be wondering how I~managed to produce two (or, actually, several)
letters with different letterheads in a single \LaTeX\ run (yes, it \emph{was} a
single run).  Well, I~am the author of the package, and I~could have played some
nasty trick; but actually I~didn't need to, because the \eclh\ and \eclf\
environments save their contents in their associated storage boxes
\emph{locally}.  This means that if they are postioned \emph{within} the
environment that produces a certain letter (say, \emph{e.g.},
\env{foldedletterhead}), the header and the footer will be changed \emph{only}
for that letter; for subsequent ones, the former header and footer will be
reinstated.  Of course, the redefinitions must occur before the \verb|\opening|
command (or anything else that typesets text).

%%%%
\begin{listing}[tbp]
    \cleantop
\begin{verbatim}
\begin{foldedletterhead}[Someone Else]{
    To Someone Else\\
    Some other place\\
    Some other city
}[
    Another letterhead.
]

\begin{customletterhead}{\textwidth}
    \raggedright \Huge
    A different head
\end{customletterhead}
\begin{customletterfoot}{\textwidth}
    \centering
    \ruleacrossheadorfoot
    A different foot
\end{customletterfoot}

\opening{Dear Someone,}

\lipsum[1-2]

\closing{Best regards.}

\end{foldedletterhead}
\end{verbatim}
    \caption{How to customize the letterhead for a single letter}
    \label{lis:customletterlocal}
    \cleanbot
\end{listing}
%%%%

This point is further illustrated in listing~\ref{lis:customletterlocal}, which
shows how to customize the letterhead for just a single letter.  This code has
been copied and then pasted toward the end of this file, to show, in a third,
independent letter, the output it produces.  Actually, for this I~\emph{did}
have to play some tricks not included in the code of the listing, in order to
``decolor'' the thin sign that marks the point where the sheet is to be folded,
and to reset the value of the \verb|\longindentation| parameter; but both these
changes can be made ``locally'' too.  There is a slight complication deriving
from the fact that, in order for a change to \verb|\longindentation| to turn
effective in a given ``letter-making'' environment, the change must occur
\emph{outside} the ``letter-making'' environment itself: this forced me to
supply an additional level of grouping.



\paragraph{Your own classes for your own letterhead}
\label{P:Classes}

If you know \LaTeX\ well, there will probably be one last point that still
bothers you.  We said, in Paragraph~\ref{P:LetterHeadImpatient}, that the \eclh\
and \eclf\ environments can very well be embedded in the preamble, without
causing any trouble: how come the typesetting that occurs inside these
environments does not trigger the ``Missing \verb|\begin{document}|'' error?
The answer is simply that these two environments have been specifically made
exempt from this error, precisely in order to permit you to include them in the
preamble too; and this, in turn, has been done because the concept of
``preamble'' also covers the code included in custom classes that you write
yourself.

This means that you can write your own custom classes that produce your own
custom letterhead, which is nice.~\facesmile\space We use the plural, because
you will surely want to define customized versions of \emph{both} the \lcdp\
class \emph{and} the \acdp\ class; the best way to do so is to write three
distinct files, as we are now going to explain.

%%%%
\begin{listing}[p]
    \cleantop
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e} % LaTeX2e is required!
\ProvidesClass{myletter}
              [2018/02/08 v0.03 (development)]
\LoadClassWithOptions{letteracdp}[2018/02/08]
\input{mylogo.def}
\endinput
\end{verbatim}
    \caption{Contents of the\/ \filedir{myletter.cls} file}
    \label{lis:myletter}
\end{listing}
%%%%

%%%%
\begin{listing}[p]
\begin{verbatim}
\NeedsTeXFormat{LaTeX2e} % LaTeX2e is required!
\ProvidesClass{myarticletter}
              [2018/02/08 v0.03 (development)]
\LoadClassWithOptions{articoletteracdp}[2018/02/08]
\input{mylogo.def}
\endinput
\end{verbatim}
    \caption{Contents of the\/ \filedir{myarticletter.cls} file}
    \label{lis:myarticletter}
\end{listing}
%%%%

%%%%
\begin{listing}[p]
    \cleantop
\begin{verbatim}
\ProvidesFile{mylogo.def}[2018/02/08 v0.03 (development)]

\RequirePackage[customletterhead]{cdpaddon}[2018/02/08]

\begin{customletterhead}{\textwidth}
    \centering \Huge
    My Huge Centered Letterhead
\end{customletterhead}
\begin{customletterfoot}{\textwidth}
    \raggedleft \tiny
    \ruleacrossheadorfoot
    My (almost unreadable) small print\\
    flushed against the right margin.
\end{customletterfoot}

\endinput
\end{verbatim}
    \caption{Contents of the\/ \filedir{mylogo.def} file}
    \label{lis:mylogo}
    \cleanbotp
\end{listing}
%%%%

So, let us suppose that you want to define two custom classes, named
\packlass{myletter} and \packlass{myarticletter}, respectively, that both
produce the same letterhead as the one we saw in listing~\ref{lis:customletter}.
For this, you write three files called \filedir{myletter.cls},
\filedir{myarticletter.cls}, and \filedir{mylogo.def}, whose contents are
reproduced in listings \ref{lis:myletter}, \ref{lis:myarticletter},
and~\ref{lis:mylogo}, respectively.  As you can see, the purpose of
\filedir{myletter.cls}\slash\filedir{myarticletter.cls} is just to supply ``glue
code'' toward (the \lcdp\slash\acdp\ classes and) the \filedir{mylogo.def} file,
which is the single place where the redefinition of the letterhead occurs.

%%%%
\begin{listing}[tbp]
    \cleantop
\begin{verbatim}
\ProvidesFile{mylogo.def}[2018/02/08 v0.03 (development)]

\RequirePackage[customletterhead]{cdpaddon}[2018/02/08]
\RequirePackage{color}

\DeclareFontFamily{T1}{my@calli}{}
\DeclareFontShape{T1}{my@calli}{m}{n}{<->s*[1.44]callig15}{}

\definecolor{my@lh@color}{rgb}{0,.4,.4}

\begin{customletterhead}{\textwidth}
    \color{my@lh@color}
    \fontsize{17}{21}\usefont{T1}{my@calli}{m}{n}
    \leftline{%
        \setlength{\unitlength}{1cm}%
        \begin{picture}(0,0) % you can use \includegraphics instead
            \put(-2,0){\framebox(1.8,1.2){%
                \normalsize\ttfamily My Logo%
            }}
        \end{picture}%
        My Company'\,s Letterhead\enspace
        \hrulefill\hspace{-2cm}%
    }
\end{customletterhead}

\settowidth{\longindentation}{%
    \fontsize{17}{21}\usefont{T1}{my@calli}{m}{n}%
    My Company'\,s Letterhead\enspace
}

\begin{customletterfoot}{\textwidth}
    \color{my@lh@color}
    \fontsize{5}{6}\usefont{T1}{pplx}{m}{n}
    \raggedleft
    \ruleacrossheadorfoot[-2cm]
    My (almost unreadable) \textsc{small print},\\
    aligned along the \textit{right} edge\\
    of the main text.
\end{customletterfoot}

\renewcommand*{\foldingtagrule}{%
    \color{my@lh@color}\CDPFactoryFoldingTagRule
}

\endinput
\end{verbatim}
    \caption{Contents of a more elaborated\/ \filedir{mylogo.def} file}
    \label{lis:mylogo-more}
    \cleanbotp
\end{listing}
%%%%

Listing~\ref{lis:mylogo-more} shows a more elaborate example of a
\filedir{mylogo.def} file to go together with the same two class files shown in
listings~\ref{lis:myletter} and~\ref{lis:myarticletter}.  Here we have added a
touch of superior style not only by employing color and some fancy fonts, but
also by having recourse to the fine adjustments described in
\hyperref[P:FinePoints]{the next paragraph} (because of the fonts, this example
might not work on all \TeX\ installations).  The letterhead defined by this
example is exactly the same as the one this letter itself bears on its first
page.



\paragraph{Fine points of style}
\label{P:FinePoints}

The first fine point of style that should be noted in
listing~\ref{lis:mylogo-more} is that the \verb|\longindentation| rigid length
is set equal to the width of the writing of the letterhead (``My Company's
Letterhead'').  Since the ``letter-making'' environments indent the address of
the addressee precisely by the amount of \verb|\longindentation|, this will
cause such addresses to be neatly aligned with a visually relevant element of
the design of the letterhead (the rule on the right); you should do the same
with your own letterhead, if it contains a similarly relevant component.  If you
do not yourself assign it a value, \verb|\longindentation| is set to half the
value of \verb|\textwidth|.

The second fine point to note is that the sign that marks the fold is drawn in
the same color as the rest of the letterhead.  The \Bundle\ computes the
vertical position of this sign, but to actually draw it, it calls the
\verb|\foldingtagrule| command, which the end user can redefine.  This command
works similarly to \verb|\footnoterule|, and, like the latter, should take up no
vertical space.  Its ``factory'' definition is backed up in the
\verb|\CDPFactoryFoldingTagRule| command (which should \emph{never} be
redefined, of course); as you can see, in listing~\ref{lis:mylogo-more} we
redefine \verb|\foldingtagrule| to simply invoke the factory default after
setting the appropriate color.

The third, and last, point to note is that the \verb|\ruleacrossheadorfoot|
command can get an optional argument in which an inset from the text margins can
be specified; a \emph{negative} inset, like here, causes the rule to protrude
into the margins.  A second optional argument let you indicate different insets
for the left and the right margin, in this order.  Note that these arguments
\emph{must} contain \emph{rigid} lengths.



\section{Other languages besides Italian}
\label{S:Languages}

Like many other document classes and packages, the classes of the \Bundle\ mark
up some portions of the output they produce by adding certain descriptive
strings, that, by default, are written in Italian.  For example, when you have
requested the \sty{headings} page style, the name of the addressee, which is
printed atop pages, is preceded by the string ``\emph{A:}'' (=~``To:'');
similarly, when you issue the command \verb|\tableofcontents| in a documents
that adopts the \acdp\ document class, the table it produces is titled
``\emph{Sommario}'' (=~``Contents''); and so on.

When the \Bundle\ was used only by the members of the \emph{Coordinamento}, the
Italian defaults it provided for those captions were, of course, quite adequate;
as long as its use remained confined to the Italian \LaTeX\ community, they were
still acceptable; but now, questions about how to adapt the \Bundle\ to foreign
languages have begun to be asked in some Internet forums by users around the
world, pushing me to reconsider the matter.

Of course, the Italian captions are not (nor they have ever been) ``hard-wired''
in the code: they are defined by macros that follow the usual naming conventions
(\verb|\headtoname|, \verb|\contentsname|, and so on).  Thus, it's only a matter
of redefining these ``hooks'' to suit the target language.  However, it would be
desirable to have some standard definitions set for each language; but
unfortunately, this cannot be attained just by loading the \babel\ package, for
two reasons.  In the first place, there are some captions that are specific to
the \Bundle\ and are therefore not cared for by the \babel\ package: for
example, the (optional) subject of a letter is preceded by the expansion of
\verb|\subjectname| (which is ``\emph{Oggetto:}'' in Italian and should be
``Subject:'' in English), a hook the \babel\ package knows nothing about.
Secondarily, even for those hooks that are standard, sometimes the definition
provided by the \babel\ package seems (at least to me) not adequate for a
letter; in particular, alas, if you load \babel\ with the \opz{italian} option
(as you ordinarily do when you are writing in Italian), it actually
\emph{cancels} the definitions preset by the \Bundle, substituting for them
strings that I~deem more suitable for articles or books, for which they are
indeed intended, than for letters (for example, \( \verb|\contentsname| \to
\mbox{``\emph{Indice}''} \) in \babel, instead of \( \verb|\contentsname| \to
\mbox{``\emph{Sommario}''} \), as defined by the \Bundle; \( \verb|\refname| \to
\mbox{``\emph{Riferimenti bibliografici}''} \) in \babel, instead of \(
\verb|\refname| \to \mbox{``\emph{Testi citati}''} \), as I~prefer).

To supply a \emph{provisional} solution to this problem, a new component has
been added to the \Bundle: the \cdpbabel\ package.  The idea is that, when using
one of the document classes of the \Bundle, you load the \cdpbabel\ package
\emph{instead of} \babel, and let the former load the latter on your behalf; in
this way, you offer it a chance to augment, or amend, the definitions made by
\babel\ itself.  This solution might seem inelegant (and admittedly it is), but
the problem is more subtle than it may look at first sight, involving also
compatibility issues with existing documents, and I~need to further investigate
it.  It is hoped that a more satisfactory scheme will be found for future
releases.

In practice, all the \cdpbabel\ package has to do is (to load \babel\ and) to
issue an \verb|\addto{\captions|\meta{language}\verb|}{|\ldots\verb|}| command
(or better, one such command for each required \meta{language}), with ``\ldots''
replaced by the appropriate redefinitions; the list, and the details, of such
redefintions are of course dictated by \meta{language}, so \cdpbabel\ takes them
from what we will call a ``C.D.P. language definition file''.  This is a text
file that, by convention, must be named
\filedir{cdpnames}\meta{language}\filedir{.ldf}, where \meta{language} is the
name of the corresponding language option (for example,
%
\begin{verbatim}
    \usepackage[english,italian]{cdpbabel}
\end{verbatim}
%
invokes both \filedir{cdpnamesenglish.ldf} and \filedir{cdpnamesitalian.ldf}, in
this order), and which must adhere to the format shown in
listing~\ref{lis:cdpnames}.

%%%%
\begin{listing}[tbp]
    \cleantop
    \zerolistvertspaces
    \begin{flushleft}
        \verb|\ProvidesFile{cdpnames|\meta{language}\verb|.ldf}[|%
                \meta{date \& version}\verb|]|
    \end{flushleft}
\begin{verbatim}

\def\@cdpbabel@letter@names{%
\end{verbatim}
    \begin{flushleft}
        \verb|  \def\subjectname      {|\meta{Subject:}\verb|}%|\\
        \verb|  \def\registeredname   {|\meta{Registered}\verb|}%|\\
        \verb|  \def\registeredRRname {|\meta{Registered R.R.}\verb|}%|\\
        \verb|  \def\andccname        {|\meta{cc (in addresses)}\verb|}%|\\
        \verb|  \def\ccname           {|\meta{cc (at end of letters)}\verb|}%|\\
        \verb|  \def\enclname         {|\meta{Encl:}\verb|}%|\\
        \verb|  \def\PSname           {|\meta{P.S.:}\verb|}%|\\
        \verb|  \def\headtoname       {|\meta{To:}\verb|}%|\\
        \verb|  \def\lettername       {|\meta{Letter}\verb|}%|
    \end{flushleft}
\begin{verbatim}
  % More captions could be added in the future.
}
\def\@cdpbabel@artlet@names{%
\end{verbatim}
    \begin{flushleft}
        \verb|  \def\contentsname     {|\meta{Contents}\verb|}%|\\
        \verb|  \def\listfigurename   {|\meta{List of figures}\verb|}%|\\
        \verb|  \def\listtablename    {|\meta{List of tables}\verb|}%|\\
        \verb|  \def\refname          {|\meta{References}\verb|}%|\\
        \verb|  \def\indexname        {|\meta{Index}\verb|}%|\\
        \verb|  \def\figurename       {|\meta{Figure}\verb|}%|\\
        \verb|  \def\tablename        {|\meta{Table}\verb|}%|\\
    \end{flushleft}
\begin{verbatim}
  % More captions could be added in the future.
}

\endinput
\end{verbatim}
    \caption{Contents of a
        \filedir{cdpnames}\protect\meta{language}\filedir{.ldf} file}
    \label{lis:cdpnames}
    \cleanbot
\end{listing}
%%%%

As you can see, a ``C.D.P. language definition file'' must define two macros,
named \verb|\@cdpbabel@letter@names| and \verb|\@cdpbabel@artlet@names|,
respectively: in the first you put the redefinitions that should be added to
\verb|\captions|\meta{language} when only the \lcdp\ class has been loaded; in
the second you list the additional redefinitions that apply if the \acdp\ class
is loaded too; and that's all.  Listing~\ref{lis:cdpnames} details exactly what
hooks need to be redefined when switching to another language; in principle, you
must supply a suitable redefinition for each of them, but of course, when a hook
is already defined by the \babel\ package in a way that you think suits, you may
omit it from your list (or, perhaps better, comment it out).

At present, the \Bundle\ ships with \emph{just two} such definition files
included: they are \filedir{cdpnamesitalian.ldf}, for Italian, and
\filedir{cdpnamesenglish.ldf}, for English.  For all other languages, you'll
have to write and install appropriate files yourself.  Needless to say, you are
most welcome if, after doing so, you want to contribute your work for inclusion
in future releases of the \Bundle.  Look at these two provided files, and in
particular at \filedir{cdpnamesenglish.ldf}, for inspiration about the intended
meaning of the captions (which sould be quite obvious, however).



\section{The new \opz{signaturerule} option}
\label{S:Options}

Some users have asked for a means to add a thin rule in signatures, just above
the signer's name, to mark the place when the handwritten signature should be
put.  Although, in my opinion, such usage is highly questionable (only pupils in
primary school need rules to guide their writing!\@), nevertheless it has now
been supported.  You request this behavior by passing the new
\opz{signaturerule} option to the \lcdp\ document class.  Indeed, the decision
whether to draw the rule or not is a matter of style and, as such, should be
made, once for all, for the whole document.

Even if you do specify the \opz{signaturerule} option, the rule will \emph{not}
be drawn inside a \env{signatureenv*} environment, because this environment is
meant exactly to be used when you are not going to sign the letter by hand.
This applies also to the \mbox{$*$-form} of the \verb|\closing| and of the
\verb|\makesignature| commands, which are used for the same purpose and which
invoke, directly or indirectly, precisely the \env{signatureenv*} environment.

To produce the rule, the \lcdp\ class calls the \verb|\signaturerule| command,
which you can customize, if you want to, to suit your needs.  This command is
called in \LaTeX's ``LR~mode'' (or, to be more precise, in \TeX's ``restricted
horizontal mode''), and it should construct a horizontal box containing the
rule, aligned along the baseline of the box itself; for example,
%
\begin{verbatim}
    \renewcommand*{\signaturerule}{%
        \makebox[5cm]{\hrulefill}
    }
\end{verbatim}
%
could be a typical (re)definition.  The default definition of
\verb|\signaturerule| is actually like this one, except that it draws a thinner
rule, and that it allows you to specify the horizontal length of the rule
(\emph{i.e.}, its width).  Specifically, the \verb|\signaturerulewidth|
parameter, which is a rigid length, indicates the width of the rule produced by
the default definition of \verb|\signaturerule|.  Should you ever redefine the
latter, you should honor this parameter in your redefinition, \emph{e.g.},
%
\begin{verbatim}
    \renewcommand*{\signaturerule}{%
        \makebox[\signaturerulewidth]{\hrulefill}
    }
\end{verbatim}
%
But I~think you will hardly need this: most users will content themselves with
changing the width of the rule.

For completeness' sake, the \opz{nosignaturerule} option is defined too: it is
the default, and it does not draw the rule.



\section{Aesthetic adjustments}
\label{S:Adjustments}

The \verb|\cc| and \verb|\encl| command have been reimplemented in such a way to
include the ``correct'' interline glue above and below their output.  Remember
that the output produced by these command is kept on the same page as the
signature; this means, in particular, that the \verb|\encl| command should be
used only for very short lists of enclosures (one item or two).  For longer
lists, utilize the \env{enclosures} environment, which mildly encourages a page
break above itself.



\section{A sample letter}
\label{S:Sample}

Listing~\ref{lis:sample} shows a sample input file that illustrates the features
covered in this letter: it uses the \packlass{myletter} sample class defined in
Paragraph~\ref{P:Classes}, with the letterhead drawn by the ``more elaborate''
version of the \filedir{mylogo.def} file that is reproduced in
listing~\ref{lis:mylogo-more}, the \opz{signaturerule} option described in
Section~\ref{S:Options}, and the \verb|\encl| command touched upon in
Section~\ref{S:Adjustments}.  As before, the output produced by this example is
shown in a separate letter at the end of this file.

%%%%
\begin{listing}[tbp]
    \cleantop
\begin{verbatim}
\documentclass
    [twoside,boldsubject,italicsignature,shortindent,signaturerule]
    {myletter}
\usepackage[T1]{fontenc}
\usepackage[english]{cdpbabel}
\usepackage{url,lipsum}

\name{Michael Youngster Name}
\address{
    Mike Y. \textsc{Name}\\
    Sails Manager\\
    \protect\url{m.y.name@my.company.com}
}
\signature{Mike Y. Name\\Sails Manager}
\date{February~8, 2018}
\place{Mamina del Rey}

\hfuzz = 0pt
\vfuzz = 0pt



\begin{document}

\begin{foldedletterhead}[R.~J.~Drofnats]{
    Revinu~J. \textsc{Drofnats}\\
    Department of Farm Ecology\\
    University of St.\,Anford\\
    Haga Alto, CA~94321
}[
    Our new sails.
]

\opening{Dear affectionate customer:}

we are delighted to have the opportunity of presenting our new
collection of sails for the incoming yachting season\ldots

\lipsum[1-2]

\closing{Sincerely,}

\encl{2018 Catalogue\\Invitation card}

\end{foldedletterhead}

\end{document}
\end{verbatim}
    \caption{A sample input file that uses the new features}
    \label{lis:sample}
    \cleanbotp
\end{listing}
%%%%



\epilogue

That, more or less, is all we had to say about version~0.36 of the \Bundle.  For
further information, write to the author: his e-mail address is on the first
page.

\closing*{Best regards.}

\PS
Please note that \packlass{myletter} also used to be (a great many years ago)
the obsolete name of the \packlass{akletter} document class.  Instructing you to
create a custom class by that name shouldn't cause you any trouble in
2018~\facesmile, but I~want to inform you all the same of the potential name
conflict.

\end{letterhead}






%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                              %
%       Letter no. 2           %
%                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begingroup

\date{February~8, 2018}

\begin{customletterhead}{\textwidth}
    \centering \Huge
    My Huge Centered Letterhead
\end{customletterhead}
\begin{customletterfoot}{\textwidth}
    \raggedleft \tiny
    \ruleacrossheadorfoot
    My (almost unreadable) small print\\
    flushed against the right margin.
\end{customletterfoot}
\setlength\longindentation{.5\textwidth}
\let \foldingtagrule = \CDPFactoryFoldingTagRule

\begin{foldedletterhead}[Whom it may concern]
    {To whom it may concern}
    [My own letterhead, at last!]

\makepresentation
\maketopdate\relax

\lipsum[1-2]

\makesignature

\end{foldedletterhead}






%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                              %
%       Letter no. 3           %
%                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{foldedletterhead}[Someone Else]{
    To Someone Else\\
    Some other place\\
    Some other city
}[
    Another letterhead.
]

\begin{customletterhead}{\textwidth}
    \raggedright \Huge
    A different head
\end{customletterhead}
\begin{customletterfoot}{\textwidth}
    \centering
    \ruleacrossheadorfoot
    A different foot
\end{customletterfoot}

\opening{Dear Someone,}

\lipsum[1-2]

\closing{Best regards.}

\end{foldedletterhead}

\endgroup






%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                              %
%       Letter no. 3           %
%                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{foldedletterhead}[R.~J.~Drofnats]{
    Revinu~J. \textsc{Drofnats}\\
    Department of Farm Ecology\\
    University of St.\,Anford\\
    Haga Alto, CA~94321
}[
    Our new sails.
]

\name{Michael Youngster Name}
\address{
    Mike Y. \textsc{Name}\\
    Sails Manager\\
    \protect\url{m.y.name@my.company.com}
}
\signature{Mike Y. Name\\Sails Manager}
\date{February~8, 2018}
\place{Mamina del Rey}

\opening{Dear affectionate customer:}

we are delighted to have the opportunity of presenting our new collection of
sails for the incoming yachting season\ldots

\lipsum[1-2]

\closing{Sincerely,}

\encl{2018 Catalogue\\Invitation card}

\end{foldedletterhead}


\end{document}