\begin{filecontents*}[overwrite]{clettrine.bib}
@MISC{lettr,
TITLE = "Typesetting dropped capitals with \LaTeX{}",
AUTHOR = "Flipo, Daniel",
HOWPUBLISHED = "\url{https://www.ctan.org/pkg/lettrine}",
YEAR="2020",
}
@MISC{texse,
TITLE = "Adding a Letter to an Image in a Do-It-Yourself Lettrine",
AUTHOR = "mlchristians",
HOWPUBLISHED = "\url{https://tex.stackexchange.com/questions/611290/adding-a-letter-to-an-image-in-a-do-it-yourself-lettrine/611292\#611292}",
YEAR = "2021"
}
@MISC{acorn,
TITLE = "Acorn Initials",
AUTHOR = "{The \LaTeX{} Font Catalogue}",
HOWPUBLISHED = "\url{https://www.tug.org/FontCatalogue/acorn/}",
YEAR = "2018"
}
\end{filecontents*}
%\documentclass{ltugboat}
\documentclass{article}
\textwidth=3.5in
\input Acorn.fd
\newcommand*\initfamily{\usefont{U}{Acorn}{xl}{n}}
\usepackage{lettrine,xcolor,scalerel,stackengine}
\usepackage{mathrsfs,graphicx}
\usepackage[hyphens]{url}
\setlength{\textwidth}{3in}
% USER PARAMETERS:
% LETTRINE SUPPLIED
\setcounter{DefaultLines}{2}
\setlength{\DefaultFindent}{2pt}
\setlength{\DefaultNindent}{.7ex}
% \clettrine SPECIFIC
\newcommand\clfgcolor{white!85!orange}
\newcommand\clbgcolor{black!60!blue}
\newcommand\cloffset{12pt}
\newcommand\clsep{2pt}
\newcommand\clvshift{0pt}
\newif\ifclsidesep
\clsidesepfalse
\newcommand\clformat[1]{#1}
% END USER PARAMETERS
\newlength\clbls
\newlength\cldpst
\newcommand\clettrine[1][0]{%
\def\claddlines{#1}\clettrineaux}
\newcommand\clettrineaux[3][\clvshift]{%
\edef\cltmp{\the\fboxsep}%
\setlength\fboxsep{0pt}%
\ifclsidesep\def\clsidekern{\kern\clsep}%
\else\def\clsidekern{}\fi
\setlength\clbls{\the\baselineskip}%
\setlength\cldpst{\the\dp\strutbox}%
\lettrine
[lines=\the\numexpr\theDefaultLines
+\claddlines]%
{\clboxscale{#1}%
{\the\dimexpr\cloffset
+\value{DefaultLines}\clbls
+\claddlines\clbls
-\cldpst\relax}%
{\clformat{\clsidekern#2\clsidekern}}}%
{#3}%
\setlength\fboxsep{\cltmp}}
\newcommand\clboxscale[3]{\raisebox{#1}{%
\colorbox{\clbgcolor}{%
\addstackgap[\clsep]{\scaleto{%
\abovebaseline[0pt]{%
\textcolor{\clfgcolor}{#3}}}%
{\dimexpr#2-\clsep-#1}}}}}
% DID STUFF TO MAKE IT COMPILE
\newcommand\citeauthoryear[3]{\small #2, #3}
\newcommand\UseExtraLabel{}
\sloppy
% END "DID STUFF"
% DOCUMENT SHORTCUTS
\newcommand\Clettrine{\cmd{clettrine}}
\newcommand\cmd[1]{\texttt{\upshape\textbackslash #1}}
\begin{document}
\section*{\clettrine{C}{olorboxed} Versals for Use with Lettrine}
Steven B Segletes
\section*{Abstract}
The lettrine package\cite{lettr} provides the means to typeset
dropped capitals, also known as decorative initials or
``versals'' at the beginning of paragraphs.
Here, the lettrine package is adapted to provide a convenient
and consistent way to employ colorboxed letters (either
conventional letters or decorative initials).
\centerline{------}%\section{Background}
\clettrine{O}{n} \texttt{tex.stackexchange.com}\cite{texse}, a question
was asked about a ``do-it-yourself'' lettrine, in which
a letter could be inserted into a specified black box that
had been put in place by way of lettrine.
My answer to that question garnered the accepted answer and
received additional notice that culminated in this article, which
formalizes that answer for more general use.
%\section{The Approach}
\clettrine{T}{he} approach taken was to create
a macro that we here call \Clettrine{}.
The macro employs lettrine, but takes into account an
additional set of parameters defined
specifically for \Clettrine{} configuration.
While the approach may be generalized at some point to take
full advantage of lettrine options, this early implementation
instead assumes certain features of the versal; thus, the
normal lettrine optional key-word argument is \textit{not}
made available to the user of \Clettrine.
The \Clettrine{} command uses the same two mandatory
arguments that \cmd{lettrine} does.
In addition, \Clettrine{} has its own unique set of
\textit{optional} arguments that will be discussed
subsequently.
A good place to start might be to show the parameters that
are used to configure \Clettrine, as seen in
Figure~\ref{fg:cldims}.
Some of the parameters, those listed in red, are parameters
provided by the lettrine package.
The defaults for these may be changed by the user and
\Clettrine{} will make use of the revised defaults.
Other lettrine parameters not listed in the figure should
be left in their package-default state.
\begin{figure}[ht]
\hspace{-.15\linewidth}\includegraphics[width=1.15\linewidth]{clettrinedims}
\caption{Parameters employed by \Clettrine}
\label{fg:cldims}
\end{figure}
In addition to the lettrine parameters shown in red, there
are several parameters defined in Figure~\ref{fg:cldims}
that are shown in the color cyan.
These are definitions introduced by this implementation of
\Clettrine{} and are available for reconfiguration by the
user.
%\section{User Definable Parameters}
\clettrine{L}{et} us now discuss parameter definitions and
values.
The parameters used to define the typeset of the versal
``L'' at the start of this paragraph are given as follows:
{\footnotesize
\begin{verbatim}
% USER PARAMETERS:
% LETTRINE SUPPLIED
\setcounter{DefaultLines}{2}
\setlength{\DefaultFindent}{2pt}
\setlength{\DefaultNindent}{.7ex}
% \clettrine SPECIFIC
\newcommand\clfgcolor{white!85!orange}
\newcommand\clbgcolor{black!60!blue}
\newcommand\cloffset{12pt}
\newcommand\clsep{2pt}
\newcommand\clvshift{0pt}
\newif\ifclsidesep
\clsidesepfalse
\newcommand\clformat[1]{#1}
% END USER PARAMETERS
\end{verbatim}
\par}
To users of lettrine, the first three parameters should
be familiar: the number of text lines encompassed by
the versal (\texttt{DefaultLines}), the indent of the
first line following the versal (\cmd{DefaultFindent}),
and the indent of the next line(s) to the right of the
versal (\cmd{DefaultNindent}).
The next group of parameters are \Clettrine{} specific.
The foreground and background colors are defined as
\texttt{white!85!orange} (\cmd{clfgcolor}) and
\texttt{black!60!blue} (\cmd{clbgcolor}),
respectively.
The command \cmd{cloffset} is defined as 12pt.
This parameter is the vertical length that the colorboxed
versal extends above the \cmd{ht\textbackslash
strutbox} of the top line of the paragraph.
The next parameter, \cmd{clsep} might be used for
several reasons, but primarily to compensate for
vertical protrusion of glyphs outside of their
bounding box.
In the S'' of Figure~\ref{fg:cldims}, for example, we see horizontal lines labelledlettertop'' and letterbottom''. These denote the upper and lower extent of the bounding box for the Computer-ModernS'' glyph.
As can be seen, the glyph extends beyond the lines in what
is commonly known as protrusion''. Without the use of \cmd{clsep}, theS'' would extend
vertically beyond the top and bottom of the colorbox.
Note, importantly, that \cmd{clsep} is not defined in terms
of the original unscaled glyph, but in terms of the
versal-sized scaled glyph.
The next parameter, \cmd{clvshift}, denotes a vertical
shift of the letterbottom'' placement. When \cmd{clvshift} is set to 0pt, the letterbottom of the versal will be aligned with the baseline of text to its right. I personally find the value of 0pt to be aesthetically pleasing---however there are two reasons why one might consider changing the value: (1) if the \cmd{clsep} is so large as to interfere with the text below the versal, or (2) to specially adjust descended versals, such as the letterQ'', where the letterbottom does not coincide
with the glyph's baseline.
More will be said on this latter point subsequently.
The parameter \cmd{ifclsidesep} is a T/F if-parameter.
When false, the colorbox extends horizontally only as far
as the outer edge of the glyph's bounding box.
Sometimes, however, one might prefer that the colorbox
extend past the bounding box, for example, if the glyph
set experiences horizontal protrusion.
When \cmd{clsideseptrue}, the colorbox is likewise extended
horizontally on both sides, by the dimension \cmd{clsep}.
Another reason to set this condition true might be if
the glyph suffers no protrusions,
either horizontally or vertically, but the user desires
a uniform colorbox border around the glyph.
The final \Clettrine{} parameter is actually the command
used to typeset the versal, given as \cmd{clformat}.
This command takes an argument, namely, the letter that
is to be typeset.
The job of the command is to use the specified letter to
select the appropriate glyph.
To this point in the article, the glyph
selected by this command is merely the letter in the
currently active font.
However, if the user wishes the versal to be selected from
an alternate font family or even an alternate font, the
\cmd{clformat} should be redefined to make the conversion.
Examples of this conversion will be shown subsequently.
%\section{Syntax}
\clettrine{S}{yntax} for the \Clettrine{} command is
as follows:\[4pt]\bgroup\itshape
\verb|\clettrine[|extra-lines\verb|][|clvshift-value\verb|]%|\
\verb| {|versal\verb|}{|rest-of-versal-word\verb|}|
\[4pt]\egroup
The usage envisioned is that the optional argument(s) will
only be employed for versals that have descenders.
The use of these two options are sufficient to present the
descended versal in a manner that preserves the original
baseline relative to their undescended counterparts.
Consider that our default \Clettrine{} parameters to this
point (with zero \cmd{clvshift}) align the letterbottom
of the versal with the baseline of the 2nd line of
paragraph text.
Such is the case with the versal ``S'' that opens this
section.
Let us examine what happens with a descended letter, as
depicted in Figure~\ref{fg:descenders}.
\begin{figure}[ht]
\centering
\def\showbl{\makebox[0pt]{\color{cyan}\rule{60pt}{.5pt}}}
\begin{minipage}[t]{.31\linewidth}\raggedright
\clettrine{Q}{} without \showbl options. Q squeezed into 2-line
box.\ Option: N/A
\end{minipage}
\rule[-95pt]{1.5pt}{95pt}
\begin{minipage}[t]{.31\linewidth}\raggedright
\clettrine[1]{Q}{} with \showbl one line added. Q too large.\
Option: \texttt{[1]}
\end{minipage}
\rule[-95pt]{1.5pt}{95pt}
\begin{minipage}[t]{.31\linewidth}\raggedright
\clettrine[1][3.5pt]{Q}{} plus \showbl one line & vshift.
Base-\allowbreak line match!\ Options: \texttt{[1][3.5pt]}
\end{minipage}
\hfil(a)\hfil\hfil\hfil(b)\hfil\hfil\hfil(c)\hfil\hfil
\caption{Treatment of Descenders}
\label{fg:descenders}
\end{figure}
In Figure~\ref{fg:descenders}(a),
\verb|\clettrine{Q}{}| typesets the descending Q'' without any options. The effect is to squeeze the versal-Q into the same vertical space as allocated for letters likeS''.
Because Q descends, this makes the versal ``Q'' too small,
forcing the Q's baseline much higher.
In Figure~\ref{fg:descenders}(b),
\verb|\clettrine[1]{Q}{}| allocates an extra line for the
versal.
However, this is more space than needed, as we now see the
baseline of the ``Q'' sinks below the baseline of the
2nd text line.
In Figure~\ref{fg:descenders}(c),
\verb|\clettrine[1][3.5pt]{Q}{}| allocates an extra line
for the versal, but also shifts up the letterbottom by
3.5pt.
In so doing, the baseline of the versal-Q can be seen to
align with the baseline of the 2nd line of text, just
as occurs with non-descending letters.
Mission accomplished!
%\section{A Few Examples}
\renewcommand\clsep{3pt}
\renewcommand\cloffset{8pt}
\renewcommand\clbgcolor{green!50!black}
\renewcommand\clfgcolor{yellow!30}
\renewcommand\clformat[1]{$\mathcal{#1}$}
\clettrine{W}{hat} more can be shown about the capabilities
of \Clettrine?
A few examples could help elaborate.
The default versal style shown for the ``W'' has been changed
according to the following redefinitions:
{\footnotesize
\begin{verbatim}
\renewcommand\clsep{3pt}
\renewcommand\cloffset{8pt}
\renewcommand\clbgcolor{green!50!black}
\renewcommand\clfgcolor{yellow!30}
\renewcommand\clformat[1]{$\mathcal{#1}$}
\end{verbatim}
\par}
Here, in addition to changes in the foreground
and backgroup colors, the format was changed
to present the versal in the \cmd{mathcal}
font.
Because the \cmd{mathcal} font has larger protrusions,
the \cmd{clsep} was increased from 2pt to 3pt.
The \cmd{cloffset} beyond \cmd{ht}\cmd{strutbox} was
reduced from 12pt to 8pt.
%%%%
\setcounter{DefaultLines}{3}
\renewcommand\cloffset{0pt}
\renewcommand\clsep{2pt}
\renewcommand\clbgcolor{red!50!black}
\renewcommand\clformat[1]{$\mkern.5mu\mathscr{#1}$}
\vbox{%
\clettrine{R}{educing} the value of \cmd{cloffset} to
0pt, brings the versal ``R'' of this paragraph in line
with the top of the paragraph's strutbox.
To compensate, the number of default versal lines has been
increased to 3.
Revisions are as follows:}
{\footnotesize
\begin{verbatim}
\setcounter{DefaultLines}{3}
\renewcommand\cloffset{0pt}
\renewcommand\clsep{2pt}
\renewcommand\clbgcolor{red!50!black}
\renewcommand\clformat[1]{$\mkern.5mu\mathscr{#1}$}
\end{verbatim}
\par}
The font is changed to \cmd{mathscr}.
Unusually, the ``R'' has a leftward protrusion.
While \cmd{clsideseptrue} could be set to add 2pt
separation to the sides of the colorbox, instead,
we opt in the \cmd{clformat} to just add .5mu to the
left of the formatted glyphs, to counteract the protrusion.
\clsideseptrue
\renewcommand\clbgcolor{red!80!green}
\renewcommand\clformat[1]{\initfamily#1}
\renewcommand\clsep{3pt}
\clettrine{N}{othing} in the \Clettrine{} approach
prevents the use of actual initial fonts for the versals,
such as the Acorn\allowbreak\cite{acorn}
decorative-initial ``N'' used in this paragraph.
Because decorative-initial fonts are generally void of
protrusions, they make a great candidate for
\cmd{clsideseptrue}, so that a uniform border of
\cmd{clsep} may be added to all 4 sides of the glyph,
as shown in the following configuration for this
paragraph:
{\footnotesize
\begin{verbatim}
% PREAMBLE SETUP
\input Acorn.fd
\newcommand*\initfamily{\usefont{U}{Acorn}{xl}{n}}
% RECONFIGURATION
\clsideseptrue
\renewcommand\clbgcolor{red!80!green}
\renewcommand\clformat[1]{\initfamily#1}
\renewcommand\clsep{3pt}
\end{verbatim}
\par}
%\section{The Code}
% LETTRINE SUPPLIED
\setcounter{DefaultLines}{2}
% \clettrine SPECIFIC
\renewcommand\clfgcolor{white!85!orange}
\renewcommand\clbgcolor{black!60!blue}
\renewcommand\cloffset{12pt}
\renewcommand\clsep{2pt}
\clsidesepfalse
\renewcommand\clformat[1]{#1}
% END USER PARAMETERS
\clettrine{C}{ode} listing is the last
topic to cover in this article.
In addition to lettrine, the other packages
required of \Clettrine{} include xcolor,
stackengine, and scalerel.
The stackengine package is used to add
the \cmd{clsep} buffer above and below the
versal glyph and to shift the scaled glyph
relative to the baseline.
The scalerel package is used to scale the versal
glyph to the prescribed size, before placing it
in a colorbox.
The relevant code is given below:
{\footnotesize
\begin{verbatim}
\newlength\clbls
\newlength\cldpst
\newcommand\clettrine[1][0]{%
\def\claddlines{#1}\clettrineaux}
\newcommand\clettrineaux[3][\clvshift]{%
\edef\cltmp{\the\fboxsep}%
\setlength\fboxsep{0pt}%
\ifclsidesep\def\clsidekern{\kern\clsep}%
\else\def\clsidekern{}\fi
\setlength\clbls{\the\baselineskip}%
\setlength\cldpst{\the\dp\strutbox}%
\lettrine
[lines=\the\numexpr\theDefaultLines-
+\claddlines]%
{\clboxscale{#1}%
{\the\dimexpr\cloffset
+\value{DefaultLines}\clbls
+\claddlines\clbls
-\cldpst\relax}%
{\clformat{\clsidekern#2\clsidekern}}}%
{#3}%
\setlength\fboxsep{\cltmp}}
\newcommand\clboxscale[3]{\raisebox{#1}{%
\colorbox{\clbgcolor}{%
\addstackgap[\clsep]{\scaleto{%
\abovebaseline[0pt]{%
\textcolor{\clfgcolor}{#3}}}%
{\dimexpr#2-\clsep-#1}}}}}
\end{verbatim}
\par}
Much of the code is spent saving and restoring
lengths as well as other parameters.
The real meat of the \Clettrine{} transformation
occurs in the first mandatory argument to
\cmd{lettrine}, as called in the \cmd{clettrineaux}
macro.
There, the \cmd{clboxscale} macro is called and
provided the required measurements needed to
scale the glyph into an appropriately sized
colorbox.
In the end, we find that for a relatively small
overhead of code, the capability of lettrine
can be extended to provide colorboxed versals that
are highly configurable and set in a consistent
manner.
{\raggedright
\bibliographystyle{ltugbib.bst}
\bibliography{clettrine}}
\end{document}
luatex85. – DDS Feb 03 '22 at 23:08luatex85is rarely needed now; it was a temporary fix. – Thérèse Feb 03 '22 at 23:16