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


\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}{Ne pas regarder}[\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-first.tex}
\tdocstartproj{Première version du projet.}
\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-focus-exa-leavevmode.tex}
\begin{tdocexa}
    \leavevmode
    \begin{enumerate}
        \item Point 1.

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


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

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


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

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


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

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


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

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


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

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


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

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


\begin{filecontents*}[overwrite]{examples-focus-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.,
               color   = orange]
               {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,
                     color  = red]
    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,
                     color  = green]
    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]{article}

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[french]{babel, varioref}

\usepackage{enumitem}
\frenchsetup{StandardItemLabels=true}

\usepackage{multicol}

\newcommand\thispack{\tdocpack{tutodoc}}

% Package documented.
\usepackage[lang = french]{tutodoc}


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

\NewDocumentCommand{ \tdocdocbasicinput }{ 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{ \tdocdocextraruler }{ 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{ tdoc-doc-showcase }
                       { O{ Début du rendu dans cette doc. }
                         O{ Fin du rendu dans cette doc. } }{
        \tdocdocextraruler{#1}
        \nopagebreak\smallskip\nopagebreak
}{
        \nopagebreak\smallskip\nopagebreak
        \tdocdocextraruler{#2}
}


\begin{document}


\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe BAL}
\date{28 sept. 2024 - Version 1.4.0}

\maketitle

\begin{abstract}
    Le package \thispack{}\,%
    \footnote{
        Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} qui se traduit en \tdocquote{documentation de type tutoriel}.
    }
    est utilisé 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.
    }
    et avec un rendu sobre pour une lecture sur écran.

    \medskip

    \noindent
    Deux points importants à noter.
    \begin{itemize}
        \item Ce package impose un style de mise en forme. Dans un avenir plus ou moins proche, \thispack{} sera sûrement éclaté en une classe et un package.

        \item Cette documentation est aussi disponible en anglais.
    \end{itemize}

    \tdocsep

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

        The \thispack{} package\,%
        \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.
        }
        and with a sober rendering for reading on screen.
    
        \medskip
    
        Two important points to note.
        \begin{itemize}
            \item This package imposes a formatting style. In the not-too-distant future, \thispack{} will probably be split into a class and a package.
    
            \item This documentation is also available in French.
        \end{itemize}
    }
\end{abstract}


\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]
\hypersetup{
  colorlinks,
  citecolor = orange!75!black,
  filecolor = orange!75!black,
  linkcolor = orange!75!black,
  urlcolor  = orange!75!black
}
\end{tdoclatex}


\section{Choisir la langue au chargement du package}

La présente documentation utilise le français via \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
Pour le moment, on a juste les deux choix suivants.

\begin{enumerate}
    \item \tdocinlatex|english| est la valeur par défaut.

    \item \tdocinlatex|french| est pour \tdocinEN{français}.
\end{enumerate}


\begin{tdocnote}
    Les noms des langues sont ceux proposés par le package \tdocpack{babel}.
\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 indiquée lors de l'importation de \thispack{}.
\end{tdocnote}


\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 indiquée lors du chargement du package \thispack{}.
\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.
\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-focus-exa.tex}



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


\begin{tdocimp}
    La numérotation des exemples est remise à zéro dès qu'une section de niveau au moins égale à une \tdocinlatex|\section| est ouverte.
\end{tdocimp}


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


\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-focus-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-focus-rmk.tex}



\subsection{Du contenu tape-à-l'oeil} \label{tdoc-colorful-focus}

\begin{tdocnote}
    Les icônes sont obtenues via le package \tdocpack{fontawesome5}, et la gestion de l'espacement avec le texte est faite par la macro \tdocmacro{tdocicon}.
    \footnote{
        Par exemple,
        \tdocinlatex|\tdocicon{\faBed}{Fatigué}|
        produit\,
        \tdocicon{\faBed}{Fatigué}.
    }
\end{tdocnote}


\subsubsection{Une astuce}

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

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



\smallskip

\begin{tdocnote}
    Les couleurs sont obtenues via les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor}.
    Pour des informations complémentaires à ce sujet, se reporter à la fin de la section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}.
\end{tdocnote}


