% ********************************************************* %
% ** This is file `tutodoc.sty' generated automatically. ** %
% **                                                     ** %
% ** Copyright (C) 2023-2024 by Christophe BAL           ** %
% **                                                     ** %
% ** This file may be distributed and/or modified under  ** %
% ** the conditions of the GNU 3 License.                ** %
% ********************************************************* %

\ProvidesExplPackage
  {tutodoc}
  {2024-09-25}  % Creation: 2023-11-29
  {1.3.0}
  {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}


% =================== %
% == PACKAGES USED == %
% =================== %

\RequirePackage[
  top            = 2.5cm,
  bottom         = 2.5cm,
  left           = 2.5cm,
  right          = 2.5cm,
  marginparwidth = 2cm,
  marginparsep   = 2mm,
  heightrounded
]{geometry}%
 [2020-01-02]

\RequirePackage[raggedright]%
               {titlesec}%
               [2021/07/05]

\RequirePackage{tocbasic}

\RequirePackage{xcolor}%
               [2022/06/12]

\RequirePackage{hyperref}%
               [2023-02-07]


% We delegate the management of quoting to the `csquotes' package,
% which takes care of the linguistic parameters.
\RequirePackage{csquotes}%
               [2022-09-14]


\RequirePackage{fontawesome5}%
               [2022-05-02]

\RequirePackage{keytheorems}%
               [2024/09/19]

\RequirePackage[svgnames]%
               {xcolor}%
               [2023/11/15]

\RequirePackage{tcolorbox}%
               [2024/07/10]

\tcbuselibrary{breakable, skins}


\RequirePackage{clrstrip}%
               [2021-08-28]


\RequirePackage{minted2}% Temporary patch? minted3 seems very slow8

\RequirePackage{tcolorbox}%
               [2024/07/10]

\tcbuselibrary{minted, breakable, skins}


\RequirePackage{fontawesome5}%
               [2022-05-02]

\RequirePackage{marginnote}%
               [2023-09-07]


% ======================= %
% == AVAILABLE OPTIONS == %
% ======================= %

% ----------------- %
% -- LOCALE LANG -- %
% ----------------- %

\ExplSyntaxOn

% ::::::::::::::::::: %
% :: SOME MESSAGES :: %
% ::::::::::::::::::: %

\msg_set:nnnn { tdoc } { package-option-lang-unknown }
  { Unknown ~ language. }
  { See ~ the ~ documentation ~ for ~ the ~ supported ~ languages. }


% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
% ::::::::::::::::::::::: %

\str_new:N \l_tdoc_opt_lang_str

