summaryrefslogtreecommitdiff
path: root/obsolete/macros/context/contrib/context-lettrine/doc/context/third/lettrine/lettrine-doc.tex
blob: 541f2bf3e494df0307631508bc6d7452d86b69ca (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
\setupoutput[pdftex]
\loadmapfile[texnansi-public-lm]
\loadmapfile[cork-public-lm]
\loadmapfile[original-ams-euler]
\loadmapfile[hoekwater]

%\enablemode[onecolumn]
%\enablemode[realfonts]
\usemodule[map-se]
\usemodule[lettri]
\setupcolors[state=start,conversion=yes]
\usemodule[set-11]
\hbadness=10000
\setuplettrine[T][Findent=0.2em,Nindent=0.2em,Oversize=.05,Hang=.15]

\startbuffer[setuplettrine]
<cd:command name="setuplettrine">
  <cd:sequence>
    <cd:string value="setuplettrine"/>
  </cd:sequence>
  <cd:arguments>
    <cd:keywords optional="yes">
      <cd:constant type="cd:text"/>
    </cd:keywords>
    <cd:assignments list="yes">
      <cd:parameter name="Lines">
        <cd:constant type="cd:number"/>
      </cd:parameter>
      <cd:parameter name="Hang">
        <cd:constant type="cd:text"/>
      </cd:parameter>
      <cd:parameter name="Oversize">
        <cd:constant type="cd:text"/>
      </cd:parameter>
      <cd:parameter name="Raise">
        <cd:constant type="cd:text"/>
      </cd:parameter>
      <cd:parameter name="Findent">
        <cd:constant type="cd:dimension"/>
      </cd:parameter>
      <cd:parameter name="Nindent">
        <cd:constant type="cd:dimension"/>
      </cd:parameter>
      <cd:parameter name="Slope">
        <cd:constant type="cd:dimension"/>
      </cd:parameter>
      <cd:parameter name="Ante">
        <cd:constant type="cd:text"/>
      </cd:parameter>
      <cd:parameter name="FontHook">
        <cd:constant type="cd:command"/>
      </cd:parameter>
      <cd:parameter name="TextFont">
        <cd:constant type="cd:command"/>
      </cd:parameter>
      <cd:parameter name="Image">
        <cd:constant type="yes"/>
        <cd:constant type="no" default="yes"/>
      </cd:parameter>
    </cd:assignments>
  </cd:arguments>
</cd:command>
\stopbuffer

\startbuffer[lettrine]
<cd:command name="lettrine" file="core-mis.tex">
  <cd:sequence>
    <cd:string value="lettrine"/>
  </cd:sequence>
  <cd:arguments>
    <cd:assignments list="yes" optional="yes">
      <cd:inherit name="setuplettrine"/>
    </cd:assignments>
    <cd:content/>
    <cd:content/>
  </cd:arguments>
</cd:command>
\stopbuffer

\def\emph#1{#1}

\starttext
\startArticle[%
        Author=Taco Hoekwater,
	Email=taco@elvenkind.com,
        Title=Lettrines for Con\TeX{}t,
        Page=26,
        Category=context]

\startKeywords
lettrines, module, initials, dropped capitals, Con\TeX{}t
\stopKeywords

\startAbstract
The \ConTeXt\ module \type{lettri} is port of the \LaTeX\ package
\type{lettrine} by Daniel Flipo that provides a way to typeset dropped 
capitals at the beginning of paragraphs.
\stopAbstract

\section{Introduction}

Daniel Flipo's \LaTeX\ package ``lettrine.sty'' provides the command
\type{\lettrine} for the creation of dropped capitals at the beginning
of a paragraph. Various parameters are provided to control the size
and layout of the dropped capital, using a key||value system to
specify the options.

Last februari, Gerben Wierda asked on the \ConTeXt\ mailing list if
``Would someone be able to take lettrine.sty as an example and produce
a version that works with \ConTeXt\ (and plain \TeX)?''. I never
considered making a version for plain \TeX, but a \ConTeXt\ version
was doable. So I've created the `lettri' module, for use in a
\type{\usemodule} command.

\section{Commands}

The module defines two user||level commands, one for setup and one for
actual use. Most of the parameter names are a bit different from their
\LaTeX{} counterparts. There are two reasons for this, both a side||effect 
of the implementation in \ConTeXt.
\startitemize
\item The first reason is my laziness, I did not want to create lots of 
new constants for internationalization of the interface, so I just used 
an initial uppercase character. This makes the keywords impervious to
differences in the \ConTeXt\ language interfaces.
\item The second reason is that some parameter names seemed a bit odd, 
probably because of name\-space conflicts within \LaTeX, and I sanitized
those names where that was possible without confusing the users.
\stopitemize
\noindent
So, for example, the \LaTeX\ parameter keyword \type{lhang} became the
\ConTeXt\ parameter \type{Hang}.

\subsection{Usage command: \type{\lettrine}}

The command \type{\lettrine} uses an optional parameter for 
settings, and two required arguments that are texts to be typeset.

\processXMLbuffer[lettrine]

\lettrine{T}{he two} typeset arguments are the dropped capital and 
the run||in text following it; the \TeX\ source of this paragraph 
started with ``\type{\lettrine{T}{he two} typeset}''. The optional
parameter is explained below.


\subsection{Setup command: \type{\setuplettrine}}

\processXMLbuffer[setuplettrine]

\startitemize
\item \type{Lines} controls how many lines the dropped capital 
   will occupy (the default value is~2);
\item \type{Hang} sets how much of the dropped capital's width 
   should hang into the margin (the default is 0, values should be
   between 0 and 1);
\item \type{Oversize} enlarges or decreases the dropped capital's height: 
   with \type{Oversize=0.1}. its height is enlarged by 10\% so that
   it raises above the top paragraph's line (default=0, values should 
   be between $-$1 and 1);