%\subsection{Du contenu tape-à-l'oeil}

\subsubsection{Note informative}

L'environnement \tdocenv*{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.

\tdoclatexinput[sbs]{examples-focus-note.tex}



%\subsection{Du contenu tape-à-l'oeil}

\subsubsection{Un truc important}

L'environnement \tdocenv*{tdocimp} permet d'indiquer quelque chose d'important mais sans danger.

\tdoclatexinput[sbs]{examples-focus-important.tex}



%\subsection{Du contenu tape-à-l'oeil}

\subsubsection{Avertir d'un point très délicat}

L'environnement \tdocenv*{tdoccaut} sert à indiquer un point délicat à  l'utilisateur. Voici comment l'employer.

\tdoclatexinput[sbs]{examples-focus-caution.tex}



%\subsection{Du contenu tape-à-l'oeil}

\subsubsection{Avertir d'un danger}

L'environnement \tdocenv*{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.

\tdoclatexinput[sbs]{examples-focus-warn.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{tdoc-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} \label{tdoc-color-macros}

\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{tdoc-latexshow} page \pageref{tdoc-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 choisie lors du chargement de \thispack{}.
\end{tdocnote}


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


\begin{tdocexa}[Changer la couleur 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}
    Vous avez sûrement remarqué que le rouge sert de base pour obtenir les couleurs utilisées.

    \begin{itemize}
    	\item La couleur de fond est fournie par \tdocmacro{tdocbackcolor}.

    	\item La couleur des titres et des lignes est fournie par \tdocmacro{tdocdarkcolor}.
    \end{itemize}

    Ces macros développables admettent les codes suivants.

    \begin{tdoclatex}[code]
% Argument 1 : de façon optionnelle, on peut indiquer la quantité de couleur
%              relativement au noir.
%              Il est en général inutile de modifier ce paramètre !
% Argument 2 : une couleur au format xcolor.
\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}

% Argument 1 : de façon optionnelle, on peut indiquer le taux de transparence.
%              Il est en général inutile de modifier ce paramètre !
% Argument 2 : une couleur au format xcolor.
\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
    \end{tdoclatex}

    Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est utilisée.

    \begin{tdoclatex}[std]
        \tdocruler{Un pseudo-titre décoré}{red}
    \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 la couleur et/ou les textes par défaut]
    \leavevmode

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


    Ceci produira ce qui suit.

    \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[color = orange]{external.tex}+\,, ceci produira le changement de couleur observable ci-après.

    \medskip

    \tdocshowcaseinput[color = orange]{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{tdoc-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}.
Voici des exemples d'utilisation.


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

    2: \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}.
    \tdocdocbasicinput{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.
    \tdocdocbasicinput{examples-listing-strange.tex}


    \smallskip

    Une autre méthode consiste à utiliser la primitive \tdocmacro{string}.
    \tdocdocbasicinput{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{tdoc-latexshow}

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

    \medskip

    \begin{tdoc-doc-showcase}
        \tdoclatexshow{examples-listing-xyz.tex}

    \end{tdoc-doc-showcase}
\end{tdocexa}


\begin{tdocnote}
    Les textes par défaut tiennent compte de la langue choisie lors du chargement du package \thispack{}.
\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{tdoc-doc-showcase}
        \tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}

    \end{tdoc-doc-showcase}
\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{tdoc-showcase} page \pageref{tdoc-showcase}.
    Voici un exemple illustrant ceci.

    \medskip

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


    \medskip

    Ceci va produire ce qui suit.

    \medskip

    \begin{tdoc-doc-showcase}
        \input{examples-listing-latexshow-options.tex}

    \end{tdoc-doc-showcase}
\end{tdocexa}


\section{Indiquer les changements}

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



\subsection{À quel moment ?}

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}
        \item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} nécessitent deux compilations.

        \item Comme la langue indiqué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{tdocwarn}
    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{tdocwarn}


\subsection{Quoi de neuf ?}

\thispack{} 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{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
\end{tdocnote}


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


\begin{tdocexa}[Juste pour la toute première version]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Pour les nouveautés]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Pour les mises à jour]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Pour les bifurcations]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Pour les problèmes]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Pour les réparations]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Thématiques aux choix avec une icône]
    \leavevmode

    \tdoclatexinput[sbs]{examples-version-n-change-user-choice-icon.tex}

\end{tdocexa}


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


\begin{tdocexa}[Thématiques aux choix sans icône]
    \leavevmode

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

\end{tdocexa}


\section{Décorations}

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

\small

\tdocversion{1.4.0}[2024-09-28]

\begin{tdocbreak}
	\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, et ils partagent le même compteur.

	\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 verticalement via \tdocmacro{vphantom}.
\end{tdocupdate}

\tdocsep


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


\tdocversion{1.3.1}[2024-09-26]

\begin{tdocnew}
    \item Version étoilée de \tdocmacro{tdocenv} pour n'avoir que le nom de l'environnement.
\end{tdocnew}

\tdocsep


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


\tdocversion{1.3.0}[2024-09-25]

\begin{tdocprob}
	\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 l'usage de la version 2 de \tdocpack{minted}.
\end{tdocprob}


\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


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


\tdocversion{1.2.0-a}[2024-08-23]

\begin{tdocupdate}
    \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


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


\tdocversion{1.1.0}[2024-01-06]

\begin{tdocnew}
    \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


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


\tdocversion{1.0.1}[2023-12-08]

\begin{tdocfix}
    \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}