% ==================== %
% == RESOURCES USED == %
% ==================== %


\begin{filecontents*}[overwrite]{gallery-showcase-bw.tex}
\documentclass[10pt, a4paper, theme = bw]{tutodoc}

% -- FORDOC -- %

\newcommand\thisstyle{bw}

\newcommand\myexrmktext{
    \tdocdate{2024-10-23}
    Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal.
}

\newcommand\myadmotext{
    \tdocversion{1.6.0}[2024-10-23]
    Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance.
}

\newcommand\myhighlightedtext{
    Que dire\,%
    \footnote{
        N'oublions pas les notes de bas de page...
    }?
    Je ne sais pas, mais en tout cas, il semble sympathique de montrer ce que peut donner telle mise en forme, ou telle autre. Non ?
}


\begin{document}

{\Huge\bfseries Le thème \texttt{"\thisstyle"}}

\section{Mettre en avant, versionner et dater}

\ExplSyntaxOn

\seq_map_inline:Nn \g__tutodoc_focus_std_seq {
    \subsection*{tdoc#1}

    \myexrmktext

    \begin{tdoc#1}
        \myhighlightedtext
    \end{tdoc#1}

    \myexrmktext
}

\ifcsundef{g__tutodoc_focus_color_seq}{
    \prop_map_inline:Nn \g__tutodoc_focus_color_prop {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
} {
    \seq_map_inline:Nn \g__tutodoc_focus_color_seq {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
}

\ExplSyntaxOff

\section{Des codes \LaTeX}

Il est indispensable de pouvoir montrer des cas d'utilisation en \LaTeX.

\begin{tdoclatex}
Voir du code \LaTeX\ mis en forme, c'est sympa : $E = m c^2$ ou $\pi \neq \frac{3}{14}$.
\end{tdoclatex}


On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ?

\begin{tdoclatex}[sbs]
Voir du code \LaTeX\ mis en forme,
c'est sympa : $E = m c^2$ ou
$\pi \neq \frac{3}{14}$.
\end{tdoclatex}

\end{document}

\end{filecontents*}

\begin{filecontents*}[overwrite]{gallery-showcase-color.tex}
\documentclass[10pt, a4paper, theme = color]{tutodoc}

% -- FORDOC -- %

\newcommand\thisstyle{color}

\newcommand\myexrmktext{
    \tdocdate{2024-10-23}
    Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal.
}

\newcommand\myadmotext{
    \tdocversion{1.6.0}[2024-10-23]
    Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance.
}

\newcommand\myhighlightedtext{
    Que dire\,%
    \footnote{
        N'oublions pas les notes de bas de page...
    }?
    Je ne sais pas, mais en tout cas, il semble sympathique de montrer ce que peut donner telle mise en forme, ou telle autre. Non ?
}


\begin{document}

{\Huge\bfseries Le thème \texttt{"\thisstyle"}}

\section{Mettre en avant, versionner et dater}

\ExplSyntaxOn

\seq_map_inline:Nn \g__tutodoc_focus_std_seq {
    \subsection*{tdoc#1}

    \myexrmktext

    \begin{tdoc#1}
        \myhighlightedtext
    \end{tdoc#1}

    \myexrmktext
}

\ifcsundef{g__tutodoc_focus_color_seq}{
    \prop_map_inline:Nn \g__tutodoc_focus_color_prop {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
} {
    \seq_map_inline:Nn \g__tutodoc_focus_color_seq {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
}

\ExplSyntaxOff

\section{Des codes \LaTeX}

Il est indispensable de pouvoir montrer des cas d'utilisation en \LaTeX.

\begin{tdoclatex}
Voir du code \LaTeX\ mis en forme, c'est sympa : $E = m c^2$ ou $\pi \neq \frac{3}{14}$.
\end{tdoclatex}


On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ?

\begin{tdoclatex}[sbs]
Voir du code \LaTeX\ mis en forme,
c'est sympa : $E = m c^2$ ou
$\pi \neq \frac{3}{14}$.
\end{tdoclatex}

\end{document}

\end{filecontents*}

\begin{filecontents*}[overwrite]{gallery-showcase-dark.tex}
\documentclass[10pt, a4paper, theme = dark]{tutodoc}

% -- FORDOC -- %

\newcommand\thisstyle{dark}

\newcommand\myexrmktext{
    \tdocdate{2024-10-23}
    Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal.
}

\newcommand\myadmotext{
    \tdocversion{1.6.0}[2024-10-23]
    Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance.
}

\newcommand\myhighlightedtext{
    Que dire\,%
    \footnote{
        N'oublions pas les notes de bas de page...
    }?
    Je ne sais pas, mais en tout cas, il semble sympathique de montrer ce que peut donner telle mise en forme, ou telle autre. Non ?
}


\begin{document}

{\Huge\bfseries Le thème \texttt{"\thisstyle"}}

\section{Mettre en avant, versionner et dater}

\ExplSyntaxOn

\seq_map_inline:Nn \g__tutodoc_focus_std_seq {
    \subsection*{tdoc#1}

    \myexrmktext

    \begin{tdoc#1}
        \myhighlightedtext
    \end{tdoc#1}

    \myexrmktext
}

\ifcsundef{g__tutodoc_focus_color_seq}{
    \prop_map_inline:Nn \g__tutodoc_focus_color_prop {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
} {
    \seq_map_inline:Nn \g__tutodoc_focus_color_seq {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
}

\ExplSyntaxOff

\section{Des codes \LaTeX}

Il est indispensable de pouvoir montrer des cas d'utilisation en \LaTeX.

\begin{tdoclatex}
Voir du code \LaTeX\ mis en forme, c'est sympa : $E = m c^2$ ou $\pi \neq \frac{3}{14}$.
\end{tdoclatex}


On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ?

\begin{tdoclatex}[sbs]
Voir du code \LaTeX\ mis en forme,
c'est sympa : $E = m c^2$ ou
$\pi \neq \frac{3}{14}$.
\end{tdoclatex}

\end{document}

\end{filecontents*}

\begin{filecontents*}[overwrite]{gallery-showcase-draft.tex}
\documentclass[10pt, a4paper, theme = draft]{tutodoc}

% -- FORDOC -- %

\newcommand\thisstyle{draft}

\newcommand\myexrmktext{
    \tdocdate{2024-10-23}
    Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal.
}

\newcommand\myadmotext{
    \tdocversion{1.6.0}[2024-10-23]
    Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance.
}

\newcommand\myhighlightedtext{
    Que dire\,%
    \footnote{
        N'oublions pas les notes de bas de page...
    }?
    Je ne sais pas, mais en tout cas, il semble sympathique de montrer ce que peut donner telle mise en forme, ou telle autre. Non ?
}


\begin{document}

{\Huge\bfseries Le thème \texttt{"\thisstyle"}}

\section{Mettre en avant, versionner et dater}

\ExplSyntaxOn

\seq_map_inline:Nn \g__tutodoc_focus_std_seq {
    \subsection*{tdoc#1}

    \myexrmktext

    \begin{tdoc#1}
        \myhighlightedtext
    \end{tdoc#1}

    \myexrmktext
}

\ifcsundef{g__tutodoc_focus_color_seq}{
    \prop_map_inline:Nn \g__tutodoc_focus_color_prop {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
} {
    \seq_map_inline:Nn \g__tutodoc_focus_color_seq {
        \subsection*{tdoc#1}

        \myadmotext

        \begin{tdoc#1}
            \myhighlightedtext
        \end{tdoc#1}

        \myadmotext
    }
}

\ExplSyntaxOff

\section{Des codes \LaTeX}

Il est indispensable de pouvoir montrer des cas d'utilisation en \LaTeX.

\begin{tdoclatex}
Voir du code \LaTeX\ mis en forme, c'est sympa : $E = m c^2$ ou $\pi \neq \frac{3}{14}$.
\end{tdoclatex}


On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ?

\begin{tdoclatex}[sbs]
Voir du code \LaTeX\ mis en forme,
c'est sympa : $E = m c^2$ ou
$\pi \neq \frac{3}{14}$.
\end{tdoclatex}

\end{document}

\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-dating.tex}
Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...

\medskip % ATTENTION ! Ceci évite le chevauchement.

\tdocdate{2023-09-24}

Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...

\medskip % ATTENTION ! Ceci évite le chevauchement.

\tdocdate[gray]{2020-05-08}

Bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli...

Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo...

Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu...
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice-icon.tex}
\begin{tdoctopic}{À cacher}<\faEyeSlash>
% Une icône venant de fontawesome5.
    \item Info 1...
    \item Info 2...
\end{tdoctopic}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
\begin{tdoctopic}{La fin des icônes}
    \item Info 1...
    \item Info 2...
\end{tdoctopic}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-update.tex}
\begin{tdocupdate}
    \item Info 1...
    \item Info 2...
\end{tdocupdate}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-versioning.tex}
\tdocversion[red]{10.2.0-beta}[2023-12-01]

Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...

\bigskip % ATTENTION ! Ceci évite le chevauchement.

\tdocversion{10.2.0-alpha}

Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-side-effect.tex}
\tdocversion[red]{1.2.3}[2024-10-29]%
\paragraph{Avant c'est problématique.}
Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...


\paragraph{Après c'est mal placé.}%
\tdocversion[red]{1.2.3}[2024-10-29]

Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...


\paragraph{Pas de solution miracle.\tdocversion[red]{1.2.3}[2024-10-29]}

Bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli,
bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli,
bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli,
bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli...


\paragraph{Gestion manuelle du problème.\tdocversion{1.2.3}[2024-10-29]<-.745cm>}

Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo...
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-first.tex}
\tdocstartproj{Première version du projet.}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-tech.tex}
\begin{tdoctech}
    \item Info 1...
    \item Info 2...
\end{tdoctech}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-what-n-when.tex}
\begin{tdoctech}[col  = red,
                 date = 2024-10-29]
    \item Info 1...
    \item Info 2...
\end{tdoctech}

\begin{tdocupdate}[col     = ForestGreen,
                   version = 1.2.3]
    \item Info 1...
    \item Info 2...
\end{tdocupdate}

\begin{tdoctopic}{À cacher}<\faEyeSlash>%
                           [version = 4.5.6, date = 2025-11-30]
    \item Info 1...
    \item Info 2...
\end{tdoctopic}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex}
\begin{tdocbreak}
    \item Info 1...
    \item Info 2...
\end{tdocbreak}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-pb.tex}
\begin{tdocprob}
    \item Info 1...
    \item Info 2...
\end{tdocprob}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-new.tex}
\begin{tdocnew}
    \item Info 1...
    \item Info 2...
\end{tdocnew}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-fix.tex}
\begin{tdocfix}
    \item Info 1...
    \item Info 2...
\end{tdocfix}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-exa-leavevmode.tex}
\begin{tdocexa}
    \leavevmode
    \begin{enumerate}
        \item Point 1.

        \item Point 2.
    \end{enumerate}
\end{tdocexa}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-important.tex}
\begin{tdocimp}
    Un truc important sans danger.
\end{tdocimp}

\begin{tdocimp}[Mini titre]
    Utile ?
\end{tdocimp}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-note.tex}
\begin{tdocnote}
    Un truc utile à vous dire...
\end{tdocnote}

\begin{tdocnote}[Mini titre]
    Utile ?
\end{tdocnote}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-caution.tex}
\begin{tdoccaut}
    Prudence, prudence...
\end{tdoccaut}

\begin{tdoccaut}[Mini titre]
    Utile ?
\end{tdoccaut}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-tip.tex}
\begin{tdoctip}
    Une astuce.
\end{tdoctip}

\begin{tdoctip}[Mini titre]
    Utile ?
\end{tdoctip}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-warn.tex}
\begin{tdocwarn}
    Evitez les dangers...
\end{tdocwarn}

\begin{tdocwarn}[Mini titre]
    Utile ?
\end{tdocwarn}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-exa.tex}
\begin{tdocexa}
    Un exemple...
\end{tdocexa}

\begin{tdocexa}[Mini titre]
    Utile ?
\end{tdocexa}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-leavevmode-items.tex}
\begin{tdoctip}[Peu élégant]
    \begin{enumerate}
        \item Point 1.
        \item Point 2.
    \end{enumerate}
\end{tdoctip}
VERSUS.
\begin{tdoctip}[Plus élégant]
    \begin{enumerate}[wide]
        \item Point 1.
        \item Point 2.
    \end{enumerate}
\end{tdoctip}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-admonitions-rmk.tex}
\begin{tdocrem}
    Juste une remarque...
\end{tdocrem}

\begin{tdocrem}[Mini titre]
    Utile ?
\end{tdocrem}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-latexshow-options.tex}
\tdoclatexshow[explain   = Ce qui vient est coloré...,
               before    = Rendu ci-après.,
               after     = Rendu fini.,
               colstripe = orange,
               coltext   = blue!70!black]
               {examples-listing-xyz.tex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-ABC.tex}
\begin{tdoclatex}[sbs]
    $A = B + C$
\end{tdoclatex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-xyz.tex}
% Juste une démo.
$x y z = 1$
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-strange.tex}
\begin{tdoclatex}[std]
    [Étrange... Ou pas !]
\end{tdoclatex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex}
\begin{tdoclatex}
    \string[Étrange... Ou pas !]
\end{tdoclatex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-customized.tex}
\begin{tdocshowcase}[before    = Mon début,
                     after     = Ma fin à moi,
                     colstripe = red,
                     coltext   = orange!75!black]
    Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
\end{tdocshowcase}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-hook.tex}
\begin{tdocshowcase}
    \string[Cela fonctionne...]