\item \type{Raise} does not affect the dropped  capital's height, but 
   moves it up (if positive) or down (if negative); useful with capitals 
   like \type{J} or \type{Q} which have a positive depth (default=0,
   values should be between $-$1 and 1);
\item \type{Findent} (positive or negative) controls the horizontal gap 
   between the dropped capital and the indented block of text (default=0pt);
\item \type{Nindent} shifts the indented lines, starting from the second line,
   horizontally by the specified amount (default=0.5em);
\item \type{Slope} can be used with dropped
   capitals like \type{A} or \type{V} to add an extra shift
   (positive or  negative) to the indentation of each line
   starting from the third one (no effect if \type{Lines=2}, default=0pt);
\item \type{Ante} can be used to typeset something
   \emph{before} the dropped capital (typical use is for French 
   guillemets starting the paragraph).
\item \type{Image} will force  \type{\lettrine} 
  to replace the letter normally used as dropped capital by an image.
  \type{\lettrine[Image=yes]{A}{n exemple}} will load \type{A.eps} or
  \type{A.pdf} instead of letter~A.
\item \type{FontHook} can be used to change the font and/or color of 
   the dropped capital (default: empty)
\item \type{TextFont} can be used to change the font and/or color of 
   the run||in text  (default: \type{\sc})
\stopitemize

\noindent
The first, optional argument to the \type{\setuplettrine} command
allows you to create presets: The settings that follow will apply only
if the first text argument of \type{\lettrine} (see below) matches
this string exactly. I~have used this command at the top of this
article:
\starttyping
\setuplettrine[T][Findent=0.2em,Nindent=0.2em,
                 Oversize=.05,Hang=.15]]
\stoptyping
because otherwise the example on the previous page would not have 
been as nice as it is.

\section{Examples}
The following examples were all adapted from the file \type{demo.tex}
that is part of Daniel Flipo's original distribution. I've been forced 
to make some changes here and there because the font for the Maps is
quite different from the font in the original examples, but I~have not
made changes to the original french text.

\subsection{Standard options (using 2 lines)}

\starttyping
\lettrine{E}{n} plein marais...
\stoptyping

