summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/lettrine/lettrine.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/lettrine/lettrine.dtx')
-rw-r--r--macros/latex/contrib/lettrine/lettrine.dtx187
1 files changed, 101 insertions, 86 deletions
diff --git a/macros/latex/contrib/lettrine/lettrine.dtx b/macros/latex/contrib/lettrine/lettrine.dtx
index c357e97aba..65f301e6af 100644
--- a/macros/latex/contrib/lettrine/lettrine.dtx
+++ b/macros/latex/contrib/lettrine/lettrine.dtx
@@ -1,8 +1,6 @@
-% \CheckSum{650}
-%
% \iffalse meta-comment
%
-% Copyright © 1999-2020 Daniel Flipo.
+% Copyright © 1999-2022 Daniel Flipo.
%
% This program can be distributed and/or modified under the terms
% of the LaTeX Project Public License either version 1.3c of this
@@ -26,7 +24,7 @@
\ProvidesFile{lettrine.dtx}
%</dtx>
%<*!cfg>
- [2020-03-14 v2.23 (Daniel Flipo)]
+ [2022-09-25 v2.30 (Daniel Flipo)]
%</!cfg>
%
% Lettrine package for LaTeX version 2e
@@ -36,6 +34,8 @@
% Please report errors to: daniel (dot) flipo (at) free (dot) fr
%
%<*driver>
+\RequirePackage{pdfmanagement-testphase}
+\DeclareDocumentMetadata{pdfstandard=A-2b, lang=en-US}
\documentclass[a4paper]{ltxdoc}
\usepackage[dvipsnames]{xcolor}
\usepackage{unicode-math}
@@ -48,7 +48,10 @@
\usepackage[expansion=true,protrusion=true]{microtype}
\usepackage{url}
\usepackage[numbered]{hypdoc}
-\hypersetup{colorlinks,urlcolor=blue,unicode}
+\hypersetup{pdftitle={Lettrine User’s Guide},
+ pdfauthor={Daniel FLIPO},
+ colorlinks
+ }
\usepackage{lettrine}
\usepackage{tikz}
\usetikzlibrary{shapes.arrows}
@@ -92,15 +95,16 @@
%
% \changes{v2.23}{2020/03/14}{Documentation cleanup.}
%
-% Adding |\usepackage{lettrine}| in the preamble of a document
+% Adding |\usepackage{lettrine}| in the preamble of a document
% defines the command |\lettrine|, the simplest use of which is
% |\lettrine{|\meta{letter}|}{|\meta{text}|}|.
% It produces a dropped capital \meta{letter} (2 lines high),
% followed by \meta{text} typeset in small caps, and the rest
% of the paragraph is wrapped around the dropped capital.
%
-% Various parameters are provided to control the size and layout
-% of the dropped capital and match the requirements described
+% The |\lettrine[|\meta{options}|]{|\meta{letter}|}{|\meta{text}|}|
+% command accepts various optional arguments to control the size and
+% layout of the dropped capital and match the requirements described
% in the books
% \begin{itemize}
% \item ``Lexique des règles typographiques en usage à
@@ -149,7 +153,7 @@
% \changes{v1.6}{2004/05/22}{Add a flag to switch to
% images in eps or pdf format. Suggested by Bill Jetzer.}
%
-% \item \lopt{image=true} will force |\lettrine| to replace the letter
+% \item \lopt{image[=true]} will force |\lettrine| to replace the letter
% normally used as dropped capital by an image in eps format (latex)
% or in pdf, jpg, etc.\ format (pdflatex, xelatex, lualatex);
% this requires the |graphicx| package to be loaded in the preamble.
@@ -163,13 +167,13 @@
% \changes{v1.8}{2015/02/06}{Added two keyval options:
% `grid’ (true/false) and `novskip’ to override \cs{DiscardVskip}.}
%
-% \item \lopt{grid=true} will force the vertical skip added above the
+% \item \lopt{grid[=true]} will force the vertical skip added above the
% paragraph starting with |\lettrine| to be rounded up to an integer
% number of |\baselineskip|. This option is meant for grid
% typesetting.
% \item \lopt{novskip=}\meta{dimen} overrides |\DiscardVskip|
% (default=0.2pt). In some cases (see options \lopt{lraise},
-% \lopt{loversize} or accentuated dropped capitals,\dots) the top of
+% \lopt{loversize} or accentuated dropped capitals,…) the top of
% the dropped capital will raise above the top of following text
% (usually in small caps), this will trigger a corresponding vertical
% skip above the paragraph starting with |\lettrine|, \emph{only if}
@@ -180,7 +184,7 @@
% \changes{v1.9}{2015/08/31}{New keyval option: `realheight’
% (true/false) and new global flag \cs{ifLettrineRealHeight}.}
%
-% \item \lopt{realheight=true} will compute the default height of the
+% \item \lopt{realheight[=true]} will compute the default height of the
% initial so that the top of it is exactly aligned with the top of
% the text entered as second mandatory argument of |\lettrine|
% taking possible accents into account. Otherwise, the default
@@ -212,7 +216,7 @@
% \lopt{refstring=}\meta{string} to override \cs{LettrineTestString}
% locally.} is meant for fancy initials with
% irregular heights (i.e.\ taken in fonts like Yinit (OpenType),
-% \file{cfr-initials},\dots). \lopt{refstring} forces the
+% \file{cfr-initials},…). \lopt{refstring} forces the
% |\fontsize| computations to be run on the initial given as
% |\lettrine|’s first mandatory argument instead of the reference
% string |\LettrineTestString|. In most cases, this option should
@@ -224,7 +228,7 @@
% Example: |\lettrine[lines=4, lraise=0.1, nindent=0em, |%
% |slope=-.5em]%|\\
% \mbox{}\phantom{\tt Example: lettrine}%
-% |{V}{oici} un exemple |\dots
+% |{V}{oici} un exemple |…
%
% Coloured initials are possible in conjonction with package
% \file{color}, examples: \\
@@ -237,46 +241,54 @@
% Three dimensions, |\LettrineWidth|, |\LettrineHeight| and
% |\LettrineDepth|, store the final size of the initial.
%
-% Once \file{lettrine.sty} will be installed (run \texttt{lualatex}
-% on \file{lettrine.ins} to extract it), compile \file{demo-fr.tex}
-% and \file{demo-lua.tex} print the resulting PDFs to see the
+% Have a look at files \file{demo-fr.tex} and \file{demo-lua.tex}
+% and at the resulting PDFs in the \file{doc} folder to see the
% possible usage of these parameters.
%
% \changes{v1.9}{2015/08/31}{New customisable string
% \cs{LettrineSecondString} to tune the initial’s height.}
%
-% The default settings can be customized either in a config file
-% \file{lettrine.cfg} (for a global usage), or on a per document
-% basis, in the preamble of each document. The following list
-% shows the syntax to set them and their default values:
+% Starting with version~2.30, the default settings can be
+% specified as options passed to the \pkg{lettrine} \emph{package}.
+% These options are the same as those of the |\lettrine| command%
+% \footnote{With one exception: \lopt{refstring} is available only
+% for the \cs{lettrine} command.}:
+% f.i. |\usepackage[lines=3]{lettrine}| will set the default to three
+% lines of text. Options passed to the \pkg{lettrine} package override
+% the defaults set in the \file{lettrine.cfg} file (see below) and will
+% be overriden by options passed to the |\lettrine| command.
+%
+% The default settings can be customized in a config file
+% \file{lettrine.cfg} for a global usage. The following list shows
+% the syntax to set them and their default values:
% \begin{itemize}
% \item |\setcounter{DefaultLines}{2}|,
% \item |\setcounter{DefaultDepth}{0}|,
% \item |\renewcommand*{\DefaultLoversize}{0}|,
% \item |\renewcommand*{\DefaultLraise}{0}|,
% \item |\renewcommand*{\DefaultLhang}{0}|,
-% \item |\LettrineImagefalse|,
-% \item |\LettrineOnGridfalse|,
-% \item |\LettrineRealHeightfalse|,
-% \item |\LettrineSelfReffalse|,
% \item |\setlength{\DefaultFindent}{0pt}|,
% \item |\setlength{\DefaultNindent}{0.5em}|,
% \item |\setlength{\DefaultSlope}{0pt}|.
-% \item |\setlength{\DiscardVskip}{0.2pt}|.
+% \item |\setlength{\DiscardVskip}{0.2pt}|,
+% \item |\LettrineImagefalse|,
+% \item |\LettrineOnGridfalse|,
+% \item |\LettrineRealHeightfalse|.
% \end{itemize}
%
% Instead of giving optional parameters to the |\lettrine| command,
-% it is possible, from version 1.5, to set them on a per character
+% it is possible to set them on a per character
% basis in a second config file (suggested by Pascal Kockaert):
-% |\renewcommand{\DefaultOptionsFile}{|\textit{filename}|}|
+% |\renewcommand{\DefaultOptionsFile}{|\meta{filename}|}|
% in the preamble (or anywhere in the document) will
-% force each call to |\lettrine| to read the file \textit{filename}.
-% See examples of such config files in the subdirectory
-% \file{contrib}.
+% force each call to |\lettrine| to read the file \meta{filename}.
+% Alternatively, |\usepackage[optionsfile=|\meta{filename}|]{lettrine}|
+% produces the same effect.
+% See examples of such config files in the subdirectory \file{contrib}.
%
% The dimensional parameters \lopt{findent}, \lopt{nindent} and
-% \lopt{slope}, can be set in \textit{filename} relative to
-% |\LettrineWidth| if needed. The settings read from this file
+% \lopt{slope}, can be set relative to |\LettrineWidth| if needed,
+% \emph{in \meta{filename} only}. The settings read from this file
% will be overridden by the optional arguments eventually given to
% |\lettrine|.
%
@@ -299,13 +311,13 @@
% low-level font interface (see LaTeX Companion, p.187--192),
% the |\selectfont| command is issued by |\LettrineFont|:\\
% |\renewcommand{\LettrineFontHook}{\fontfamily{ppl}|\ignorespaces
-% |\fontseries{bx}}%|\\
-% | \fontshape{sl}}|,\\
+% |\fontseries{bx}%|\\
+% | \fontshape{sl}}|\\
% selects Palatino bold expanded slanted for the dropped capital.
%
% With LuaLaTeX or XeLaTeX changing the lettrine’s font is
% even easier, simply use the |\fontspec| command:\\
-% |\renewcommand{\LettrineFontHook}{\fontspec{LinLibertine_I.otf}|\\
+% |\renewcommand{\LettrineFontHook}{\fontspec{LinLibertine_I.otf}}|\\
% will switch to Linux Libertine Initials.
%
% |\LettrineFontHook| can also be used to change the colour of
@@ -346,7 +358,7 @@
% hyphenation).
%
% You can also consider using one of the standard PostScript fonts
-% (Palatino, Times, Utopia\dots), or any OpenType font, they are
+% (Palatino, Times, Utopia…), or any OpenType font, they are
% fully scalable too!
%
% \newpage{}
@@ -419,10 +431,10 @@
% \end{macrocode}
%
% This package only runs with LaTeX and requires files
-% \file{keyval.sty} and \file{minifp.sty}.
+% \file{xkeyval.sty} and \file{minifp.sty}.
%
% \begin{macrocode}
-\RequirePackage{keyval,minifp}
+\RequirePackage{xkeyval,minifp}
% \end{macrocode}
%
% Default initializations: define the necessary counters, lengths,
@@ -442,8 +454,7 @@
% \changes{v2.1}{2018/08/14}{Newif \cs{ifLettrineVone} and
% new option `Vone’ (removed in v2.2, rollback prefered).}
%
-% \changes{v2.1}{2018/08/14}{New option `refstring’ and newif
-% \cs{ifLettrineSelfRef}.}
+% \changes{v2.1}{2018/08/14}{New option `refstring’.}
%
% \begin{macrocode}
\newcounter{DefaultLines}
@@ -464,9 +475,44 @@
\newif\ifLettrineImage
\newif\ifLettrineOnGrid
\newif\ifLettrineRealHeight
-\newif\ifLettrineSelfRef
% \end{macrocode}
%
+% Load a local config file if present in LaTeX’s search path.
+% \begin{macrocode}
+\InputIfFileExists{lettrine.cfg}
+ {\typeout{Loading lettrine.cfg}}
+ {\typeout{lettrine.cfg not found, using default values}}
+% \end{macrocode}
+%
+% \changes{v2.30}{2022/09/23}{Added global options to package
+% \pkg{lettrine}.}
+%
+% Global package options enable to override the default values given
+% above to generic parameters. These may be overriden again by
+% options passed to the |\lettrine[]{}{}| command.
+% \begin{macrocode}
+\DeclareOptionX{lines}[\value{DefaultLines}]{\setcounter{DefaultLines}{#1}}
+\DeclareOptionX{depth}[\value{DefaultDepth}]{\setcounter{DefaultDepth}{#1}}
+\DeclareOptionX{lhang}[]{\ifx#1\@empty\else
+ \renewcommand*{\DefaultLhang}{#1}\fi}
+\DeclareOptionX{loversize}[]{\ifx#1\@empty\else
+ \renewcommand*{\DefaultLoversize}{#1}\fi}
+\DeclareOptionX{lraise}[]{\ifx#1\@empty\else
+ \renewcommand*{\DefaultLraise}{#1}}
+\DeclareOptionX{findent}[\the\DefaultFindent]{%
+ \setlength{\DefaultFindent}{#1}}
+\DeclareOptionX{nindent}[\the\DefaultNindent]{%
+ \setlength{\DefaultNindent}{#1}}
+\DeclareOptionX{slope}[\the\DefaultSlope]{\setlength{\DefaultSlope}{#1}}
+\DeclareOptionX{image}[true]{\csname LettrineImage#1\endcsname}
+\DeclareOptionX{grid}[true]{\csname LettrineOnGrid#1\endcsname}
+\DeclareOptionX{novskip}[\the\DiscardVskip]{\setlength{\DiscardVskip}{#1}}
+\DeclareOptionX{realheight}[true]{\csname LettrineRealHeight#1\endcsname}
+\DeclareOptionX{optionsfile}[]{\ifx#1\@empty\else
+ \renewcommand*{\DefaultOptionsFile}{#1}\fi}
+\ProcessOptionsX
+% \end{macrocode}
+
% Then let’s define the necessary internal counters, lengths,
% and commands.
%
@@ -653,10 +699,11 @@
% \changes{v2.22}{2018/09/14}{Warn if \cs{fontsize} computation fails
% due to division by 0.}
%
-% When optional argument \lopt{selfref} is \lopt{true} the initial
-% itself is taken as reference to compute |\fontsize|, this can be
-% handy when working with fancy fonts (i.e.\ cfr-initials, Yinit).
-% In most cases, the default is a better choice.
+% The conditional |\ifL@selfref| is set to \lopt{true} by |\lettrine|
+% option \lopt{refstring}, then the initial itself is taken as
+% reference to compute |\fontsize|, this can be handy when working
+% with fancy fonts (i.e.\ cfr-initials, Yinit). In most cases, the
+% default is a better choice.
% \begin{macrocode}
\def\compute@fontsize{%
\ifL@selfref
@@ -700,10 +747,10 @@
% \begin{macro}{\LettrineImage}
% The following definition is for use with dropped capitals defined
% as images: EPS, PDF, JPG, PNG files (see examples in demo-fr.tex).
-% Its use requires the |graphicx| package to be loaded in the
-% preamble with |\usepackage{graphicx}|. The required size is
-% computed just as in the standard case, |\includegraphics|
-% prints the image at this size.
+% Its requires the |graphicx| package to be loaded in the
+% preamble with |\usepackage{graphicx}|. The image’s height is
+% computed just as in the standard case and passed to
+% |\includegraphics|.
%
% \changes{v1.6}{2004/05/22}{Added \cs{LettrineFontHook}
% to \cs{LettrineFontEPS}. This is needed for color options.}
@@ -731,7 +778,7 @@
% \end{macrocode}
% \end{macro}
%
-% Set up keyval initializations.
+% Set up keyval initializations for the |\lettrine| command.
%
% \begin{macrocode}
\define@key{L}{lines}{\setcounter{L@lines}{#1}}
@@ -797,7 +844,6 @@
\ifLettrineImage\L@imagetrue\else\L@imagefalse\fi
\ifLettrineOnGrid\L@gridtrue\else\L@gridfalse\fi
\ifLettrineRealHeight\L@realhtrue\else\L@realhfalse\fi
- \ifLettrineSelfRef\L@selfreftrue\else\L@selfreffalse\fi
% \end{macrocode}
%
% The final initial size depends on the height of |\L@tbox|; the
@@ -831,7 +877,7 @@
% |\DefaultOptionsFile|), do this inside a group, and define a
% global command |\l@LOKeys| which will expand to the list of
% options given by |\LettrineOptionsFor| for the current initial
-% (defined by |#2|)\dots
+% (defined by |#2|)…
% \begin{macrocode}
\if\DefaultOptionsFile\relax
\else
@@ -1005,7 +1051,7 @@
%
% \changes{v1.1}{1999/08/18}{Add \cs{rightmargin} to
% \cs{L@Pindent} for \cs{Lettrine} to work properly in quote,
-% quotation, abstract environments\dots{} but do not change
+% quotation, abstract environments… but do not change
% \cs{linewidth} which is set by these environments.}
%
% \changes{v1.4}{2002/10/26}{\cs{lettrine} still didn’t
@@ -1017,7 +1063,7 @@
% \changes{v2.22}{2019/04/04}{\cs{@totalleftmargin} is the correct
% indentation for quote, quotation and abstract environments.}
%
-% This is for quotation, quote, abstract\dots{} environments:
+% This is for quotation, quote, abstract… environments:
% |\linewidth| is set by these environments, all we have to do
% is to shift our text left by |\@totalleftmargin|.
% \begin{macrocode}
@@ -1080,12 +1126,6 @@
}
% \end{macrocode}
%
-% Load a local config file if present in LaTeX’s search path.
-% \begin{macrocode}
-\InputIfFileExists{lettrine.cfg}
- {\typeout{Loading lettrine.cfg}}
- {\typeout{lettrine.cfg not found, using default values}}
-% \end{macrocode}
% \iffalse
%</sty>
% \fi
@@ -1123,7 +1163,6 @@
%%\LettrineImagefalse
%%\LettrineOnGridfalse
%%\LettrineRealHeightfalse
-%%\LettrineSelfReffalse
%%
%% Theses are *commands* (value=string, only height matters):
%%\renewcommand*{\LettrineTestString}{EFTZ}
@@ -1137,30 +1176,6 @@
%</cfg>
% \fi
%
-% \iffalse
-%<*dtx>
-% \fi
-%%
-%% \CharacterTable
-%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
-%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
-%% Digits \0\1\2\3\4\5\6\7\8\9
-%% Exclamation \! Double quote \" Hash (number) \#
-%% Dollar \$ Percent \% Ampersand \&
-%% Acute accent \' Left paren \( Right paren \)
-%% Asterisk \* Plus \+ Comma \,
-%% Minus \- Point \. Solidus \/
-%% Colon \: Semicolon \; Less than \<
-%% Equals \= Greater than \> Question mark \?
-%% Commercial at \@ Left bracket \[ Backslash \\
-%% Right bracket \] Circumflex \^ Underscore \_
-%% Grave accent \` Left brace \{ Vertical bar \|
-%% Right brace \} Tilde \~}
-%%
-% \iffalse
-%</dtx>
-% \fi
-%
% \Finale
\endinput