% ------------------------------------------------------- %
% - 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-01-06} % Creation: 2023-11-29
    {1.1.0}
    {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}

\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{amsthm}[2017/09]


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


\RequirePackage{tcolorbox}[2023/06/19]
\tcbuselibrary{minted, breakable, skins}


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


% -- 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


% -- 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}


% -- 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{}%
  }%
}


% -- FOCUS ON SOME 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@rmk@title}


% :: IMPORTANT :: %

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


% :: NOTE :: %

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


% :: TIP :: %

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


% :: CUATION :: %

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


% :: WARNING :: %

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


% -- 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


% :: 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%
}


% :: 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,
% 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
    enhanced,
    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 date or nothing)
%     #3 : the second material (a version number 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
        \__tdoc_translate_date:n { #2 }
      \par
    }

    \vspace{1pt}

    \par
      #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}
}


% :: 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
                         {#3}      % Date
                         {#2}      % Version
                         {-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?

% :: 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 }{
  \IfBlankT{#1}{
    \msg_fatal:nn { tdoc } { changes-topic-missing-title }
  }

  \textbf{
    \textsc{#1.}
  }

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


% :: CHANGES - NEW THINGS :: %

%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "New"
%              translated into the good language.
%%%
\NewDocumentEnvironment{tdocnew}{}{
  \begin{tdoctopic}{\tutodoc@trans@chges@new}
}{
  \end{tdoctopic}
}


% :: CHANGES - UPDATE :: %

%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "Update"
%              translated into the good language.
%%%
\NewDocumentEnvironment{tdocupdate}{}{
  \begin{tdoctopic}{\tutodoc@trans@chges@update}
}{
  \end{tdoctopic}
}


% :: CHANGES - BREAK :: %

%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "Break"
%              translated into the good language.
%%%
\NewDocumentEnvironment{tdocbreak}{}{
  \begin{tdoctopic}{\tutodoc@trans@chges@break}
}{
  \end{tdoctopic}
}


% :: CHANGES - PROBLEM :: %

%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "Problem"
%              translated into the good language.
%%%
\NewDocumentEnvironment{tdocprob}{}{
  \begin{tdoctopic}{\tutodoc@trans@chges@pb}
}{
  \end{tdoctopic}
}


% :: CHANGES - FIX :: %

%%%
% prototype::
%     :see: env.tdoctopic
%
%     :action: similar to the \env ''tdoctopic'' with the title "Fix"
%              translated into the good language.
%%%
\NewDocumentEnvironment{tdocfix}{}{
  \begin{tdoctopic}{\tutodoc@trans@chges@fix}
}{
  \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}
}