% \iffalse meta-comment
% Copyright 2020-2021 Nelson Lago <lago@ime.usp.br>
%
% This work may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3c of this license or (at
% your option) any later version. The latest version of this license can be
% found at http://www.latex-project.org/lppl.txt and version 1.3 or later
% is part of all distributions of LaTeX version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Nelson Lago <lago@ime.usp.br>.
%
% \fi
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}[2015/01/01]
%<package>\ProvidesPackage{froufrou}[2021/05/06 1.4.0 Visual section separator]
%
%<*driver>

\documentclass{ltxdoc}

\usepackage[hyperref,svgnames,x11names,table]{xcolor}
\usepackage{url}
\urlstyle{sf}
\usepackage{hyperref}
\hypersetup{
  colorlinks=true,
  citecolor=DarkGreen,
  linkcolor=NavyBlue,
  urlcolor=DarkRed,
  filecolor=green,
  anchorcolor=black,
}

\usepackage{froufrou}
\usepackage{pgfornament}

\usepackage{libertinus}
\usepackage[scale=.85]{sourcecodepro}

%%\EnableCrossrefs
%%\CodelineIndex
\RecordChanges

\OnlyDescription

\begin{document}
\DocInput{froufrou.dtx}
\end{document}

%</driver>
%
% \fi
%
% \CheckSum{0}
%
% \changes{v1.0}{2019/04/24}{Prerelease}
% \changes{v1.1}{2020/02/03}{Prerelease}
% \changes{v1.2}{2020/12/22}{First public version}
% \changes{v1.3.0}{2021/04/22}{More related packages}
% \changes{v1.3.0}{2021/04/22}{Small doc improvements}
% \changes{v1.3.0}{2021/04/22}{Add ``closing'' ornament}
% \changes{v1.4.0}{2021/05/06}{Add related package}
% \changes{v1.4.0}{2021/05/06}{Add \texttt{pgfornament} example}
% \changes{v1.4.0}{2021/05/06}{Make nested optional arguments work by using xparse}
%
% \GetFileInfo{froufrou.sty}
%
% \title{The \textsf{froufrou} package\thanks{This document
% corresponds to \textsf{froufrou}~\fileversion, dated~\filedate.}}
%
% \author{
% Nelson Lago\\
% \texttt{lago@ime.usp.br}\\
% ~\\
% \url{https://gitlab.com/lago/froufrou}
% }
%
% \maketitle
%
% \begin{abstract}
%
% This package provides fancy separators, which are visual cues that
% indicate a change of subject or context without actually starting
% a new chapter or section.
%
% \end{abstract}
%
% \section{Introduction}
%
% This package allows the user to create fancy separators that visually
% indicate text subdivisions without a title, i.e., they are similar to
% \verb|\section| but do not provide a name to the new section. Apparently,
% there is no definite name for such separators; they may be regarded as
% thought breaks or anonymous sections, but often borrow their name from
% the ornament that embodies them, such as asterism, fleuron, or dinkus.
% An example:
%
% \froufrou
%
% The package prevents separators from appearing at the top of the page
% (that would be confusing), but allows them at the bottom if strictly
% necessary. It should work equally well with one or two-column text
% and with single or doublespacing. The package offers a few predefined
% ornaments to be used as separators, but the user may create others.
%
% \section{Usage}
%
% After \verb|\usepackage{froufrou}|, just call \verb|\froufrou| to create
% a subdivision. By default, the separator behaves like \verb|\section|,
% suppressing indentation in the following paragraph. With \verb|\froufrou*|,
% this feature is disabled and the following paragraph is indented normally.
%
% You may select a different separator appearance either by
% supplying the name of a predefined ornament as a package
% option (\verb|\usepackage[ornament]{froufrou}|) or by calling
% \verb|\setfroufrou{ornament}| anywhere in the document. You may
% also use \verb|\froufrou[ornament]| to only affect that specific
% separator. \verb|ornament| is one of:
%
% \makeatletter
% \begin{description}
%
% \item[fleuron,] the default\footnote{From the \verb|fancyhdr| docs.}: \quad\raisebox{1pt}{\@froufrouFleuron}
%
% \item[simplefleuron,] similar to the default, but without the side lines: \quad\raisebox{2pt}{\@froufrouSimpleFleuron}
%
% \item[asterism,] three asterisks forming a triangle\footnote{
% From \verb|symbols-a4| (search for ``asterism'').}: \quad\@froufrouAsterism
%
% \item[tightasterism,] similar, but with tighter spacing: \quad\@froufrouTightAsterism
%
% \item[trueasterism,] also similar, but using unicode character
%      U+2042\footnote{Only works with a unicode engine (luatex, xetex)
%      and a font that provides the glyph (such as libertinus).}: \quad\@froufrouTrueAsterism
%
% \item[dinkus,] three asterisks forming a line: \quad\raisebox{-2.5pt}{\@froufrouDinkus}
%
% \item[closing,] a calligraphic curve\footnote{Uses \verb|tikz|.}
%      (shown reduced here): \quad\raisebox{-2pt}{\scalebox{.28}{\@froufrouClosing}}
%
% \end{description}
% \makeatother
%
% Beyond the predefined ornaments, you may also use
% \verb|\setfroufrou{SOMETHING}| or \verb|\froufrou[SOMETHING]|
% to make \verb|SOMETHING| be the separator. However, please note
% that \verb|\usepackage[SOMETHING]{froufrou}| does \emph{not}
% work! An example using the \mbox{\verb|pgfornament|} package:
%
% \bgroup\footnotesize\vspace{\baselineskip}
% \noindent
% \verb|\froufrou[\pgfornament[height=.1cm]{87}\hspace{-2pt}\pgfornament[width=.5cm,|\\
% \verb|ydelta=-10pt]{9}\hspace{-2pt}\pgfornament[symmetry=v,height=.1cm]{87}]|\par
% \vspace{\baselineskip}\egroup
%
% \noindent which produces
%
% \froufrou[\pgfornament[height=.1cm]{87}\hspace{-2pt}\pgfornament[width=.5cm,
% ydelta=-10pt]{9}\hspace{-2pt}\pgfornament[symmetry=v,height=.1cm]{87}]
%
% \section{See also}
%
% \begin{itemize}
% \item \url{http://tug.org/TUGboat/tb32-2/tb101glister.pdf} ;
%
% \item The \verb|pgfornament|, \verb|adforn|, \verb|fourier-orns|,
%       \verb|marvosym|, \verb|typicons|, \verb|decorule|,
%       \mbox{\verb|pifont|}, \verb|adfsymbols|, \verb|fontawesome|,
%       and \verb|fontawesome5| packages, which may aid in creating
%       separators;
%
% \item The \verb|novel| and \verb|memoir| classes, which offer
%       the somewhat similar commands \verb|\ChapterDeco| and
%       \verb|\fancybreak| respectively;
%
% \item The \verb|sectionbreak| package, similar to this one.
% \end{itemize}
%
% \StopEventually{\PrintChanges}
%
% \section{The implementation}
%
%    \begin{macrocode}

\RequirePackage{etoolbox}
\RequirePackage{expl3}
\RequirePackage{xparse}
\RequirePackage{tikz}

% .1\textwidth works well for one and two-column text.
\RequirePackage{fourier-orns}
\newcommand\@froufrouFleuron{%
    \bgroup
    \footnotesize
    \rule[.7mm]{.1\textwidth}{0.5pt}%
    \enspace\,%
    \decofourleft\decotwo\decofourright
    \enspace\,%
    \rule[.7mm]{.1\textwidth}{0.5pt}%
    \egroup
}

\newcommand\@froufrouSimpleFleuron{%
    \bgroup
    \footnotesize
    \decofourleft\decotwo\decofourright
    \egroup
}

\newcommand{\@froufrouTightAsterism}{%
  \bgroup
  \smash{%
    \raisebox{-.5ex}{%
      \setlength{\tabcolsep}{-.5pt}%
      \begin{tabular}{@{}cc@{}}%
        \multicolumn2c*\\[-2ex]*&*%
      \end{tabular}%
    }%
  }%
  \egroup
}

\newcommand{\@froufrouAsterism}{%
  \bgroup
  \smash{%
    \raisebox{-.5ex}{%
      \setlength{\tabcolsep}{0pt}%
      \begin{tabular}{@{}cc@{}}%
        \multicolumn2c*\\[-1.8ex]*&*%
      \end{tabular}%
    }%
  }%
  \egroup
}

% Unicode character U+2042 (\char"2042), only with a unicode engine
% (luatex/xetex) and a font that has this glyph (such as libertinus
% or libertine)
\newcommand\@froufrouTrueAsterism{⁂}

\newcommand{\@froufrouDinkus}{\relax*\quad*\quad*}

% Drawn in inkscape and saved as pstricks, then manually adjusted
% according to the instructions in the pgfornament package docs.
\newcommand{\@froufrouClosing}{
  \begingroup
  \def\i{\pgfusepath{clip}}%
  \def\k{\pgfusepath{stroke}}%
  \let\o\pgfpathclose
  \let\s\pgfusepathqfillstroke
  \def\p ##1##2{\pgfqpoint{##1bp}{##2bp}}%
  \def\m ##1 ##2 {\pgfpathmoveto{\p{##1}{##2}}}%
  \def\r ##1 ##2 ##3 ##4 {\pgfpathrectangle{\p{##1}{##2}}{%
  \p{##3}{##4}}}%
  \def\l ##1 ##2 {\pgfpathlineto{\p{##1}{##2}}}%
  \def\c ##1 ##2 ##3 ##4 ##5 ##6 {%
  \pgfpathcurveto{\p{##1}{##2}}{\p{##3}{##4}}{\p{##5}{##6}}}%
  \begin{tikzpicture}
  \pgftransformscale{.7}
  \m 361.42743307 485.43412913
  \c 364.42138961 486.7928315 367.73662488 487.42057323 370.95633638 488.30607874
  \c 379.74149291 490.44056693 383.76755906 490.62308031 391.35855118 488.3695748
  \c 405.76059213 484.51011024 406.70554961 483.73814173 413.58935433 483.38611654
  \c 416.16343937 483.29540787 417.77933858 483.3672189 420.40183937 483.67147087
  \c 422.89485354 483.96740787 426.64293543 485.12473701 426.71546457 486.98607874
  \c 426.6103937 488.63913071 423.03061417 487.99570394 423.57588661 488.15168504
  \c 418.2015874 487.67754331 413.49017953 485.75739213 408.4583811 484.02119055
  \c 399.74728819 480.47652283 390.74634331 477.26052283 381.83172283 474.28418268
  \c 375.53600126 472.27740472 370.4288315 471.94854803 367.61240693 473.5680378
  \c 364.79626583 475.33300157 371.42866394 477.84098268 372.45991559 478.09961575
  \c 377.50835906 479.82100157 383.18290394 480.01485354 386.6184189 478.67342362
  \c 393.54591496 475.75513701 402.00702992 472.28330079 405.77480315 471.12691654
  \c 412.4688 468.98203465 416.39803465 468.57569764 419.52922205 469.03139528
  \c 421.66703622 469.34169449 423.44821417 470.04102047 424.39819843 470.98314331
  \c 425.30127874 472.04364094 424.96837795 473.86847244 421.96418268 473.86250079
  \c 421.2608126 473.87005984 418.78662047 473.90520945 414.92602205 472.87320945
  \c 408.18776693 471.2327811 401.88672756 467.46954331 396.75938268 462.73613858
  \c 392.33865827 458.27013543 390.73662992 453.68923465 389.21480315 447.90428976
  \c 388.56245669 444.65930079 390.39484724 441.00941102 387.00623622 440.46667087
  \c 386.52650079 443.15096693 387.11508661 447.4599685 388.18087559 450.49296378
  \c 391.04658898 457.85060787 395.2343811 463.9695874 401.94822047 467.95831181
  \c 406.58543622 470.56331339 412.23809764 472.88794961 416.70444094 473.7440126
  \c 420.24733228 474.27533858 421.93621417 474.76622362 424.25132598 473.81431181
  \c 425.94848504 472.94452913 426.61549606 470.68221732 422.90362205 468.96185197
  \c 420.50127874 468.31547717 415.42231181 466.65660472 407.19348661 469.46415118
  \c 399.46495748 472.24679055 399.78568819 472.31028661 390.79419213 475.96452283
  \c 387.20500157 477.36532913 385.63029921 478.95983622 380.68550551 478.98274016
  \c 380.36613543 478.99785827 379.3023874 478.95628346 378.77374488 478.93474016
  \c 374.11377638 478.63464567 368.68895622 476.18622992 368.36232189 475.76991496
  \c 365.33666646 473.89031811 370.62351496 473.26998425 372.80703874 473.48534173
  \c 373.85684031 473.51557795 376.5843326 473.63009764 379.31032441 474.56628661
  \c 388.16209134 477.4280315 396.81985512 480.20341417 405.51753071 483.50762835
  \c 410.38851024 485.35827402 414.70730079 487.11896693 419.77632756 488.3767937
  \c 422.21064567 488.90418898 426.66326929 490.4783622 428.19949606 487.8576
  \c 428.96462362 486.08613543 426.88304882 484.21878425 423.46219843 483.49243465
  \c 418.42117795 482.74091339 413.21850709 482.48779843 407.04702992 483.81936378
  \c 399.01345512 485.29413543 392.91106772 487.3039748 384.77571024 489.11584252
  \c 383.20051654 489.31729134 382.84312441 489.53967874 381.31464567 489.51473386
  \c 374.93645102 489.38849764 370.27737827 486.79150866 364.25366929 484.92170079
  \c 363.08989228 484.58154331 362.13536126 485.15338583 361.42743307 485.43405354
  \o\s
  \end{tikzpicture}
  \endgroup
}

\ExplSyntaxOn
\newcommand\setfroufrou[1]{%
  \str_case:nnF{#1}{
      {}{\relax}
      {fleuron}{\def\@froufrouOrnament{\@froufrouFleuron}}
      {simplefleuron}{\def\@froufrouOrnament{\@froufrouSimpleFleuron}}
      {asterism}{\def\@froufrouOrnament{\@froufrouAsterism}}
      {tightasterism}{\def\@froufrouOrnament{\@froufrouTightAsterism}}
      {trueasterism}{\def\@froufrouOrnament{\@froufrouTrueAsterism}}
      {dinkus}{\def\@froufrouOrnament{\@froufrouDinkus}}%
      {closing}{\def\@froufrouOrnament{\@froufrouClosing}}%
  }{\def\@froufrouOrnament{#1}}%
}
\ExplSyntaxOff

% I see no reason to make these different, but feel free to change this :)
\def\@froufrouspacebefore{\vskip 22pt plus 7pt minus 5pt}
\def\@froufrouspaceafter{\@froufrouspacebefore}

% The starred form means "indent the first line of the next paragraph"
% (\if@afterindent is read by \@afterheading)
\NewDocumentCommand{\froufrou}{s O{}}{%
  % Make sure we left horizontal mode.
  \nopagebreak[4]\par

  \IfBooleanTF{#1}{\@afterindenttrue}{\@afterindentfalse}

  \nopagebreak[4]\@froufrouspacebefore\nopagebreak[4]

  % Start a new group to (1) reset \doublespacing, \parskip, and
  % \baselineskip, so spacing is independent from the previous text
  % settings and (2) so that using #1 to change the ornament only
  % affects the current call. Then, start yet another group only
  % for the ornament because font size changes in it should not
  % affect spacing either.
  \bgroup
    \setfroufrou{#2}%
    \normalsize
    \ifdefvoid{\setstretch}{}{\setstretch{\setspace@singlespace}}% normally 1
    \setlength{\parskip}{0pt}
    \noindent\centering\bgroup\@froufrouOrnament\egroup\par
  \egroup

  \nopagebreak[4]\@froufrouspaceafter\nopagebreak[4]

  % Next paragraph's \doublespacing, \baselineskip, and \parskip
  % should not affect spacing.
  \@froufrouFixSpacingAfter

  % Breaking after the separator is acceptable as a last resort. Since
  % we use a lot of vertical space before/after it, not allowing this
  % break might lead to poor results in some cases.
  \nopagebreak[3]

  % Emulate the behavior of \section, \subsection etc: prevent
  % the first line of the next paragraph from being indented
  % and absolutely forbid a club line in the next paragraph.
  \@afterheading
}

% For compatibility with older versions of this package.
\NewDocumentCommand{\frufru}{s O{}}{%
  \IfBooleanTF{#1}{\froufrou*[#2]}{\froufrou[#2]}%
}

\newcommand\@froufrouFixSpacingAfter{
  % The next \par will add \parskip and \baselineskip. We want to
  % (1) eliminate \parskip so that spacing does not change if it
  % is nonzero and (2) add the "normal" \baselineskip, even if the
  % text is set using \doublespacing. These adjustments may be off
  % if font size, \parskip or \baselineskip are changed before the
  % next paragraph.

  \nopagebreak[4]\vskip -\parskip

  \ifdefvoid{\setstretch}
    {}
    {
      \bgroup
        % \singlespacing may add an extra \baselineskip; let's
        % avoid surprises and use \setstrech instead.
        \setstretch {\setspace@singlespace}%  normally 1
        \nopagebreak[4]\vskip \baselineskip
      \egroup

      \nopagebreak[4]\vskip -\baselineskip
    }
}

% Trying to accept a custom ornament as a package option is not such a
% great idea: first, it has to be expandable; second, this may become
% a problem if we want to add more options to the class in the future.
\DeclareOption{fleuron}{\setfroufrou{fleuron}}
\DeclareOption{simplefleuron}{\setfroufrou{simplefleuron}}
\DeclareOption{asterism}{\setfroufrou{asterism}}
\DeclareOption{tightasterism}{\setfroufrou{tightasterism}}
\DeclareOption{trueasterism}{\setfroufrou{trueasterism}}
\DeclareOption{dinkus}{\setfroufrou{dinkus}}
\DeclareOption{closing}{\setfroufrou{closing}}
\DeclareOption*{\PackageWarning{froufrou}{Unknown option `\CurrentOption'}}
\ExecuteOptions{fleuron}
\ProcessOptions\relax

%    \end{macrocode}
% \Finale