Debian Codegraph @

texmf-dist/source/latex/froufrou/froufrou.dtx

raw
1 % \iffalse meta-comment
2 % Copyright 2020-2021 Nelson Lago <[email protected]>
3 %
4 % This work may be distributed and/or modified under the conditions of the
5 % LaTeX Project Public License, either version 1.3c of this license or (at
6 % your option) any later version. The latest version of this license can be
7 % found at http://www.latex-project.org/lppl.txt and version 1.3 or later
8 % is part of all distributions of LaTeX version 2005/12/01 or later.
9 %
10 % This work has the LPPL maintenance status `maintained'.
11 %
12 % The Current Maintainer of this work is Nelson Lago <[email protected]>.
13 %
14 % \fi
15 % \iffalse
16 %
17 %<package>\NeedsTeXFormat{LaTeX2e}[2015/01/01]
18 %<package>\ProvidesPackage{froufrou}[2021/05/06 1.4.0 Visual section separator]
19 %
20 %<*driver>
21
22 \documentclass{ltxdoc}
23
24 \usepackage[hyperref,svgnames,x11names,table]{xcolor}
25 \usepackage{url}
26 \urlstyle{sf}
27 \usepackage{hyperref}
28 \hypersetup{
29 colorlinks=true,
30 citecolor=DarkGreen,
31 linkcolor=NavyBlue,
32 urlcolor=DarkRed,
33 filecolor=green,
34 anchorcolor=black,
35 }
36
37 \usepackage{froufrou}
38 \usepackage{pgfornament}
39
40 \usepackage{libertinus}
41 \usepackage[scale=.85]{sourcecodepro}
42
43 %%\EnableCrossrefs
44 %%\CodelineIndex
45 \RecordChanges
46
47 \OnlyDescription
48
49 \begin{document}
50 \DocInput{froufrou.dtx}
51 \end{document}
52
53 %</driver>
54 %
55 % \fi
56 %
57 % \CheckSum{0}
58 %
59 % \changes{v1.0}{2019/04/24}{Prerelease}
60 % \changes{v1.1}{2020/02/03}{Prerelease}
61 % \changes{v1.2}{2020/12/22}{First public version}
62 % \changes{v1.3.0}{2021/04/22}{More related packages}
63 % \changes{v1.3.0}{2021/04/22}{Small doc improvements}
64 % \changes{v1.3.0}{2021/04/22}{Add ``closing'' ornament}
65 % \changes{v1.4.0}{2021/05/06}{Add related package}
66 % \changes{v1.4.0}{2021/05/06}{Add \texttt{pgfornament} example}
67 % \changes{v1.4.0}{2021/05/06}{Make nested optional arguments work by using xparse}
68 %
69 % \GetFileInfo{froufrou.sty}
70 %
71 % \title{The \textsf{froufrou} package\thanks{This document
72 % corresponds to \textsf{froufrou}~\fileversion, dated~\filedate.}}
73 %
74 % \author{
75 % Nelson Lago\\
76 % \texttt{[email protected]}\\
77 % ~\\
78 % \url{https://gitlab.com/lago/froufrou}
79 % }
80 %
81 % \maketitle
82 %
83 % \begin{abstract}
84 %
85 % This package provides fancy separators, which are visual cues that
86 % indicate a change of subject or context without actually starting
87 % a new chapter or section.
88 %
89 % \end{abstract}
90 %
91 % \section{Introduction}
92 %
93 % This package allows the user to create fancy separators that visually
94 % indicate text subdivisions without a title, i.e., they are similar to
95 % \verb|\section| but do not provide a name to the new section. Apparently,
96 % there is no definite name for such separators; they may be regarded as
97 % thought breaks or anonymous sections, but often borrow their name from
98 % the ornament that embodies them, such as asterism, fleuron, or dinkus.
99 % An example:
100 %
101 % \froufrou
102 %
103 % The package prevents separators from appearing at the top of the page
104 % (that would be confusing), but allows them at the bottom if strictly
105 % necessary. It should work equally well with one or two-column text
106 % and with single or doublespacing. The package offers a few predefined
107 % ornaments to be used as separators, but the user may create others.
108 %
109 % \section{Usage}
110 %
111 % After \verb|\usepackage{froufrou}|, just call \verb|\froufrou| to create
112 % a subdivision. By default, the separator behaves like \verb|\section|,
113 % suppressing indentation in the following paragraph. With \verb|\froufrou*|,
114 % this feature is disabled and the following paragraph is indented normally.
115 %
116 % You may select a different separator appearance either by
117 % supplying the name of a predefined ornament as a package
118 % option (\verb|\usepackage[ornament]{froufrou}|) or by calling
119 % \verb|\setfroufrou{ornament}| anywhere in the document. You may
120 % also use \verb|\froufrou[ornament]| to only affect that specific
121 % separator. \verb|ornament| is one of:
122 %
123 % \makeatletter
124 % \begin{description}
125 %
126 % \item[fleuron,] the default\footnote{From the \verb|fancyhdr| docs.}: \quad\raisebox{1pt}{\@froufrouFleuron}
127 %
128 % \item[simplefleuron,] similar to the default, but without the side lines: \quad\raisebox{2pt}{\@froufrouSimpleFleuron}
129 %
130 % \item[asterism,] three asterisks forming a triangle\footnote{
131 % From \verb|symbols-a4| (search for ``asterism'').}: \quad\@froufrouAsterism
132 %
133 % \item[tightasterism,] similar, but with tighter spacing: \quad\@froufrouTightAsterism
134 %
135 % \item[trueasterism,] also similar, but using unicode character
136 % U+2042\footnote{Only works with a unicode engine (luatex, xetex)
137 % and a font that provides the glyph (such as libertinus).}: \quad\@froufrouTrueAsterism
138 %
139 % \item[dinkus,] three asterisks forming a line: \quad\raisebox{-2.5pt}{\@froufrouDinkus}
140 %
141 % \item[closing,] a calligraphic curve\footnote{Uses \verb|tikz|.}
142 % (shown reduced here): \quad\raisebox{-2pt}{\scalebox{.28}{\@froufrouClosing}}
143 %
144 % \end{description}
145 % \makeatother
146 %
147 % Beyond the predefined ornaments, you may also use
148 % \verb|\setfroufrou{SOMETHING}| or \verb|\froufrou[SOMETHING]|
149 % to make \verb|SOMETHING| be the separator. However, please note
150 % that \verb|\usepackage[SOMETHING]{froufrou}| does \emph{not}
151 % work! An example using the \mbox{\verb|pgfornament|} package:
152 %
153 % \bgroup\footnotesize\vspace{\baselineskip}
154 % \noindent
155 % \verb|\froufrou[\pgfornament[height=.1cm]{87}\hspace{-2pt}\pgfornament[width=.5cm,|\\
156 % \verb|ydelta=-10pt]{9}\hspace{-2pt}\pgfornament[symmetry=v,height=.1cm]{87}]|\par
157 % \vspace{\baselineskip}\egroup
158 %
159 % \noindent which produces
160 %
161 % \froufrou[\pgfornament[height=.1cm]{87}\hspace{-2pt}\pgfornament[width=.5cm,
162 % ydelta=-10pt]{9}\hspace{-2pt}\pgfornament[symmetry=v,height=.1cm]{87}]
163 %
164 % \section{See also}
165 %
166 % \begin{itemize}
167 % \item \url{http://tug.org/TUGboat/tb32-2/tb101glister.pdf} ;
168 %
169 % \item The \verb|pgfornament|, \verb|adforn|, \verb|fourier-orns|,
170 % \verb|marvosym|, \verb|typicons|, \verb|decorule|,
171 % \mbox{\verb|pifont|}, \verb|adfsymbols|, \verb|fontawesome|,
172 % and \verb|fontawesome5| packages, which may aid in creating
173 % separators;
174 %
175 % \item The \verb|novel| and \verb|memoir| classes, which offer
176 % the somewhat similar commands \verb|\ChapterDeco| and
177 % \verb|\fancybreak| respectively;
178 %
179 % \item The \verb|sectionbreak| package, similar to this one.
180 % \end{itemize}
181 %
182 % \StopEventually{\PrintChanges}
183 %
184 % \section{The implementation}
185 %
186 % \begin{macrocode}
187
188 \RequirePackage{etoolbox}
189 \RequirePackage{expl3}
190 \RequirePackage{xparse}
191 \RequirePackage{tikz}
192
193 % .1\textwidth works well for one and two-column text.
194 \RequirePackage{fourier-orns}
195 \newcommand\@froufrouFleuron{%
196 \bgroup
197 \footnotesize
198 \rule[.7mm]{.1\textwidth}{0.5pt}%
199 \enspace\,%
200 \decofourleft\decotwo\decofourright
201 \enspace\,%
202 \rule[.7mm]{.1\textwidth}{0.5pt}%
203 \egroup
204 }
205
206 \newcommand\@froufrouSimpleFleuron{%
207 \bgroup
208 \footnotesize
209 \decofourleft\decotwo\decofourright
210 \egroup
211 }
212
213 \newcommand{\@froufrouTightAsterism}{%
214 \bgroup
215 \smash{%
216 \raisebox{-.5ex}{%
217 \setlength{\tabcolsep}{-.5pt}%
218 \begin{tabular}{@{}cc@{}}%
219 \multicolumn2c*\\[-2ex]*&*%
220 \end{tabular}%
221 }%
222 }%
223 \egroup
224 }
225
226 \newcommand{\@froufrouAsterism}{%
227 \bgroup
228 \smash{%
229 \raisebox{-.5ex}{%
230 \setlength{\tabcolsep}{0pt}%
231 \begin{tabular}{@{}cc@{}}%
232 \multicolumn2c*\\[-1.8ex]*&*%
233 \end{tabular}%
234 }%
235 }%
236 \egroup
237 }
238
239 % Unicode character U+2042 (\char"2042), only with a unicode engine
240 % (luatex/xetex) and a font that has this glyph (such as libertinus
241 % or libertine)
242 \newcommand\@froufrouTrueAsterism{⁂}
243
244 \newcommand{\@froufrouDinkus}{\relax*\quad*\quad*}
245
246 % Drawn in inkscape and saved as pstricks, then manually adjusted
247 % according to the instructions in the pgfornament package docs.
248 \newcommand{\@froufrouClosing}{
249 \begingroup
250 \def\i{\pgfusepath{clip}}%
251 \def\k{\pgfusepath{stroke}}%
252 \let\o\pgfpathclose
253 \let\s\pgfusepathqfillstroke
254 \def\p ##1##2{\pgfqpoint{##1bp}{##2bp}}%
255 \def\m ##1 ##2 {\pgfpathmoveto{\p{##1}{##2}}}%
256 \def\r ##1 ##2 ##3 ##4 {\pgfpathrectangle{\p{##1}{##2}}{%
257 \p{##3}{##4}}}%
258 \def\l ##1 ##2 {\pgfpathlineto{\p{##1}{##2}}}%
259 \def\c ##1 ##2 ##3 ##4 ##5 ##6 {%
260 \pgfpathcurveto{\p{##1}{##2}}{\p{##3}{##4}}{\p{##5}{##6}}}%
261 \begin{tikzpicture}
262 \pgftransformscale{.7}
263 \m 361.42743307 485.43412913
264 \c 364.42138961 486.7928315 367.73662488 487.42057323 370.95633638 488.30607874
265 \c 379.74149291 490.44056693 383.76755906 490.62308031 391.35855118 488.3695748
266 \c 405.76059213 484.51011024 406.70554961 483.73814173 413.58935433 483.38611654
267 \c 416.16343937 483.29540787 417.77933858 483.3672189 420.40183937 483.67147087
268 \c 422.89485354 483.96740787 426.64293543 485.12473701 426.71546457 486.98607874
269 \c 426.6103937 488.63913071 423.03061417 487.99570394 423.57588661 488.15168504
270 \c 418.2015874 487.67754331 413.49017953 485.75739213 408.4583811 484.02119055
271 \c 399.74728819 480.47652283 390.74634331 477.26052283 381.83172283 474.28418268
272 \c 375.53600126 472.27740472 370.4288315 471.94854803 367.61240693 473.5680378
273 \c 364.79626583 475.33300157 371.42866394 477.84098268 372.45991559 478.09961575
274 \c 377.50835906 479.82100157 383.18290394 480.01485354 386.6184189 478.67342362
275 \c 393.54591496 475.75513701 402.00702992 472.28330079 405.77480315 471.12691654
276 \c 412.4688 468.98203465 416.39803465 468.57569764 419.52922205 469.03139528
277 \c 421.66703622 469.34169449 423.44821417 470.04102047 424.39819843 470.98314331
278 \c 425.30127874 472.04364094 424.96837795 473.86847244 421.96418268 473.86250079
279 \c 421.2608126 473.87005984 418.78662047 473.90520945 414.92602205 472.87320945
280 \c 408.18776693 471.2327811 401.88672756 467.46954331 396.75938268 462.73613858
281 \c 392.33865827 458.27013543 390.73662992 453.68923465 389.21480315 447.90428976
282 \c 388.56245669 444.65930079 390.39484724 441.00941102 387.00623622 440.46667087
283 \c 386.52650079 443.15096693 387.11508661 447.4599685 388.18087559 450.49296378
284 \c 391.04658898 457.85060787 395.2343811 463.9695874 401.94822047 467.95831181
285 \c 406.58543622 470.56331339 412.23809764 472.88794961 416.70444094 473.7440126
286 \c 420.24733228 474.27533858 421.93621417 474.76622362 424.25132598 473.81431181
287 \c 425.94848504 472.94452913 426.61549606 470.68221732 422.90362205 468.96185197
288 \c 420.50127874 468.31547717 415.42231181 466.65660472 407.19348661 469.46415118
289 \c 399.46495748 472.24679055 399.78568819 472.31028661 390.79419213 475.96452283
290 \c 387.20500157 477.36532913 385.63029921 478.95983622 380.68550551 478.98274016
291 \c 380.36613543 478.99785827 379.3023874 478.95628346 378.77374488 478.93474016
292 \c 374.11377638 478.63464567 368.68895622 476.18622992 368.36232189 475.76991496
293 \c 365.33666646 473.89031811 370.62351496 473.26998425 372.80703874 473.48534173
294 \c 373.85684031 473.51557795 376.5843326 473.63009764 379.31032441 474.56628661
295 \c 388.16209134 477.4280315 396.81985512 480.20341417 405.51753071 483.50762835
296 \c 410.38851024 485.35827402 414.70730079 487.11896693 419.77632756 488.3767937
297 \c 422.21064567 488.90418898 426.66326929 490.4783622 428.19949606 487.8576
298 \c 428.96462362 486.08613543 426.88304882 484.21878425 423.46219843 483.49243465
299 \c 418.42117795 482.74091339 413.21850709 482.48779843 407.04702992 483.81936378
300 \c 399.01345512 485.29413543 392.91106772 487.3039748 384.77571024 489.11584252
301 \c 383.20051654 489.31729134 382.84312441 489.53967874 381.31464567 489.51473386
302 \c 374.93645102 489.38849764 370.27737827 486.79150866 364.25366929 484.92170079
303 \c 363.08989228 484.58154331 362.13536126 485.15338583 361.42743307 485.43405354
304 \o\s
305 \end{tikzpicture}
306 \endgroup
307 }
308
309 \ExplSyntaxOn
310 \newcommand\setfroufrou[1]{%
311 \str_case:nnF{#1}{
312 {}{\relax}
313 {fleuron}{\def\@froufrouOrnament{\@froufrouFleuron}}
314 {simplefleuron}{\def\@froufrouOrnament{\@froufrouSimpleFleuron}}
315 {asterism}{\def\@froufrouOrnament{\@froufrouAsterism}}
316 {tightasterism}{\def\@froufrouOrnament{\@froufrouTightAsterism}}
317 {trueasterism}{\def\@froufrouOrnament{\@froufrouTrueAsterism}}
318 {dinkus}{\def\@froufrouOrnament{\@froufrouDinkus}}%
319 {closing}{\def\@froufrouOrnament{\@froufrouClosing}}%
320 }{\def\@froufrouOrnament{#1}}%
321 }
322 \ExplSyntaxOff
323
324 % I see no reason to make these different, but feel free to change this :)
325 \def\@froufrouspacebefore{\vskip 22pt plus 7pt minus 5pt}
326 \def\@froufrouspaceafter{\@froufrouspacebefore}
327
328 % The starred form means "indent the first line of the next paragraph"
329 % (\if@afterindent is read by \@afterheading)
330 \NewDocumentCommand{\froufrou}{s O{}}{%
331 % Make sure we left horizontal mode.
332 \nopagebreak[4]\par
333
334 \IfBooleanTF{#1}{\@afterindenttrue}{\@afterindentfalse}
335
336 \nopagebreak[4]\@froufrouspacebefore\nopagebreak[4]
337
338 % Start a new group to (1) reset \doublespacing, \parskip, and
339 % \baselineskip, so spacing is independent from the previous text
340 % settings and (2) so that using #1 to change the ornament only
341 % affects the current call. Then, start yet another group only
342 % for the ornament because font size changes in it should not
343 % affect spacing either.
344 \bgroup
345 \setfroufrou{#2}%
346 \normalsize
347 \ifdefvoid{\setstretch}{}{\setstretch{\setspace@singlespace}}% normally 1
348 \setlength{\parskip}{0pt}
349 \noindent\centering\bgroup\@froufrouOrnament\egroup\par
350 \egroup
351
352 \nopagebreak[4]\@froufrouspaceafter\nopagebreak[4]
353
354 % Next paragraph's \doublespacing, \baselineskip, and \parskip
355 % should not affect spacing.
356 \@froufrouFixSpacingAfter
357
358 % Breaking after the separator is acceptable as a last resort. Since
359 % we use a lot of vertical space before/after it, not allowing this
360 % break might lead to poor results in some cases.
361 \nopagebreak[3]
362
363 % Emulate the behavior of \section, \subsection etc: prevent
364 % the first line of the next paragraph from being indented
365 % and absolutely forbid a club line in the next paragraph.
366 \@afterheading
367 }
368
369 % For compatibility with older versions of this package.
370 \NewDocumentCommand{\frufru}{s O{}}{%
371 \IfBooleanTF{#1}{\froufrou*[#2]}{\froufrou[#2]}%
372 }
373
374 \newcommand\@froufrouFixSpacingAfter{
375 % The next \par will add \parskip and \baselineskip. We want to
376 % (1) eliminate \parskip so that spacing does not change if it
377 % is nonzero and (2) add the "normal" \baselineskip, even if the
378 % text is set using \doublespacing. These adjustments may be off
379 % if font size, \parskip or \baselineskip are changed before the
380 % next paragraph.
381
382 \nopagebreak[4]\vskip -\parskip
383
384 \ifdefvoid{\setstretch}
385 {}
386 {
387 \bgroup
388 % \singlespacing may add an extra \baselineskip; let's
389 % avoid surprises and use \setstrech instead.
390 \setstretch {\setspace@singlespace}% normally 1
391 \nopagebreak[4]\vskip \baselineskip
392 \egroup
393
394 \nopagebreak[4]\vskip -\baselineskip
395 }
396 }
397
398 % Trying to accept a custom ornament as a package option is not such a
399 % great idea: first, it has to be expandable; second, this may become
400 % a problem if we want to add more options to the class in the future.
401 \DeclareOption{fleuron}{\setfroufrou{fleuron}}
402 \DeclareOption{simplefleuron}{\setfroufrou{simplefleuron}}
403 \DeclareOption{asterism}{\setfroufrou{asterism}}
404 \DeclareOption{tightasterism}{\setfroufrou{tightasterism}}
405 \DeclareOption{trueasterism}{\setfroufrou{trueasterism}}
406 \DeclareOption{dinkus}{\setfroufrou{dinkus}}
407 \DeclareOption{closing}{\setfroufrou{closing}}
408 \DeclareOption*{\PackageWarning{froufrou}{Unknown option `\CurrentOption'}}
409 \ExecuteOptions{fleuron}
410 \ProcessOptions\relax
411
412 % \end{macrocode}
413 % \Finale