summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/cdpbundl/cdp-ver-0-36.tex
blob: 87e3cc0b7fb1058f12647f329af95c055d177a3a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
\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}