\begingroup
\language[fr]
\lettrine{E}{n} plein marais de la Souteyranne, \`a quelques kilom\`etres
au nord d'Aigues-Mortes, se trouve la Tour Carbonni\`ere.  Construite
au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| dont il ne reste que quelques
vestiges.
\par
\endgroup

\subsection{Lettrine on a single line}

\starttyping
\lettrine[Lines=1]{E}{n} plein marais...
\stoptyping

\begingroup
\language[fr]
\lettrine[Lines=1]{E}{n} plein marais de la Souteyranne,
\`a quelques kilom\`etres au nord d'Aigues-Mortes, se trouve 
la Tour Carbonni\`ere.
\par
\endgroup

\subsection{Lettrine on a three lines}
\starttyping
\lettrine[Lines=3]{E}{n} plein marais...
\stoptyping

\begingroup
\language[fr]
\lettrine[Lines=3]{E}{n} plein marais de la Souteyranne, 
\`a quelques kilom\`etres au nord d'Aigues-Mortes, 
se trouve la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des\break |<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.
\par
\endgroup

\subsection{Lettrine in the margin}
\starttyping
\lettrine[Hang=1, Nindent=0pt, Lines=3]
         {J}{ustement},...
\stoptyping

\setupnarrower[middle=6pt]
\begingroup
\language[fr]
\startnarrower
\lettrine[Hang=1, Nindent=0pt, Lines=3]{J}{ustement}, 
\`a quelques kilom\`etres au nord d'Aigues-Mortes, 
se trouve la Tour Carbonni\`ere.  Construite au XIII\high{e}~si\`ecle,
elle contr\^olait l'unique voie d'acc\`es terrestre de la ville
fortifi\'ee, celle qui menait \`a Psalmody, l'une des
|<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.  L'abbaye \'etait
ravitaill\'ee ---~dit-on ~--- par un souterrain qui la reliait au
ch\^ateau de Treillan.
\stopnarrower
\par
\endgroup


\subsection{Lettrine oversised, and partly in the margin}
\starttyping
\lettrine[Lines=3,Hang=0.2,Oversize=0.25]
         {E}{n} ...
\stoptyping

\begingroup
\language[fr]
\lettrine[Lines=3, Hang=0.2, Oversize=0.25]{E}{n} 
plein marais de la Souteyranne,
\`a quelques kilom\`etres au nord d'Aigues-Mortes la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| \dots
% dont il ne reste que des vestiges.
\par
\endgroup

\subsection{A guillemet in front of the lettrine}
\starttyping
\lettrine[Ante={<<}]{E}{n} plein marais ...
\stoptyping

\begingroup
\language[fr]
\lettrine[Ante={<<}]{E}{n} plein marais de la Souteyranne,
\`a quelques kilom\`etres au nord d'Aigues-Mortes, se trouve 
la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des\break |<<|abbayes de sel|>>| \dots
% dont il ne reste que des vestiges.
\par
\endgroup

\blank
The following four lettrines have all been typeset after changing the
default settings with the following command:

\starttyping
\setuplettrine[Lines=4,FontHook={\color[gray]}]
\stoptyping

\setuplettrine[Lines=4,FontHook={\color[gray]}]

\subsection{A somewhat smaller and slightly raised lettrine}

\starttyping
\lettrine[Oversize=-0.15, Raise=0.15]
         {Q} {u'en plein marais} ...
\stoptyping

\begingroup
\language[fr]
\lettrine[Oversize=-0.15, Raise=0.15]{Q}{u'en plein marais}
 de la Souteyranne, \`a quel\-ques kilom\`etres au nord d'Aigues-Mortes, 
se trouve la Tour Carbonni\`ere, surprend les visiteurs.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.
L'abbaye \'etait ravitaill\'ee par un souterrain qui
la reliait au ch\^ateau de Treillan.
\par
\endgroup

\subsection{The same lettrine, without corrections}

\starttyping
\lettrine{Q}{u'en plein marais} de ...
\stoptyping

\begingroup
\language[fr]
\lettrine{Q}{u'en plein marais} de la Souteyranne,
\`a quelques kilom\`etres au nord d'Aigues-\break Mortes, 
se trouve la Tour Carbonni\`ere, surprend les visiteurs.
Construite au XIII\high{e}\break si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.
L'abbaye \'etait ravitaill\'ee par un souterrain qui
la reliait au ch\^ateau de Treillan.
\par
\endgroup

\subsection{Using the Slope option for the following lines}
\starttyping
\lettrine[Slope=0.4em,Findent=-0.5em,
          Nindent=0.4em]
         {\`A}{quelques kilom\`etres}...
\stoptyping

\kern -12pt

\begingroup
\language[fr]
\lettrine[Slope=0.4em, Findent=-0.5em, Nindent=0.4em]{\`A} {quelques 
kilom\`etres} au nord d'Aigues-Mortes, se trouve  la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.
L'abbaye \'etait ravitaill\'ee ---~dit-on~--- par un souterrain qui
la reliait au ch\^ateau de Treillan.
\par
\endgroup

\kern 24pt
\subsection{Using the Slope option for the opposite effect} 

Also note the move into the margin

\starttyping
\lettrine[Slope=-0.5em,Hang=0.5,Findent=0.2em]
         {V}{oici} \`a...
\stoptyping

\begingroup
\language[fr]
\startnarrower
\lettrine[Slope=-0.5em, Hang=0.5, Findent=0.2em]{V}{oici}
\`a quelques kilom\`etres au nord d'Aigues-Mortes la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie
d'acc\`es terrestre de la ville fortifi\'ee, celle qui menait \`a
Psalmody, l'une des |<<|abbayes de sel|>>| dont il ne reste que
quelques vestiges.  L'abbaye \'etait ravitaill\'ee ---~dit-on~--- par
un souterrain qui la reliait au ch\^ateau de Treillan.
\stopnarrower
\par
\endgroup

\subsection{Using a different font by using the FontHook}

\starttyping
\def\myhook
  {\definefontsynonym[LettrineFont][SansBold]}
\lettrine[FontHook={\myhook}, 
          Hang=.2, Findent=.3em] 
         {E}{n} plein marais...
\stoptyping

\def\myhook
  {\definefontsynonym[LettrineFont][SansBold]}

\begingroup
\language[fr]
\lettrine[FontHook={\myhook},Hang=.2,Findent=.3em]{E}{n} plein 
marais de la Souteyranne, \`a quelques
kilom\`etres au nord d'Aigues-Mortes, se trouve la Tour Carbonni\`ere.
Construite au XIII\high{e}~si\`ecle, elle contr\^olait l'unique voie d'acc\`es
terrestre de la ville fortifi\'ee, celle qui menait \`a Psalmody,
l'une des |<<|abbayes de sel|>>| dont il ne reste que quelques vestiges.
L'abbaye \'etait ravitaill\'ee par un souterrain qui
la reliait au ch\^ateau de Treillan.
\par
\endgroup

\subsection{Use of an image instead of an actual letter}

\setuplettrine[FontHook={}]

\starttyping
\lettrine[Image=yes,Hang=.1, Oversize=.25, 
          Findent=0.1em, Raise=-.1]
          {W} {er} reitet ...
\stoptyping

{\switchtobodyfont[eul]
\lettrine[Image=yes,Hang=.1, Oversize=.25, Findent=0.1em, Raise=-.1]
{W}{er} reitet so sp\"at durch Nacht und Wind?\crlf
Es ist der Vater mit seinem Kind;\crlf
Er hat den Knaben wohl in dem Arm,\crlf
Er fa{\SS}t ihn sicher, er h\"alt ihn warm.
\par}%

\section{Availability}

The module can be downloaded from the new \ConTeXt\ module repository,
at\crlf
\hyphenatedurl{http://modules.contextgarden.net}.

\blank
I have released this module into the public domain.

\stopArticle
\stoptext