\end{tdocshowcase}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-no-clrstrip-customized.tex}
\begin{tdocshowcase}[nostripe,
                     before    = Mon début,
                     after     = Ma fin à moi,
                     colstripe = green,
                     coltext   = purple]
    Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
\end{tdocshowcase}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-external.tex}
Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-default.tex}
\begin{tdocshowcase}
    \bfseries Un peu de code \LaTeX.

    \bigskip

    \emph{\large Fin de l'affreuse démo.}
\end{tdocshowcase}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-no-clrstrip.tex}
\begin{tdocshowcase}[nostripe]
    Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
\end{tdocshowcase}
\end{filecontents*}


% ======================== %
% == SOURCE FOR THE DOC == %
% ======================== %

\documentclass[10pt, a4paper]{tutodoc}

% Community tools
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage{enumitem}

\usepackage[french]{babel, varioref}
\frenchsetup{StandardItemLabels=true}

\usepackage{multicol}

\usepackage{pdfpages}

% Some useful commands.
\newcommand\thisproj{\tdoccls{tutodoc}}
\newcommand\thisrepo{\url{https://github.com/bc-tools/for-latex/tree/tutodoc}}
\newcommand\thismonorepo{\url{https://github.com/bc-tools/for-latex}}

\NewDocumentCommand{\trademark}{m}{\texttt{#1}}

\newcommand\ctan{\href{https://ctan.org/}{\trademark{CTAN}}}
\newcommand\git{\trademark{git}}
\newcommand\pdf{\trademark{PDF}}


% Source.
%    * https://tex.stackexchange.com/a/604698/6880

\NewDocumentCommand{ \tdocbasicinputDOC }{ m }{%
    Considérons le code suivant.

    \tdoclatexinput[code]{#1}

    Ceci produira ce qui suit.

    \input{#1}
}


% Source.
%    * https://tex.stackexchange.com/a/604698/6880

\NewDocumentCommand{ \tdocextrarulerDOC }{ m }{%
    \par
    {
        \centering
        \color{green!50!black}%
        \leavevmode
        \kern.075\linewidth
        \leaders\hrule height3.25pt\hfill\kern0pt
        \footnotesize\itshape\bfseries\space\ignorespaces#1\unskip\space
        \leaders\hrule height3.25pt\hfill\kern0pt
        \kern.075\linewidth
        \par
    }
}

\NewDocumentEnvironment{ tdocshowcaseDOC }
                       { O{ Début du rendu dans cette doc. }
                         O{ Fin du rendu dans cette doc. } }{
        \tdocextrarulerDOC{#1}
        \nopagebreak\smallskip\nopagebreak
}{
        \nopagebreak\smallskip\nopagebreak
        \tdocextrarulerDOC{#2}
}


\NewDocumentCommand{\mailsubject}{m}%  <-- Translate me!
  {sujet \tdocquote{\texttt{tutodoc - CONTRIB - #1}}}

% Source: https://tex.stackexchange.com/a/424061/6880

\newcommand{\FTdirO}{}
\def\FTdirO(#1,#2,#3){%
  \FTfile(#1,{\color{blue!40!black}\faFolderOpen\hspace{-.35pt}}{\hspace{0.2em}#3})
  (tmp.west)++(0.8em,-0.4em)node(#2){}
  (tmp.west)++(1.5em,0)
  ++(0,-1.3em)
}

\newcommand{\FTdirC}{}
\def\FTdirC(#1,#2,#3){%
  \FTfile(#1,{\color{blue!40!black}\faFolder\hspace{.75pt}}{\hspace{0.2em}#3})
  (tmp.west)++(0.8em,-0.4em)node(#2){}
  (tmp.west)++(1.5em,0)
  ++(0,-1.3em)
}

\newcommand{\FTfile}{}
\def\FTfile(#1,#2){%
  node(tmp){}
  (#1|-tmp)++(0.6em,0)
  node(tmp)[anchor=west,black]{\tt #2}
  (#1)|-(tmp.west)
  ++(0,-1.2em)
}

\newcommand{\FTroot}{}
\def\FTroot{tmp.west}

\newcommand\contribtranslatedirtree{
  \begin{tikzpicture}%
    \draw[color=black, thick]
% en        : parent = \FTroot
% normal dir: (parentID, currentID, label)
% file      :       (parentID, label)
      \FTdirO(\FTroot,root,translate){
        \FTdirC(root,changes,changes){
        }
        \FTdirO(root,en,en) {
          \FTdirC(en,api,api) {
          }
          \FTdirC(en,doc,doc) {
          }
        }
        \FTdirC(root,fr,fr){
        }
        \FTdirC(root,status,status){
          \FTdirO(status,en,en) {
            \FTfile(en,api.yaml)
            \FTfile(en,manual.yaml)
          }
          \FTdirC(status,fr,fr){
          }
        }
        \FTfile(root,README.md)
        \FTfile(root,LICENSE.txt)
      };
  \end{tikzpicture}
}


\begin{document}


\title{La classe \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe, BAL}
\date{30 oct. 2024 - Version 1.6.2}

\maketitle


\begin{abstract}
    La classe \thisproj{}\,%
    \footnote{
        Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} qui se traduit en \tdocquote{documentation de type tutoriel}.
    }
    est utilisée par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel\,%
    \footnote{
        L'idée est de produire un fichier \texttt{PDF} efficace à parcourir pour des besoins ponctuels. C'est généralement ce que l'on attend d'une documentation liée au codage.
    }
    via un rendu sobre pour une lecture sur écran.

    \smallskip

    \noindent
    \emph{\textbf{Remarque :} cette documentation est aussi disponible en anglais.}

    \tdocsep

    {\small\itshape
        \vspace{-5pt}
        \begin{center}
            \textbf{Abstract.}
        \end{center}

        The \thisproj{} class\,%
        \footnote{
            The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
        }
        is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style\,%
        \footnote{
            The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected of coding documentation.
        }
        using a sober rendering for reading on screen.
    
        \smallskip
    
        \noindent
        \emph{\textbf{Remark :} this documentation is also available in French.}
    }
\end{abstract}

\medskip

\begin{center}
\small
\begin{minipage}{.9\textwidth}
\begin{tdocnote}[Derniers changements]
\begin{tdocnew}
	\item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} ont un nouvel argument final facultatif \tdocinlatex{<voffset>} pour choisir un décalage vertical spécifique.

	\item De meilleurs environnements pour indiquer les modifications apportées.
	\begin{enumerate}
		\item Les nouvelles clés facultatives \tdocinlatex{col}\,, \tdocinlatex{date} et \tdocinlatex{version} permettent d'indiquer la date et la version d'une modification apportée à un sujet spécifique.

		\item Utilisation de \tdocmacro{paragraph} pour le titre.
	\end{enumerate}
\end{tdocnew} 


\begin{tdocupdate}
	\item Changements : la police des notes de marge aura toujours une forme normale.

	\item Ornement : utilisation d'un \tdocinlatex{\cleaders} pour éviter les lignes orphelines en bas de page.
\end{tdocupdate}
\end{tdocnote}
\end{minipage}
\end{center}


\newpage
\tableofcontents
\newpage


\section{Mises en forme générales imposées}

\subsection{Géométrie de la page}

Le package \tdocpack{geometry} est chargé avec les réglages suivants.


\begin{tdoclatex}[code]
\RequirePackage[
  top            = 2.5cm,
  bottom         = 2.5cm,
  left           = 2.5cm,
  right          = 2.5cm,
  marginparwidth = 2cm,
  marginparsep   = 2mm,
  heightrounded
]{geometry}
\end{tdoclatex}


\subsection{Titre et table des matières}

Les packages \tdocpack{titlesec} et \tdocpack{tocbasic} sont réglés comme suit.


\begin{tdoclatex}[code]
\RequirePackage[raggedright]{titlesec}

% ...
\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}
\end{tdoclatex}


\subsection{Liens dynamiques}

Le package \tdocpack{hyperref} est importé en coulisse avec les réglages ci-dessous.


\begin{tdoclatex}[code]
\newcommand{\tdoclinkcolor}{NavyBlue!85!white}

\hypersetup{
  colorlinks,
  citecolor = \tdoclinkcolor,
  filecolor = \tdoclinkcolor,
  linkcolor = \tdoclinkcolor,
  urlcolor  = \tdoclinkcolor
}
\end{tdoclatex}


\section{Quelle langue est utilisée par la classe \thisproj\ ?}

Cette documentation charge le package \tdocpack{babel} via \tdocinlatex|\usepackage[french]{babel}|\,.
Dès lors, la classe \thisproj\ repère \tdocinlatex|fr| comme langue principale utilisée par \tdocpack{babel}.%
\footnote{
    Techniquement, on utilise \tdocinlatex|\BCPdata{language}| qui renvoie une langue au format court.
}
Comme cette langue fait partie de la liste des langues prises en compte, voir ci-dessous, la classe \thisproj\ produira les effets attendus.

\begin{multicols}{3}
    \begin{itemize}
        \item \tdocinlatex|en| : anglais.
        \item \tdocinlatex|es| : espagnol.
        \item \tdocinlatex|fr| : français.
    \end{itemize}
\end{multicols}
                    


\begin{tdoccaut}
    Si le choix de la langue principale n'est pas faite dans le préambule, le mécanisme employé échouera avec des effets de bord non voulus (voir l'avertissement qui suit).
\end{tdoccaut}


\begin{tdocwarn}
    Lorsqu'une langue n'est pas prise en compte par \thisproj, un message d'avertissement est émis, et l'anglais est alors choisi comme langue vis-à-vis de \thisproj.
\end{tdocwarn}


\begin{tdocnote}
    Le mécanisme utilisé devrait être compatible avec le package \tdocpack{polyglossia}.
\end{tdocnote}


\section{Cela veut dire quoi en \tdocquote{anglais}}

Penser aux non-anglophones est bien, même si ces derniers se font de plus en plus rares.


\begin{tdoclatex}
Cool et top signifient \tdocinEN*{cool} et \tdocinEN{top}.
\end{tdoclatex}


La macro \tdocmacro{tdocinEN} et sa version étoilée s'appuient sur \tdocmacro{tdocquote} : par exemple, \tdocquote{sémantique} s'obtient via \tdocinlatex|\tdocquote{sémantique}| .


\begin{tdocnote}
    Le texte \tdocquote{en anglais} est traduit dans la langue détectée par \thisproj.
\end{tdocnote}


\section{Choisir son thème}

Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \tdocinlatex{theme = <choix>} où \tdocinlatex{<choix>} peut prendre les valeurs suivantes.

\begin{itemize}
    \item \tdocinlatex|bw| :
    ce thème est de type noir-et-blanc avec certaines nuances de gris.

    \item \tdocinlatex|color| :
    ce thème est coloré, \emph{c'est la valeur par défaut}.

    \item \tdocinlatex|dark| :
    ce thème est sombre, idéal pour se reposer les yeux.

    \item \tdocinlatex|draft| :
    ce thème est juste pour une impression papier à la recherche d'erreurs de contenu pas forcément simples à débusquer devant son écran.
\end{itemize}


\begin{tdocnote}
    A la fin de ce document, après l'historique des changements, vous trouverez une galerie de cas d'utilisation de ces différents thèmes : se rendre à l'annexe page \pageref{tutodoc-theme-gallery}.
\end{tdocnote}


% ----------------------------- %
% -- AT END DOCUMENT - START -- %
% ----------------------------- %

% The following AT-END-DOCUMENT lines of codes have been generated
% automatically. Don't judge their relative beauty...

\AtEndDocument{

% An annex page for a pretty doc.
\newpage

% Source.
%     + https://tex.stackexchange.com/a/8547/6880
\bgroup
    \titleformat{\section}[block]{\Huge\bfseries\filcenter}{}{1em}{}
    \phantomsection\section*{Annexe -- Galerie des thèmes}%
    \label{tutodoc-theme-gallery}
    \addcontentsline{toc}{section}{Annexe -- Galerie des thèmes}%
\egroup

\bigskip

\begin{tdocnote}
    Chaque exemple est un \pdf\ de deux pages exactement qui a été directement inséré dans ce document (ne soyez donc pas surpris par les numéros de page).
\end{tdocnote}

\newpage

% Let's build the PDFs.
\immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-bw}

\immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-color}

\immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-dark}

\immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-draft}

% The gallery starts here...
\includepdf[
    pages=1-2,
    fitpaper=true
]{gallery-showcase-bw}

\includepdf[
    pages=1-2,
    fitpaper=true
]{gallery-showcase-color}

\includepdf[
    pages=1-2,
    fitpaper=true
]{gallery-showcase-dark}

\includepdf[
    pages=1-2,
    fitpaper=true
]{gallery-showcase-draft}

}

% --------------------------- %
% -- AT END DOCUMENT - END -- %
% --------------------------- %

\section{Mettre en avant du contenu}

\begin{tdocnote}
    Les environnements présentés dans cette section
    \footnote{
        La mise en forme provient du package \tdocpack{keytheorems}.
    }
    ajoutent un court titre indiquant le type d'informations fournies.
    Ce court texte sera toujours traduit dans la langue repérée par la classe \thisproj.
\end{tdocnote}



\subsection{Du contenu dans le flot de la lecture}

\begin{tdocimp}
    Tous les environnements présentés dans cette section partagent le même compteur qui sera remis à zéro dès qu'une section de niveau au moins égale à une \tdocinlatex|\section| sera ouverte.
\end{tdocimp}



\subsubsection{Des exemples}

Des exemples numérotés, si besoin, s'indiquent via \tdocenv{tdocexa} qui propose un argument optionnel pour ajouter un mini-titre.
Voici deux usages possibles.

\tdoclatexinput[sbs]{examples-admonitions-exa.tex}



\begin{tdoctip}
    Il peut parfois être utile de revenir à la ligne dès le début du contenu. Le code suivant montre comment faire (ce tour de passe-passe reste valable pour l'environnement \verb#tdocrem# présenté juste après). Noter au passage que la numérotation suit celle de l'exemple précédent comme souhaité.
\end{tdoctip}

\tdoclatexinput[sbs]{examples-admonitions-exa-leavevmode.tex}



%\subsection{Du contenu dans le flot de la lecture}

\subsubsection{Des remarques}

Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'environnement \tdocenv*{tdocexa} comme le montre l'exemple suivant.


\tdoclatexinput[sbs]{examples-admonitions-rmk.tex}



\subsection{Du contenu tape-à-l'oeil}
\label{tutodoc-admonitions}

\begin{tdocnote}
    La mise en forme proposée ici est celle par défaut, mais d'autres sont possible en changeant de thème : voir la galerie de cas d'utilisation dans l'annexe page \pageref{tutodoc-theme-gallery}.
    Quant aux icônes, elles sont obtenues via le package \tdocpack{fontawesome5}, et la macro \tdocmacro{tdocicon} gère l'espacement vis-à-vis du texte.
    \footnote{
        Par exemple,
        \tdocinlatex|\fbox{\tdocicon{\faBed}{Fatigué}}|
        produit\,
        \fbox{\tdocicon{\faBed}{Fatigué}}\,.
    }
\end{tdocnote}



\subsubsection{Une astuce}

L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'employer.

\tdoclatexinput[sbs]{examples-admonitions-tip.tex}



\smallskip


\begin{tdoctip}
    Quelque fois, un contenu mis en avant peut se réduire à une liste. Dans ce cas, la mise en forme peut être améliorée comme suit où nous utilisons l'option \tdocinlatex{wide} du package \tdocpack{enumitem}.

    \tdoclatexinput[sbs]{examples-admonitions-leavevmode-items.tex}

\end{tdoctip}


\foreach \sectitle/\desc/\filename in {
    {Note informative}/% <-- Translate me!
    {L'environnement \tdocenv*{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.}/% <-- Translate me!
    note,
    %
    {Un truc important}/% <-- Translate me!
    {L'environnement \tdocenv*{tdocimp} permet d'indiquer quelque chose d'important mais sans danger.}/% <-- Translate me!
    important,
    %
    {Avertir d'un point très délicat}/% <-- Translate me!
    {L'environnement \tdocenv*{tdoccaut} sert à indiquer un point délicat à  l'utilisateur. Voici comment l'employer.}/%<-- Translate me!
    caution,
    %
    {Avertir d'un danger}/% <-- Translate me!
    {L'environnement \tdocenv*{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.}/% <-- Translate me!
    warn%
} {
    \subsubsection{\sectitle}

    \desc

    \tdoclatexinput[sbs]{examples-admonitions-\filename.tex}

}


\section{Indiquer des packages, des classes, des macros ou des environnements}

Voici ce qu'il est possible de taper de façon sémantique.


\begin{tdoclatex}[sbs]
\tdoccls{maclasse} sert à...           \\
\tdocpack{monpackage} est pour...      \\
\tdocmacro{unemacro} permet de...      \\
\tdocenv{env} produit...               \\
\tdocenv[{[opt1]<opt2>}]{env}          \\
Juste \tdocenv*{env}...                \\
Enfin \tdocenv*[{[opt1]<opt2>}]{env}...
\end{tdoclatex}


\begin{tdocrem}
    Contrairement à \tdocmacro{tdocinlatex}, les macros \tdocmacro{tdocenv} et \tdocmacro{tdocenv*} ne colorent pas le texte produit.
    De plus, \tdocinlatex{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin.
\end{tdocrem}


\begin{tdocwarn}
    L'argument optionnel de la macro \tdocmacro{tdocenv} est copié-collé
    \footnote{
        Se souvenir que tout est possible ou presque dorénavant.
    }
    lors du rendu. Ceci peut donc parfois nécessiter d'utiliser des accolades protectrices comme dans l'exemple ci-dessus.
\end{tdocwarn}



\section{Origine d'un préfixe ou d'un suffixe}

Pour expliquer les noms retenus, rien de tel que d'indiquer et expliciter les courts préfixes et suffixes employés. Ceci se fait facilement comme suit.


\begin{tdoclatex}[sbs]
\tdocpre{sup} est relatif à...    \\
\tdocprewhy{sup.erbe} signifie... \\
\emph{\tdocprewhy{sup.er} pour...}
\end{tdoclatex}


\begin{tdocrem}
    Le choix du point pour scinder un mot permet d'utiliser des mots avec un tiret comme dans \tdocinlatex+\tdocprewhy{ca.sse-brique}+ qui donne \tdocprewhy{ca.sse-brique}.
\end{tdocrem}


\section{Un rendu en situation réelle}
\label{tutodoc-showcase}

Il est parfois utile d'obtenir directement le rendu d'un code dans la documentation. Ceci nécessite que ce type de rendu soit dissociable du texte donnant des explications.



\subsection{Avec une bande colorée}

\begin{tdocexa}[Avec les textes par défaut]
    Il peut être utile de montrer un rendu réel directement dans un document.
    \footnote{
        Typiquement lorsque l'on fait une démo.
    }
    Ceci se tape via \tdocenv{tdocshowcase} comme suit.

    \tdoclatexinput[code]{examples-showcase-default.tex}


    On obtient alors le rendu suivant.
    \footnote{
        En coulisse, la bande est créée sans effort grâce au package \tdocpack{clrstrip}.
    }

    \medskip

    \input{examples-showcase-default.tex}

\end{tdocexa}


\begin{tdocrem}
    Voir la section \ref{tutodoc-latexshow} page \pageref{tutodoc-latexshow} pour obtenir facilement un code suivi de son rendu réel comme dans l'exemple précédent.
\end{tdocrem}


\begin{tdocnote}
    Les textes explicatifs s'adaptent à la langue détectée par \thisproj.
\end{tdocnote}


\begin{tdocexa}[Changer les couleurs et/ou les textes par défaut]
    \leavevmode

    \tdoclatexinput[code]{examples-showcase-customized.tex}


    Ceci produira ce qui suit.

    \medskip

    \input{examples-showcase-customized.tex}

\end{tdocexa}


\begin{tdocnote}
    Dans l'exemple précédent, le texte utilise bien l'orange assombri proposé. Par contre, le rouge sert de base pour obtenir les couleurs utilisées pour la bande : les transformations utilisées dépendent du thème choisi.%
    \footnote{
        Par exemple, les thèmes \tdocinlatex{bw} et \tdocinlatex{draft} ne tiennent pas compte de la clé \tdocinlatex{colstripe} !
    }
    %
    Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est employée.

    \begin{tdoclatex}[std]
        \tdocruler[red]{Un pseudo-titre décoré}
    \end{tdoclatex}
\end{tdocnote}


\begin{tdocwarn}
    Avec les réglages par défaut, si le code \LaTeX\ à mettre en forme commence par un crochet ouvrant, il faudra user de \tdocmacro{string} comme dans l'exemple suivant.

    \tdoclatexinput[code]{examples-showcase-hook.tex}


    Ceci produira ce qui suit.
\end{tdocwarn}

\input{examples-showcase-hook.tex}



\subsection{Sans bande colorée}

Le rendu de \tdocenv{tdocshowcase} avec une bande colorée peut ne pas convenir, ou parfois ne pas être acceptable malgré le travail fait par \tdocpack{clrstrip}.
Il est possible de ne pas utiliser une bande colorée comme nous allons le voir tout de suite.


\begin{tdocexa}
    L'emploi de \tdocenv[{[nostripe]}]{tdocshowcase} demande de ne pas faire appel à \tdocpack{clrstrip}.
    Voici un exemple d'utilisation.

    \tdoclatexinput[code]{examples-showcase-no-clrstrip.tex}


    Ceci produira ce qui suit.

    \medskip

    \input{examples-showcase-no-clrstrip.tex}

\end{tdocexa}


\begin{tdocexa}[Changer les couleurs et/ou les textes par défaut]
    \leavevmode

    \tdoclatexinput[code]{examples-showcase-no-clrstrip-customized.tex}


    Ceci produira l'horreur suivante.

    \medskip

    \input{examples-showcase-no-clrstrip-customized.tex}

\end{tdocexa}


\subsection{En important le code \LaTeX}

Pour obtenir des rendus en important le code depuis un fichier externe, au lieu de le taper, il suffit d'employer la macro \tdocmacro{tdocshowcaseinput} dont l'option reprend la syntaxe de celle de \tdocenv{tdocshowcase} et l'argument obligatoire correspond au chemin du fichier.


\begin{tdocexa}
    Ce qui suit a été obtenu via \tdocinlatex+\tdocshowcaseinput{external.tex}+.

    \medskip

    \tdocshowcaseinput{examples-showcase-external.tex}


    \medskip

    Quant à \tdocinlatex+\tdocshowcaseinput[colstripe = red, coltext = orange!75!black]{external.tex}+\,, ceci produira le changement de couleur observable ci-après.

    \medskip

    \tdocshowcaseinput[colstripe = red, coltext = orange!75!black]{examples-showcase-external.tex}

\end{tdocexa}


\section{Cas d'utilisation en \LaTeX}

Documenter un package ou une classe se fait efficacement via des cas d'utilisation montrant à la fois du code et le résultat correspondant.%
\footnote{
    La mise en forme des codes se fait via le package \tdocpack{minted}.
}


%\begin{tdoccaut}
%    La version 3 de \tdocpack{minted} ne peut pas être prise en compte pour le moment car elle comporte des bugs : voir \url{https://github.com/gpoore/minted/issues/401}. On force donc l'usage de la version 2 de \tdocpack{minted}.
%\end{tdoccaut}



\subsection{Codes \tdocquote{en ligne}}
\label{tutodoc-listing-inline}

La macro \tdocmacro{tdocinlatex}
\footnote{
    Le nom de la macro \tdocmacro{tdocinlatex} vient de \tdocquote{\tdocprewhy{in.line} \LaTeX} soit \tdocinEN{\LaTeX\ en ligne}.
}
permet de taper du code en ligne via un usage similaire à \tdocmacro{verb} ou bien comme une macro standard (voir la gestion des accolades dans le dernier cas ci-dessous).
Voici des exemples d'utilisation.


\begin{tdoclatex}[sbs]
    1: \tdocinlatex|$a^b = c$|               \\
    2: \tdocinlatex+\tdocinlatex|$a^b = c$|+ \\
    3: \tdocinlatex{\tdocinlatex{$a^b = c$}}
\end{tdoclatex}


\begin{tdocnote}
    La macro \tdocmacro{tdocinlatex} est utilisable dans une note de pied de page : voir ci-dessous.
    \footnote{
        \tdocinlatex+$minted = TOP$+ a été tapé \tdocinlatex|\tdocinlatex+$minted = TOP$+| dans cette note de bas de page..
    }
    De plus, une couleur de fond est volontairement utilisée pour subtilement faire ressortir les codes \tdocinlatex#\LaTeX#\,.
\end{tdocnote}



\subsection{Codes tapés directement}

\begin{tdocexa}[Face à face]
    Via \tdocenv[{[sbs]}]{tdoclatex}, on affichera un code et son rendu côte à côte.
    Indiquons que \tdocinlatex#sbs# est pour \tdocquote{\tdocprewhy{s.ide} \tdocprewhy{b.y} \tdocprewhy{s.ide}} soit \tdocinEN{côte à côte}.
    \tdocbasicinputDOC{examples-listing-ABC.tex}

\end{tdocexa}


\begin{tdocexa}[À la suite]
    \tdocenv{tdoclatex} produit le résultat suivant qui correspond à l'option par défaut \tdocinlatex#std#\,.
    \footnote{
        \tdocinlatex{std} fait référence au comportement \tdocquote{standard} de \tdocpack{tcolorbox} vis à vis de la librairie \tdocpack{minted}.
    }

    \begin{tdoclatex}
        $A = B + C$
    \end{tdoclatex}
\end{tdocexa}


\begin{tdocexa}[Juste le code]
    Via \tdocenv[{[code]}]{tdoclatex}, on aura juste le code comme ci-après.

    \begin{tdoclatex}[code]
        $A = B + C$
    \end{tdoclatex}
\end{tdocexa}


\begin{tdocwarn}
    Avec la mise en forme par défaut, si le code commence par un crochet ouvrant, il faudra indiquer explicitement l'option par défaut.
    \tdocbasicinputDOC{examples-listing-strange.tex}


    \smallskip

    Une autre méthode consiste à utiliser la primitive \tdocmacro{string}.
    \tdocbasicinputDOC{examples-listing-strange-bis.tex}

\end{tdocwarn}


\subsection{Codes importés}

Pour les codes suivants, on considère un fichier de chemin relatif \verb+examples-listing-xyz.tex+, et ayant le contenu suivant.


\tdoclatexinput[code]{examples-listing-xyz.tex}



\medskip


La macro \tdocmacro{tdoclatexinput}, présentée ci-dessous, attend le chemin d'un fichier et propose les mêmes options que l'environnement \tdocenv*{tdoclatex}.


\begin{tdocexa}[Face à face]
    \leavevmode

    \begin{tdoclatex}[code]
\tdoclatexinput[sbs]{examples-listing-xyz.tex}

    \end{tdoclatex}

    Ceci produit la mise en forme suivante.

    \tdoclatexinput[sbs]{examples-listing-xyz.tex}

\end{tdocexa}


\begin{tdocexa}[À la suite]
    \leavevmode

    \begin{tdoclatex}[code]
\tdoclatexinput{examples-listing-xyz.tex}

    \end{tdoclatex}

    Ceci produit la mise en forme suivante où l'option employée par défaut est \tdocinlatex#std#.

    \tdoclatexinput{examples-listing-xyz.tex}

\end{tdocexa}


\begin{tdocexa}[Juste le code]
    \leavevmode

    \begin{tdoclatex}[code]
\tdoclatexinput[code]{examples-listing-xyz.tex}

    \end{tdoclatex}

    Ceci produit la mise en forme suivante.

    \tdoclatexinput[code]{examples-listing-xyz.tex}

\end{tdocexa}



\subsection{Codes importés et mis en situation}
\label{tutodoc-latexshow}

\begin{tdocexa}[Mise en situation]
    Ce qui suit s'obtient via \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+.

    \medskip

    \begin{tdocshowcaseDOC}
        \tdoclatexshow{examples-listing-xyz.tex}

    \end{tdocshowcaseDOC}
\end{tdocexa}


\begin{tdocnote}
    Les textes par défaut tiennent compte de la langue détectée par \thisproj.
\end{tdocnote}


\begin{tdocexa}[Changer le texte explicatif]
    Via la clé \tdocinlatex|explain|, on peut utiliser un texte personnalisé. Ainsi, \tdocinlatex|\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}| produira ce qui suit.

    \medskip

    \begin{tdocshowcaseDOC}
        \tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}

    \end{tdocshowcaseDOC}
\end{tdocexa}


\begin{tdocexa}[Les options disponibles]
    En plus du texte explicatif, il est aussi possible d'utiliser toutes les options de l'environnement \tdocenv*{tdocshowcase}, voir \ref{tutodoc-showcase} page \pageref{tutodoc-showcase}.
    Voici un exemple illustrant ceci.

    \medskip

    \tdoclatexinput[code]{examples-listing-latexshow-options.tex}


    \medskip

    Ceci va produire ce qui suit.

    \medskip

    \begin{tdocshowcaseDOC}
        \input{examples-listing-latexshow-options.tex}

    \end{tdocshowcaseDOC}
\end{tdocexa}


\section{Indiquer les changements}

Afin de faciliter le suivi d'un projet, il est indispensable de fournir un historique indiquant les changements effectués lors de la publication d'une nouvelle version.



\subsection{À quel moment ?}
\label{tutodoc-changes-when}

On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas le numéro de version pourra éventuellement être daté.


\begin{tdocexa}[Dater des nouveautés]
    La macro \tdocmacro{tdocdate} permet d'indiquer une date dans la marge comme dans l'exemple suivant.

    \tdoclatexshow{examples-version-n-change-dating.tex}

\end{tdocexa}


\begin{tdocexa}[Versionner des nouveautés en les datant événtuellement]
    Associer un numéro de version à une nouveauté se fait via la macro \tdocmacro{tdocversion}, la couleur et la date étant des arguments optionnels.

    \tdoclatexshow{examples-version-n-change-versioning.tex}

\end{tdocexa}


\begin{tdocimp}
    \begin{enumerate}[wide]
        \item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} nécessitent deux compilations.

        \item Comme la langue détectée pour cette documentation est le français, la date dans le rendu final est au format \texttt{JJ/MM/AAAA} alors que dans le code celle-ci devra toujours être saisie au format anglais \texttt{AAAA-MM-JJ}.
    \end{enumerate}
\end{tdocimp}


\begin{tdoccaut}
    Seul l'emploi du format numérique \tdocinlatex+YYYY-MM-DD+ est vérifié,
    \footnote{
        Techniquement, vérifier la validité d'une date, via \LaTeX3, ne présente pas de difficulté.
    }
    et ceci est un choix ! Pourquoi cela ? Tout simplement car dater et versionner des explications devrait se faire de façon semi-automatisée afin d'éviter tout bug humain.
%    \footnote{
%        L'auteur de \thispack{} est entrain de mettre en place un ensemble d'outils permettant une telle semi-automatisation.
%    }.
\end{tdoccaut}


\begin{tdocwarn}
    En coulisse, le gros du travail est fait par la macro \tdocmacro{\marginnote} du package éponyme.
    Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} souffrent donc des même effets de bord comme dans l'exemple suivant.
    On peut tout de même régler ces problèmes via un argument optionnel \tdocinlatex{<déplacement-vertical>} comme à la fin de l'exemple ci-après. C'est moche, mais fonctionnel.

    \tdoclatexshow[nostripe, colstripe=red]{examples-version-n-change-side-effect.tex}

\end{tdocwarn}


\subsection{Quoi de neuf ?}

\thisproj\ propose la macro \tdocmacro{tdocstartproj} et différents environnements pour indiquer rapidement et clairement ce qui a été fait lors des derniers changements.%
\footnote{
    L'utilisateur n'a pas besoin de tous les détails techniques.
}


\begin{tdocnote}
    Concernant les icônes, voir la note au début de la section \ref{tutodoc-admonitions} page \pageref{tutodoc-admonitions}.
\end{tdocnote}


\foreach \exatitle/\filename in {
    {Juste pour la toute première version}/%<-- Translate me!
        first,
    {Pour les nouveautés}/% <-- Translate me!
        new,
    {Pour les mises à jour}/% <-- Translate me!
        update,
    {Pour les bifurcations}/% <-- Translate me!
        break,
    {Pour les problèmes}/% <-- Translate me!
        pb,
    {Pour les réparations}/% <-- Translate me!
        fix,
    {Informations techniques}/% <-- Translate me!
        tech,
    %
    {Thématiques aux choix avec une icône}/%<-- Translate me!
        user-choice-icon,
    {Thématiques aux choix sans icône}/% <-- Translate me!
        user-choice%
} {
    \begin{tdocexa}[\exatitle]
        \leavevmode

        \tdoclatexinput[sbs]{examples-version-n-change-\filename.tex}

    \end{tdocexa}
}


\subsection{Le quoi et le quand}

Les clés optionnelles \tdocinlatex{col}\,, \tdocinlatex{date} et \tdocinlatex{version} permettent de dater et versionner un changement d'un type particulier.%
\footnote{
    L'avertissement à la fin de la section \ref{tutodoc-changes-when} donne la technique utilisée en coulisse, tout en montrant la nécessité de proposer des clés spécialisées.
}
Voici des exemples d'utilisation.

\tdoclatexshow{examples-version-n-change-what-n-when.tex}



\section{Décoration}

Finissons cette documentation avec un petit outil de mise en forme qui rend de grands services.


\begin{tdoclatex}[sbs]
Bla, bla, bla...

\tdocsep % Pratique pour délimiter.

Ceci fonctionne avec des énumérations.

\begin{itemize}
    \item Point souligné.
\end{itemize}

\tdocsep % Un comportement uniforme.

Ble, ble, ble...
\end{tdoclatex}


\section{Contribuer}

\begin{tdocnote}
    \textbf{Nul besoin d'être un codeur pour participer aux traductions}, y compris pour celles utiles au fonctionnement de \thisproj.
\end{tdocnote}


%\section{Contribuer}

\subsection{Compléter les traductions}

\begin{tdocnote}
    L'auteur de \thisproj\ gère les versions françaises et anglaises des traductions.
\end{tdocnote}


\begin{tdoccaut}
    Même si nous allons expliquer comment traduire les documentations, il semble peu pertinent de le faire, car l'anglais devrait suffire de nos jours.%
    \footnote{
        L'existence d'une version française est une simple conséquence de la langue maternelle de l'auteur de \thisproj.
    }
\end{tdoccaut}

\begin{figure}[ht]
    \centering
    \contribtranslatedirtree\
    \caption{Vue simplifiée du dossier des traductions}
    \label{tutodoc-contrib-translate-dir}
\end{figure}


Les traductions sont organisées grosso-modo comme dans la figure \ref{tutodoc-contrib-translate-dir} où seuls les dossiers importants pour les traductions ont été \tdocquote{ouverts}\,.%
\footnote{
    Cette organisation était celle du 5 octobre 2024, mais elle reste d'actualité.
}
\textbf{Un peu plus bas, la section \ref{tutodoc-contrib-translate} donne les démarches à suivre pour ajouter de nouvelles traductions.}


\subsubsection{Les dossiers \texttt{fr} et \texttt{en}}

Ces deux dossiers, gérés par l'auteur de \thisproj, ont la même organisation ; ils contiennent des fichiers faciles à traduire même si l'on n'est pas un codeur.


\subsubsection{Le dossier \texttt{changes}}

Ce dossier est un outil de communication où sont indiqués les changements importants sans s'attarder sur les modifications mineures propres à une ou plusieurs traductions.



\subsubsection{Le dossier \texttt{status}}

Ce dossier permet de savoir où en sont les traductions du point de vue du projet. Tout se passe via des fichiers \verb#YAML# bien commentés, et lisibles par un non codeur.



\subsubsection{Les fichiers \texttt{README.md} et \texttt{LICENSE.txt}}

Le fichier \texttt{LICENSE.txt} est bien nommé, tandis que le fichier \texttt{README.md} reprend en anglais les points importants de ce qui est dit dans cette section sur les nouvelles traductions.



\subsubsection{De nouvelles traductions}
\label{tutodoc-contrib-translate}

\begin{tdocimp}
    Le dossier \verb#api# contient les traductions relatives aux fonctionnalités de \thisproj.
    Vous y trouverez des fichiers de type \verb#TXT# à modifier via un éditeur de texte, ou de code, mais non via un traitement de texte.
    Les contenus de ces fichiers utilisent des lignes commentées en anglais pour expliquer ce que fera \thisproj\ ; ces lignes commencent par \verb#//#\,. Voici un extrait de ce type de fichier où \textbf{les traductions se font après chaque signe \,$=$\, sans toucher à ce qui se trouve avant}, car ce morceau initial est utilisé en interne par le code de \thisproj..

    \tdocsep
    \vspace{-10pt}
    \begin{verbatim}
  // #1: year  in format YYYY like 2023.
  // #2: month in format MM   like 04.
  // #3: day   in format DD   like 29.
  date = #1-#2-#3

  // #1: the idea is to produce one text like
  //     "this word means #1 in English".
  in_EN = #1 in english\end{verbatim}
\end{tdocimp}


\begin{tdocnote}
    Le dossier \verb#doc# est réservé aux documentations. Il contient des fichiers de type \verb#TEX# compilables directement pour une validation en temps réel des traductions faites.
\end{tdocnote}


\begin{tdocwarn}
    Ne partir que de l'un des dossiers \verb#fr# et \verb#en#, car ceux-ci sont de la responsabilité de l'auteur de \thisproj.
\end{tdocwarn}


\medskip


\emph{\textbf{Imaginons que vous souhaitiez ajouter le support de l'italien en partant de fichiers rédigés en anglais.}}%
\footnote{
    Comme indiqué plus haut, il n'y a pas de besoin réel du côté du dossier \texttt{doc} de la documentation.
}


\paragraph{Méthode 1 : \git.}

\begin{enumerate}
    \item Obtenir tout le dossier du projet via \thisrepo\,.
    Ne pas passer via la branche \verb#main# qui sert à figer les dernières versions stables des projets du dépôt unique \thismonorepo\,.

    \item Dans le dossier \verb#tutodoc/contrib/translate#, créer une copie \verb#it# du dossier \verb#en#\,, le nom court de la langue étant documenté dans
    \href{https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags}%
         {la page \tdocquote{IIETF language tag}}
    de \texttt{Wikipédia}.

    \item Une fois la traduction achevée dans le dossier \verb#it# , il faudra la communiquer via \thisrepo\ en usant d'un classique \verb#git push#\,.
\end{enumerate}


\paragraph{Méthode 2 : communiquer par courriels.}

\begin{enumerate}
    \item Via un courriel de \mailsubject{en FOR italian}\,, demander une version des traductions anglaises (noter l'emploi du nom anglais de la nouvelle langue).
    Bien respecter le sujet du courriel, car l'auteur de \thisproj\ automatise le pré-traitement de ce type de courriels.

    \item Vous recevrez un dossier nommé \verb#italian# contenant la version anglaise des dernières traductions.
    Ce dossier sera le lieu de votre contribution.

    \item Une fois la traduction achevée, il faudra compresser votre dossier \verb#italian# au format \verb#zip# ou \verb#rar# avant de l'envoyer par courriel avec le \mailsubject{italian}\,.
\end{enumerate}


%\section{Contribuer}

\subsection{Améliorer le code source}

\begin{tdocimp}
    Si vous souhaitez participer à \thisproj\,, il faudra privilégier le paradigme de programmation \LaTeX3.
\end{tdocimp}


La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrepo\ correspondant à la branche de développement \verb#tutodoc#.
Ne pas passer via la branche \verb#main# qui sert à figer les dernières versions stables des projets du dépôt unique \thismonorepo\,.


\section{Historique}

\small

\begin{tdocnew}[version = 1.6.2, date = 2024-10-30]
	\item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} ont un nouvel argument final facultatif \tdocinlatex{<voffset>} pour choisir un décalage vertical spécifique.

	\item De meilleurs environnements pour indiquer les modifications apportées.
	\begin{enumerate}
		\item Les nouvelles clés facultatives \tdocinlatex{col}\,, \tdocinlatex{date} et \tdocinlatex{version} permettent d'indiquer la date et la version d'une modification apportée à un sujet spécifique.

		\item Utilisation de \tdocmacro{paragraph} pour le titre.
	\end{enumerate}
\end{tdocnew} 


\begin{tdocupdate}
	\item Changements : la police des notes de marge aura toujours une forme normale.

	\item Ornement : utilisation d'un \tdocinlatex{\cleaders} pour éviter les lignes orphelines en bas de page.
\end{tdocupdate}

\tdocsep


% ------------------ %


\begin{tdoctech}[version = 1.6.1, date = 2024-10-28]
    \item Les règles de nommage de \ctan\ nécessitent l'usage de noms du type \verb+tutodoc-*.css.cls.sty+ pour les fichiers à-la \trademark{CSS}.
\end{tdoctech}

\tdocsep


% ------------------ %


\begin{tdocbreak}[version = 1.6.0, date = 2024-10-27]
    \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdocinlatex{color} a été renommée \tdocinlatex{colstripe}.

    \item La macro \tdocmacro{tdoclinkcolor} devient la couleur \tdocinlatex{tutodoc@link@color} destinée à un usage interne.
\end{tdocbreak}


\begin{tdocnew}
    \item L'option de classe \tdocinlatex{theme} permet de choisir différents thèmes de mise en forme.

    \item Journal des modifications : ajout de l'environnement \tdocenv*{tdoctech} pour les informations techniques.

    \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdocinlatex{coltext} permet de changer aussi la couleur du texte.

    \item Les nouvelles fonctionnalités ont été documentées.
\end{tdocnew}


\begin{tdocupdate}
    \item Journal des modifications : l'environnement \tdocenv*{tdocupdate} utilise l'icône
    \raisebox{0pt}[0pt][0pt]{\fbox{\reflectbox{\faHistory}}}
    au lieu de
    \raisebox{0pt}[0pt][0pt]{\fbox{\faMagic}}\,.
\end{tdocupdate}


\begin{tdocfix}
    \item Les traductions espagnoles n'avaient pas été livrées dans la précédente version ! Ne pas rire trop fort...
\end{tdocfix}

\tdocsep


% ------------------ %


\begin{tdoctech}[version = 1.5.0, date = 2024-10-19]
    \item La version 3 de \tdocpack{minted} est prise en compte.
\end{tdoctech}

\begin{tdocbreak}
    \item La classe \thisproj\ remplace le défunt package \thisproj\ (pour le moment, la toute jeune classe ne propose aucune option spécifique).

    \item La macro \tdocmacro{tdocruler} s'emploie dorénavant via \tdocinlatex{\tdocruler[<color>]{<text>}} (avant il fallait utiliser \tdocinlatex{\tdocruler{<text>}{<color>}}).
\end{tdocbreak}


\begin{tdocnew}
    \item La classe est utilisable en langue espagnole.

    \item La documentation contient une nouvelle section expliquant comment contribuer.
\end{tdocnew}


\begin{tdocfix}
    \item La macro \tdocmacro{tdocdate} ne gérait pas le format et la mise en forme de la date.

    \item Les cadres colorés ne coloraient pas le texte après un saut de page.
\end{tdocfix}

\tdocsep


% ------------------ %


\begin{tdocbreak}[version = 1.4.0, date = 2024-09-28]
    \item L'environnement \tdocenv*{tdoccaution} a été renommé \tdocenv*{tdoccaut} pour une saisie simplifiée.

    \item Mise en avant de contenus : les exemples et remarques, indiqués via les environnements \tdocenv*{tdocexa} et \tdocenv*{tdocrem}, sont toujours numérotés via un compteur commun.

    \item La macro inutilisée \tdocmacro{tdocxspace} a été supprimée.
\end{tdocbreak}


\begin{tdocnew}
    \item Journal des changements : la macro \tdocmacro{tdocstartproj} permet de gérer le cas de la première version publique.

    \item Factorisation du code : la macro \tdocmacro{tdocicon} est en charge de l'ajout d'icônes devant du texte.
\end{tdocnew}


\begin{tdocupdate}
    \item Couleurs : les macros \tdocmacro{tdocdarkcolor} et \tdocmacro{tdoclightcolor} proposent un argument facultatif.
    \begin{enumerate}
        \item \tdocmacro{tdocdarkcolor} : la quantité de couleur par rapport au noir peut être définie de manière facultative.

        \item \tdocmacro{tdoclightcolor} : le taux de transparence peut être défini de manière facultative.
    \end{enumerate}

    \item Mise en avant de contenus : réduction de l'espace autour du contenu dans les cadres colorés.

    \item Gestion des versions: un meilleur espacement vertical via \tdocmacro{vphantom}.
\end{tdocupdate}

\tdocsep


% ------------------ %


\begin{tdocnew}[version = 1.3.1, date = 2024-09-26]
    \item Version étoilée de \tdocmacro{tdocenv} pour n'avoir que le nom de l'environnement.
\end{tdocnew}

\tdocsep


% ------------------ %


\begin{tdoctech}[version = 1.3.0, date = 2024-09-25]
    \item La version 3 de \tdocpack{minted} ne peut pas être prise en compte pour le moment car elle comporte des bugs : voir \url{https://github.com/gpoore/minted/issues/401}. On force donc temporairement l'usage de la version 2 de \tdocpack{minted}.
\end{tdoctech}


\begin{tdocbreak}
    \item L'environnement \tdocenv*{tdocimportant} a été renommé \tdocenv*{tdocimp} pour une saisie simplifiée.
\end{tdocbreak}


\begin{tdocnew}
    \item Journal des changements : les environnements proposés utilisent des icônes.


    \item Mise en avant de contenus : des cadres colorés avec des icônes sont proposés pour les environnements suivants.
    \bgroup
    \setlength\multicolsep{5pt}
    \begin{multicols}{3}
        \begin{enumerate}
            \item \tdocenv*{tdoccaution}
            \item \tdocenv*{tdocimp}
            \item \tdocenv*{tdocnote}
            \item \tdocenv*{tdoctip}
            \item \tdocenv*{tdocwarn}
        \end{enumerate}
    \end{multicols}
    \egroup
\end{tdocnew}

\tdocsep


% ------------------ %


\begin{tdocupdate}[version = 1.2.0-a, date = 2024-08-23]
    \item \tdocmacro{tdocversion}
    \begin{enumerate}
        \item Le numéro de version est au-dessus de la date.

        \item L'espacement est mieux géré lorsque la date est absente.
    \end{enumerate}
\end{tdocupdate}


\begin{tdocfix}
    \item Mise en avant de contenus : les traductions françaises de \tdocinEN*{caution} et \tdocinEN*{danger} étaient erronées.
\end{tdocfix}

\tdocsep


% ------------------ %


\begin{tdocnew}[version = 1.1.0, date = 2024-01-06]
    \item Journal des changements : deux nouveaux environnements.
    \begin{enumerate}
        \item \tdocenv{tdocbreak} pour les \tdocquote{bifurcations}\,, soit les modifications non rétrocompatibles.

        \item \tdocenv{tdocprob} pour les problèmes repérés.
    \end{enumerate}

    \item \tdocmacro{tdocinlatex}: un jaune léger est utilisé comme couleur de fond.
\end{tdocnew}

\tdocsep


% ------------------ %


\begin{tdocfix}[version = 1.0.1, date = 2023-12-08]
    \item \tdocmacro{tdocenv}: l'espacement est maintenant correct, même si le paquet \tdocpack{babel} n'est pas chargé avec la langue française.

    \item \tdocenv[{[nostripe]}]{tdocshowcase}: les sauts de page autour des lignes \tdocquote{cadrantes} devraient être rares dorénavant.
\end{tdocfix}

\tdocsep


% ------------------ %


\tdocversion{1.0.0}[2023-11-29]
\tdocstartproj{Première version publique du projet.}

\end{document}