%%%
% We define the key-val options that will be exposed by the package.
%%%
\keys_define:nn { tdoc } {
  lang .choices:nn =
    { french, english }
    {
      \tl_set:Nn \l_tdoc_opt_lang_str
                 { \tl_use:N \l_keys_choice_tl }
    },
  lang .initial:n = english,
  lang / unknown .code:n =
    \msg_error:nnxxx { tdoc } { package-option-lang-unknown }
      { lang }             % Name of choice key
      { french, english }  % Valid choices
      { \exp_not:n {#1} }  % Invalid choice given
}

\ProcessKeyOptions[tdoc]

\ExplSyntaxOff


% =============== %
% == MAIN CODE == %
% =============== %

% --------------------- %
% -- LOCALE SETTINGS -- %
% --------------------- %

\NewDocumentCommand{\tutodoc@colon}{}{:}

% We must take care of the colons, babel and spacing.
\@ifpackageloaded{babel}{
  \iflanguage{french}{
    \RenewDocumentCommand{\tutodoc@colon}{}{\babelshorthand{:}}
  }{}
}{}

\ExplSyntaxOn

\input{tutodoc-locale-main-\l_tdoc_opt_lang_str.cfg.sty}

\ExplSyntaxOff


% ---------------------- %
% -- GENERAL SETTINGS -- %
% ---------------------- %

\setlength{\parindent}{0cm}


% ----------- %
% -- LINKS -- %
% ----------- %

\hypersetup{
  colorlinks,
  citecolor = orange!75!black,
  filecolor = orange!75!black,
  linkcolor = orange!75!black,
  urlcolor  = orange!75!black
}


% --------------- %
% -- TOC & Co. -- %
% --------------- %

\ifcsundef{chapter}%
          {}%
          {\renewcommand\thechapter{\Alph{chapter}.}}

\renewcommand\thesection{\Roman{section}.}
\renewcommand\thesubsection{\arabic{subsection}.}
\renewcommand\thesubsubsection{\roman{subsubsection}.}

\titleformat{\paragraph}[hang]%
            {\normalfont\normalsize\bfseries}%
            {\theparagraph}{1em}%
            {}

\titlespacing*{\paragraph}%
              {0pt}%
              {3.25ex plus 1ex minus .2ex}%
              {0.5em}

% Source
%  * https://tex.stackexchange.com/a/558025/6880
\DeclareTOCStyleEntries[
  raggedentrytext,
  linefill = \hfill,
  indent   = 0pt,
  dynindent,
  numwidth = 0pt,
  numsep   = 1ex,
  dynnumwidth
]{tocline}{
  chapter,
  section,
  subsection,
  subsubsection,
  paragraph,
  subparagraph
}

\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section}


% --------------------------- %
% -- COLOR TRANSFORMATIONS -- %
% --------------------------- %

%%%
% prototype::
%     #1 : one color following the ''xcolor'' format.
%
%     :return: a "darker" version of the color ''#1''.
%%%
\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{%
  #1!50!black%
}


%%%
% prototype::
%     #1 : one color following the ''xcolor'' format.
%
%     :return: a "transparent" version of the color `#1`.
%%%
\NewExpandableDocumentCommand{\tdoclightcolor}{m}{%
  #1!5%
}


% ------------- %
% -- QUOTING -- %
% ------------- %

%%%
% prototype::
%     #1 : a text to quote.
%
% For example, ''\tdocquote{Something}'' prints something like **"Something"**.
%%%
\NewDocumentCommand{\tdocquote}{m}{%
  \enquote{\emph{#1}}%
}


% ------------------------------ %
% -- EXPLAINING ENGLISH NAMES -- %
% ------------------------------ %

%%%
% prototype::
%     #1 : an english text to explain in another language.
%
%     :extra: this macro has a star version.
%
% For example, if the language chosen is ''french'', we have
% the following outputs.
%
%     1) ''\tdocinEN{Something}'' prints
%        **"Something" en anglais**.
%
%     2) ''\tdocinEN*{Something}'' just prints
%        **"Something"**.
%        This can be useful in a case like
%        ''\tdocinEN*{Something} et \tdocinEN{Another thing}''
%        which gives
%        **"Something" et "Another thing" en anglais**.
%%%
\NewDocumentCommand{\tdocinEN}{s m}{%
  \tdocquote{#2}%
  \IfBooleanF{#1}{% No star used.
    \ \tutodoc@trans@in@EN{}%
  }%
}


% ----------------------------------- %
% -- SOBER HIGHLIGHTING OF CONTENT -- %
% ----------------------------------- %

% ::::::::::::::::::::::::::::::: %
% :: EXAMPLE - HIDDEN VERSIONS :: %
% ::::::::::::::::::::::::::::::: %

%%%
% See the \doc of the macro ''\newtheorem'' from the package ''amsthm''
% to have \infos about the environment ''@@tdocexa@nb''.
%%%
\newtheorem{@@tdocexa@nb}{\tutodoc@trans@exa@title}%
                         [subsubsection]

%%%
% We redefine the counter associated to the environment ''@@tdocexa@nb''
% to obtain only one single arabic number.
%%%
\renewcommand{\the@@tdocexa@nb}{\arabic{@@tdocexa@nb}}


%%%
% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
% to have \infos about the environment ''@@tdocexa@no@nb''.
%%%
\newtheorem*{@@tdocexa@no@nb}{\tutodoc@trans@exa@title}


% :::::::::::::::::::::::::::::: %
% :: EXAMPLE - PUBLIC VERSION :: %
% :::::::::::::::::::::::::::::: %

\ExplSyntaxOn

\msg_set:nnnn { tdoc } { env-tdocexa-unknown-option }
  { Unknown ~ rafters ~ option. }
  { See ~ the ~ documentation ~ for ~ the ~ supported ~ options. }

\NewDocumentEnvironment{ tdocexa } { D<>{nb} O{} } {
  \str_case:nnF { #1 } {
    { nb   } {
      \begin{@@tdocexa@nb}[#2]
    }
    { nonb } {
      \begin{@@tdocexa@no@nb}[#2]
    }
  }{
    \msg_error:nn { tdoc } { env-tdocexa-unknown-option }
  }
}{
  \str_case:nnF { #1 } {
    { nb } {
      \end{@@tdocexa@nb}
    }
    { nonb } {
      \end{@@tdocexa@no@nb}
    }
  }{}
}

\ExplSyntaxOff


% :::::::::::: %
% :: REMARK :: %
% :::::::::::: %

%%%
% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
% to have \infos about the environment ''tdocrem''.
%%%
\newtheorem*{tdocrem}{\tutodoc@trans@rem@title}


% -------------------------------------- %
% -- COLORFUL HIGHLIGHTING OF CONTENT -- %
% -------------------------------------- %

% ::::::::::::::::: %
% :: ABSTRACTION :: %
% ::::::::::::::::: %

% Sources used.
%    + https://tex.stackexchange.com/a/727022/6880
%    + https://tex.stackexchange.com/a/682332/6880

\tcbset{
  tutodoc-focus-color-style/.style = {
    breakable,
    enhanced,
%    fonttitle    = \itshape,
%    halign title = center,
    fontupper    = \color{\tdocdarkcolor{#1}},
    colback      = \tdoclightcolor{#1},
    colframe     = #1!75!black!45,
    shadow       = {.75mm}{-.75mm}{0mm}{black!30},
% We want to use the same color for the footnotes in the frame.
    before upper = {\let\default@color\current@color},
 }
}


% ::::::::::::::::::::::::::::::::::::: %
% :: LET'S GO BACK TO THE REAL WORLD :: %
% ::::::::::::::::::::::::::::::::::::: %

\ExplSyntaxOn

\prop_set_from_keyval:Nn \__g_tutodoc_focus_color_prop {
  note      = cyan,
  tip       = ForestGreen,%lime,
  imp = orange,
  caution   = violet,
  warn      = red,
}

\prop_set_from_keyval:Nn \__g_tutodoc_focus_icon_prop {
  note      = \faInfoCircle,
  tip       = \faLightbulb,
  imp       = \faHighlighter,
  caution   = \faBiohazard,
  warn      = \faSkullCrossbones,
}

\prop_map_inline:Nn \__g_tutodoc_focus_color_prop {
  \newkeytheorem{tdoc#1}[
    numbered  = false,
%  tcolorbox-no-titlebar can be used.
    tcolorbox = {tutodoc-focus-color-style=#2},
    name      = {
      \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } \kern3.5pt
      \use:c { tutodoc@trans@#1@title }
    },
  ]
}

\ExplSyntaxOff


% ---------------------------------------------- %
% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- %
% ---------------------------------------------- %

%%%
% prototype::
%     #1 : the name of a class
%
%     :action: ''\tdoccls{myclass}'' prints verb::''myclass''.
%%%
\NewDocumentCommand{\tdoccls}{m}{%
  \texttt{#1}%
}


%%%
% prototype::
%     #1 : the name of a package
%
%     :action:''\tdocpack{mypack}'' prints verb::''mypack''.
%%%
\NewDocumentCommand{\tdocpack}{m}{%
  \texttt{#1}%
}


%%%
% prototype::
%     #1 : the name of a macro
%
%     :action: ''\tdocmacro{mymacro}'' prints verb::''\mymacro''.
%%%
\NewDocumentCommand{\tdocmacro}{m}{%
  \texttt{\textbackslash{}#1}%
}


%%%
% prototype::
%     #1 : hard typed options with the good delimiters
%     #2 : the name of an environment
%
%     :action: ''\tdocenv{myenv}'' prints verb::''\begin{myenv} ... \end{myenv}''
%              or something like verb::''\begin{myenv}<opt1> ... \end{myenv}'',
%              the spaces being secable.
%%%
%
% Cleaner code from https://tex.stackexchange.com/a/703379/6880 .
\NewDocumentCommand{\tdocenv}{O{}m}{%
  \texttt{\string\begin\string{#2\string}#1 %
          \!\!...\@\!\!\! %
          \string\end\string{#2\string}}%
}


% ------------------------- %
% -- EXPLAINING PREFIXES -- %
% ------------------------- %

\ExplSyntaxOn

% :::::::::::::: %
% :: MESSAGES :: %
% :::::::::::::: %

\msg_set:nnnn { bdoc } { prefixwhy-bad-format }
{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
{ You ~ must ~ use ~ one ~ single ~ point. }


% :::::::::::::::::::: %
% :: PREFIX FROM... :: %
% :::::::::::::::::::: %

%%%
% prototype::
%     #1 : a prefix and a suffix separated by one colon.
%
%     :action: ''\tdocprewhy{pre.fix}'' prints verb::''pre''.fix.
%%%
\NewDocumentCommand{\tdocprewhy}{m}{%
% Do we have 2 parts?
  \seq_set_split:Nnn \l_tmpa_seq { . } { #1 }

  \int_set:Nn \l_tmpa_int
              {\int_eval:n {\seq_count:N \l_tmpa_seq}}

  \if_int_compare:w \l_tmpa_int = 2
  \else:
    \msg_error:nn { bdoc } { prefixwhy-bad-format }
  \fi:

% Let's go.
  \seq_pop:NN \l_tmpa_seq \l_tmpa_tl
  \seq_pop:NN \l_tmpa_seq \l_tmpb_tl

  \textbf{\tdocpre{\tl_use:N \l_tmpa_tl}\kern.5pt\textperiodcentered\kern.5pt{\tl_use:N \l_tmpb_tl}}
}

\ExplSyntaxOff


% ::::::::::::::::::::: %
% :: JUST ONE PREFIX :: %
% ::::::::::::::::::::: %

%%%
% prototype::
%     #1 : just a prefix
%
%     :action: ''\tdocpre{pre}'' only prints verb::''pre''.
%              This can be useful in a case like
%              ''\tdocpre{pre} comes from \tdocprewhy{pre}{fix}''
%              which prints:
%              verb::''pre'' comes from verb::''pre''-fix.
%%%
\NewDocumentCommand{\tdocpre}{m}{%
  \texttt{#1}%
}


% ------------------------ %
% -- GENERAL FORMATTING -- %
% ------------------------ %

% :::::::::::::::::::::::: %
% :: TEXT INSIDE A RULE :: %
% :::::::::::::::::::::::: %

\ExplSyntaxOn

%%%
% prototype::
%     #1 : a text
%     #2 : a color
%
%     :action: this macro adds two horizontal lines on either side of the text.
%              The final output is centered.
%
% note::
%     The code used comes from
%     cf::''this post ;
%           https://tex.stackexchange.com/a/604708/6880''.
%%%
\NewDocumentCommand{\tdocruler}{m m}{
  \par
  {
    \centering
      \scriptsize
      \itshape
      \bfseries
      \color{#2}

      \hbox_set:Nn \l_tmpa_box { \,\, #1 \,\, }
      \dim_set:Nn  \l_tmpa_dim {
        .35 \linewidth - .5 \box_wd:N \l_tmpa_box
      }

      \rule[.75pt] { \dim_use:N \l_tmpa_dim }
                   { 2.5pt }
      \box_use:N   \l_tmpa_box
      \rule[.75pt] { \dim_use:N \l_tmpa_dim }
                   { 2.5pt }
      \par
  }
}

\ExplSyntaxOff


% ::::::::::::::::::::::::::: %
% :: INTERNAL ENVIRONMENTS :: %
% ::::::::::::::::::::::::::: %

%%%
% prototype::
%     #1 : the text before the real output
%     #2 : the text after the real output
%     #3 : one color following the ''xcolor'' format.
%          This color is used to set the one for the decorated texts printed
%          corresponding to the two first arguments.
%
%     :action: this environment just adds its content processed by \latex
%              between centered materials produced by the macro ''\tdocruler''
%              such as to stress the start and the end of the content.
%%%
\NewDocumentEnvironment{tdoc@showcase@basic}{m m m}{
  \tdocruler{#1}{\tdocdarkcolor{#3}}
  \nopagebreak\medskip\nopagebreak
}{
  \nopagebreak\medskip\nopagebreak
  \tdocruler{#2}{\tdocdarkcolor{#3}}
}


%%%
% prototype::
%     #1 : the text before the real output
%     #2 : the text after the real output
%     #3 : the color following the ''xcolor'' format.
%          This color is used to set the ones of the stripe and the decorated
%          texts printed (see the two first arguments).
%
%     :action: this environment adds a page-width colored stripe in the
%              background of the environment content processed by \latex.
%              This stripe is preceded and followed by centered materials
%              produced by the macro ''\tdocruler'' such as to stress the
%              start and the end of the content.
%%%

\NewDocumentEnvironment{tdoc@showcase@colorstrip}{m m m}{
  \begin{colorstrip}{\tdoclightcolor{#3}}
    \begin{tdoc@showcase@basic}{#1}{#2}{#3}
}{
    \end{tdoc@showcase@basic}
  \end{colorstrip}
}


\ExplSyntaxOn

% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
% ::::::::::::::::::::::: %

\tl_new:N   \l_tdoc_showcase_before_tl
\tl_new:N   \l_tdoc_showcase_after_tl
\tl_new:N   \l_tdoc_showcase_color_tl
\bool_new:N \l_tdoc_showcase_nostripe_bool


%%%
% prototype::
%     :see: env.tdocshowcase
%
% We define the key-val options that will be exposed by the \env
% ''tdocshowcase''.
%%%
\keys_define:nn { tdoc/showcase } {
% Texts.
  before .tl_set:N   = \l_tdoc_showcase_before_tl,
  before .initial:n  = \tutodoc@trans@latex@show@start,
  after  .tl_set:N   = \l_tdoc_showcase_after_tl,
  after  .initial:n  = \tutodoc@trans@latex@show@end,
% Decorations.
  color    .tl_set:N   = \l_tdoc_showcase_color_tl,
  color    .initial:n  = cyan,
  nostripe .bool_set:N = \l_tdoc_showcase_nostripe_bool,
  nostripe .initial:n  = false,
}


% :::::::::::::::::::::::::::::: %
% :: SHOWCASE FROM TYPED CODE :: %
% :::::::::::::::::::::::::::::: %

% prototype::
%     #1 : the key-value options.
%
%     :action: this \env formats \latex code, given as an argument,
%              by framing it with texts decorated by ''\tdocruler'',
%              in order to clearly identify a rendering used as an
%              example.
%              It is also possible to have a coloured strip of the width
%              of the page in the background of the content.
%
%     :see: env.tdoc@showcase@basic ,
%           env.tdoc@showcase@colorstrip
%%%
\NewDocumentEnvironment{tdocshowcase}{ O{} }{
  \group_begin:
    \keys_set:nn { tdoc/showcase } { #1 }

    \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
      \begin{tdoc@showcase@basic}%
        { \tl_use:N \l_tdoc_showcase_before_tl }%
        { \tl_use:N \l_tdoc_showcase_after_tl }%
        { \tl_use:N \l_tdoc_showcase_color_tl }
    }{
      \begin{tdoc@showcase@colorstrip}%
        { \tl_use:N \l_tdoc_showcase_before_tl }%
        { \tl_use:N \l_tdoc_showcase_after_tl }%
        { \tl_use:N \l_tdoc_showcase_color_tl }
    }
}{
    \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
      \end{tdoc@showcase@basic}
    }{
      \end{tdoc@showcase@colorstrip}
    }
  \group_end:
}


% :::::::::::::::::::::::: %
% :: SHOWCASE FROM FILE :: %
% :::::::::::::::::::::::: %

%%%
% prototype::
%     #1 : the key-value options supported by the ''tdocshowcase'' \env.
%     #2 : the path of a file
%
%     :see: env.tdocshowcase
%%%
\NewDocumentCommand{\tdocshowcaseinput}{O{} m}{
  \group_begin:
    \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl

    \exp_last_unbraced:NNV \tdocshowcase [\l_tmpa_tl]
      \input{#2}
    \endtdocshowcase
  \group_end:
}

\ExplSyntaxOff


% -------------------- %
% -- LATEX EXAMPLES -- %
% -------------------- %

% ::::::::::::::::::::::::::::: %
% :: INLINE SHORT LATEX CODE :: %
% ::::::::::::::::::::::::::::: %

%%%
% See the \doc of the macro ''\newmintinline'' from the package ''minted''
% to have \infos about the macro ''tdocinlatex''.
%%%
\newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4}


% ::::::::::::::::::::::::::::::::::::::::::::::: %
% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: %
% ::::::::::::::::::::::::::::::::::::::::::::::: %

\ExplSyntaxOn

%%%
% In the following easy-to-understand macro, we use one fictive ''tcolorbox''
% style such as to indicate an unknown ''tdoc'' style to the user.
% For example, this can give one message similar to the following one.
%
% term::
%     Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option
%     "NOT-A-STYLE"' and I am going to ignore it. Perhaps you misspelled it.
%
%     See the pgfkeys package documentation for explanation.
%%%
\NewExpandableDocumentCommand{\tutodoc@latex@listing@formating}{ m }{
  \str_case:nnF { #1 } {
    { sbs  } { listing ~ side ~ text }
    { code } { listing ~ only }
    { std  } { listing ~ and ~ text }
  } { tdoclatex ~ bad ~ option ~ "#1" }
}

\ExplSyntaxOff


% ::::::::::::::::::::::::::::::::: %
% :: THE TCOLORBOX LISTING STYLE :: %
% ::::::::::::::::::::::::::::::::: %

%%%
% note::
%     The settings used come from the following sources.
%         * https://tex.stackexchange.com/a/604821/6880
%         * https://tex.stackexchange.com/a/327983/6880
%%%
\tcbset{
  tdoclatex_tcbstyle/.style = {
    minted language = latex,
    breakable,
    enhanced,
% Code and output
    colback = yellow!5,
% Frame
    colframe = darkgray,
    shadow   = {.75mm}{-.75mm}{0mm}{black!30},
    arc      = .75mm,
    left     = 1mm, right = 1mm,
    bottom   = 1mm, top   = 1mm,
% We can use  ''sharp corners'' to obtain an "old school" style.
%
% Separating line
    segmentation style = {
      gray,
      dash pattern = {on 5pt off 2.5pt},
      line width   = 1.25pt
    },
    #1
  },
}


% ::::::::::::::::::::::::::::::::::: %
% :: TCOLORBOX LISTING ENVIRONMENT :: %
% ::::::::::::::::::::::::::::::::::: %

%%%
% prototype::
%     #1 : the style to be used (code only, code and output side by side,
%          or the standard style corresponding to the code followed by
%          its output)
%        @ #1 in [code, sbs, std]
%
% note::
%     See the \doc of the macro ''\newtcblisting'' from the package
%     ''tcolorbox'' to have \infos about the environment ''tdoclatex''.
%%%
\newtcblisting{tdoclatex}[1][std]{%
  tdoclatex_tcbstyle = \tutodoc@latex@listing@formating{#1}
}


% :::::::::::::::::::::::::::::::::::::: %
% :: TCOLORBOX IMPORTED LISTING MACRO :: %
% :::::::::::::::::::::::::::::::::::::: %

%%%
% prototype::
%     #1 : :see: \newtcblisting{tdoclatex}.
%     #2 : the path of the file to input and format.
%
% note::
%     See the \doc of the macro ''\newtcbinputlisting'' from the package
%     ''tcolorbox'' to have more \infos about the macro ''\tdoclatexinput''.
%%%
\newtcbinputlisting{\tdoclatexinput}[2][std]{
  listing file = {#2},
  tdoclatex_tcbstyle = \tutodoc@latex@listing@formating{#1}
}


% -------------------------- %
% -- LATEX REAL USE CASES -- %
% -------------------------- %

\ExplSyntaxOn

% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
% ::::::::::::::::::::::: %

\tl_new:N \l_tdoc_listing_explain_tl

%%%
% prototype::
%     :see: macro.tdoclatexshow
%
% We define the key-val options that will be exposed by ''\tdoclatexshow''.
%%%
\keys_define:nn { tdoc/latexshow } {
  explain .tl_set:N   = \l_tdoc_listing_explain_tl,
  explain .initial:n  = { \tutodoc@trans@this@gives \tutodoc@colon },
}


% ::::::::::::::::::::: %
% :: LATEXSHOW MACRO :: %
% ::::::::::::::::::::: %

%%%
% prototype::
%     #1 : the key-value options supported by the ''tdocshowcase'' \env,
%          plus one allowing you to change the description of a line
%          printed between the code and its focused output.
%     #2 : the path of a file
%
%     :see: env.tdocshowcase ,
%           macro.tdoclatexinput
%%%
\NewDocumentCommand{\tdoclatexshow}{O{} m}{
  \group_begin:
    \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl

    \tdoclatexinput[code]{#2}

    \tl_use:N \l_tdoc_listing_explain_tl

% Source: https://tex.stackexchange.com/a/696700/6880
    \exp_last_unbraced:NNV \tdocshowcaseinput [\l_tmpa_tl] {#2}
  \group_end:
}

\ExplSyntaxOff


% -- CHANGES - WHEN? --%

\ExplSyntaxOn

% :::::::::::::: %
% :: MESSAGES :: %
% :::::::::::::: %

\msg_set:nnnn { tdoc } { date-bad-format  }
  { Bad ~ format ~ for ~ a ~ date. }
  { Use ~ YYYY-MM-DD. }


% ::::::::::::::::: %
% :: MARGIN NOTE :: %
% ::::::::::::::::: %

\reversemarginpar{}

%%%
% prototype::
%     #1 : the color of the margin note
%     #2 : the first material (a version number or nothing)
%     #3 : the second material (a date or nothing)
%     #4 : the last negative vertical spacing for the 2nd rule
%
%     :action: this macro factorizes the printing of the changes
%              in the left margin.
%
%     :see: \__tdoc_translate_date:n
%%%
\NewDocumentCommand{\tutodoc@new@change@margin}{m m m m}{
  \marginnote{
    \color{#1}
    \scriptsize
    \centering

    \vspace{0pt}
    \rule{1.65cm}{.95pt}
    \vspace{-2.9pt}

    \IfBlankTF{#2}{}{
      \par
        #2
      \par
    }

    \IfBlankTF{#3}{}{
      \IfBlankTF{#2}{}{
        \vspace{1pt}
      }

      \par
        \__tdoc_translate_date:n { #3 }
      \par
    }

    \vspace{#4}
    \rule{1.65cm}{.95pt}
  }[-.345cm]
}


%%%
% prototype::
%     :action: this function checks if we have something like
%              ''YYYY-MM-DD'' and then it calls the function
%              ''\__tdoc_translate_date_process:w'' to finish
%              the job.
%
%     :see: \__tdoc_translate_date_process:w
%%%
\cs_new:Nn \__tdoc_translate_date:n {
  \regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{
    \__tdoc_translate_date_process:w #1 \q_stop
  }{
    \msg_error:nn { tdoc } { date-bad-format }
  }
}


%%%
% prototype::
%     :action: this function extracts year, month and day in something
%              like ''YYYY-MM-DD'' and then it calls ''\tutodoc@trans@date''
%              to use the format expected for a "localised" date.
%%%
\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop {
    \tutodoc@trans@date{#1}
                       {#2}
                       {#3}
}

\ExplSyntaxOff


% :::::::::::::::::::::: %
% :: VERSION AND DATE :: %
% :::::::::::::::::::::: %

%%%
% prototype::
%     #1 : the color of the margin note
%     #2 : a version number
%     #3 : a date ''YYYY-MM-DD''
%
%     :action: this macro prints a margin note showing a version number
%              below a date, and the optional argument is used to colorize
%              all this text.
%
% warning::
%     The date must use an english formatting like ''2021-07-14''. This allows
%     to parse the date such as to display it following the standard convention
%     of the language chosen when loading the package.
%%%
\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{
  \tutodoc@new@change@margin{#1}      % Color
                            {#2}      % Version
                            {#3}      % Date
                            {-4.25pt} % Last negative vertical spacing
}


% :::::::::: %
% :: DATE :: %
% :::::::::: %

%%%
% prototype::
%     #1 : the color of the margin note
%     #2 : a date ''YYYY-MM-DD''
%
%     :action: this macro is similar to ''\tdocversion'' except that it just
%              prints a date.
%%%
\NewDocumentCommand{\tdocdate}{O{blue} m}{
  \tutodoc@new@change@margin{#1}      % Color
                            {#2}      % Date
                            {}        % Version
                            {-5.35pt} % Last negative spacing
}


% --------------------- %
% -- CHANGES - WHAT? -- %
% --------------------- %

\ExplSyntaxOn

% :::::::::::::: %
% :: MESSAGES :: %
% :::::::::::::: %

\msg_set:nnnn { tdoc } { changes-topic-missing-title }
  { Missing ~ title. }
  { One ~ single ~ title ~ must ~ be ~ indicated. }


% ::::::::::::::::::::: %
% :: CHANGES - TOPIC :: %
% ::::::::::::::::::::: %

%%%
% prototype::
%     #1 : a title that will be followed by a colon.
%
%     :action: this environment prints some ¨infos about specific changes
%              achieved in a new version (no special formatting is applied).
%%%
\NewDocumentEnvironment{tdoctopic}{ m O{} }{
  \IfBlankT{#1}{
    \msg_fatal:nn { tdoc } { changes-topic-missing-title }
  }

  \textbf{
    \IfBlankF{#2}{#2\kern3.5pt}%
    \textsc{#1.}
  }

  \begin{itemize}
}{
  \end{itemize}
}


% :::::::::::::::::::::::::: %
% :: CHANGES - NEW THINGS :: %
% :::::::::::::::::::::::::: %

\prop_set_from_keyval:Nn \__g_tutodoc_topic_change_prop {
  break  = \faCodeBranch,
  fix    = \faWrench,
  new    = \faGem,
  prob   = \faFire*,
  update = \faMagic,
}


%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "New"
%              translated into the good language.
%%%
\prop_map_inline:Nn \__g_tutodoc_topic_change_prop {
  \NewDocumentEnvironment{ tdoc#1 } {} {
    \begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } [ #2 ]
  }{
    \end{tdoctopic}
  }
}

\ExplSyntaxOff


% ----------------- %
% -- DECORATIONS -- %
% ----------------- %

% Source for \addvspace{\medskipamount} instead of \medskip.
%    * https://tex.stackexchange.com/a/705938/6880

%%%
% prototype::
%     :action: this macro draws a centered horizontal rule with a height
%              of qty::''0.75 pt'', and a width equal to half of the current
%              text width.
%              Extra vertical spaces are added above and below the rule.
%%%
\NewDocumentCommand{\tdocsep}{}{
  \par\addvspace{\medskipamount}
  \hfill\rule{0.5\textwidth}{0.75pt}\hfill\null
  \medskip
  \smallskip
}


%%%
% prototype::
%     :action: this macro adds a tiny vertical spacing.
%%%
\NewDocumentCommand{\tdocxspace}{}{
  \vspace{0.25em}
}