summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tutodoc/code/tutodoc.sty
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tutodoc/code/tutodoc.sty')
-rw-r--r--macros/latex/contrib/tutodoc/code/tutodoc.sty1026
1 files changed, 1026 insertions, 0 deletions
diff --git a/macros/latex/contrib/tutodoc/code/tutodoc.sty b/macros/latex/contrib/tutodoc/code/tutodoc.sty
new file mode 100644
index 0000000000..83b6c88433
--- /dev/null
+++ b/macros/latex/contrib/tutodoc/code/tutodoc.sty
@@ -0,0 +1,1026 @@
+% ------------------------------------------------------- %
+% - This is file `tutodoc.sty' generated automatically. - %
+% - - %
+% - Copyright (C) 2023 by Christophe BAL - %
+% - - %
+% - This file may be distributed and/or modified under - %
+% - the conditions of the GNU 3 License. - %
+% ------------------------------------------------------- %
+
+\ProvidesExplPackage
+ {tutodoc}
+ {2023-11-29} % Creation: 2023-11-29
+ {1.0.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{\tdoc@colon}{}{:}
+
+% We must take care of the colons, babel and spacing.
+\@ifpackageloaded{babel}{
+ \iflanguage{french}{
+ \RenewDocumentCommand{\tdoc@colon}{}{\babelshorthand{:}}
+ }{}
+}{}
+
+\ExplSyntaxOn
+
+\input{tdoc-locale-\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.
+ \ \tdoc@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}{\tdoc@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}{\tdoc@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}{\tdoc@trans@rmk@title}
+
+
+% :: IMPORTANT :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocimportant''.
+%%%
+\newtheorem*{tdocimportant}{\tdoc@trans@important@title}
+
+
+% :: NOTE :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocnote''.
+%%%
+\newtheorem*{tdocnote}{\tdoc@trans@note@title}
+
+
+% :: TIP :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdoctip''.
+%%%
+\newtheorem*{tdoctip}{\tdoc@trans@tip@title}
+
+
+% :: CUATION :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdoccaution''.
+%%%
+\newtheorem*{tdoccaution}{\tdoc@trans@caution@title}
+
+
+% :: WARNING :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocwarn''.
+%%%
+\newtheorem*{tdocwarn}{\tdoc@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: ''\tdocenv{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.
+%%%
+\NewDocumentCommand{\tdocenv}{O{}m}{%
+ \texttt{\textbackslash{}begin\{#2\}#1 %
+ \!...\! %
+ \textbackslash{}end\{#2\}}%
+}
+
+
+% -- 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}}
+ \medskip
+}{
+ \medskip
+ \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 = \tdoc@trans@latex@show@start,
+ after .tl_set:N = \l_tdoc_showcase_after_tl,
+ after .initial:n = \tdoc@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}{}
+
+
+% :: 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{\tdoc@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 = \tdoc@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 = \tdoc@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 = { \tdoc@trans@this@gives \tdoc@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{\tdoc@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 ''\tdoc@trans@date''
+% to use the format expected for a "localised" date.
+%%%
+\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop {
+ \tdoc@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{}}{
+ \tdoc@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}{
+ \tdoc@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}{\tdoc@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}{\tdoc@trans@chges@update}
+}{
+ \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}{\tdoc@trans@chges@fix}
+}{
+ \end{tdoctopic}
+}
+
+\ExplSyntaxOff
+
+
+% -- DECORATIONS -- %
+
+%%%
+% 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}{}{
+ \medskip
+ \hfill\rule{0.5\textwidth}{0.75pt}\hfill
+ \medskip
+ \smallskip
+}
+
+
+%%%
+% prototype::
+% :action: this macro adds a tiny vertical spacing.
+%%%
+\NewDocumentCommand{\tdocxspace}{}{
+ \vspace{0.25em}
+}