% ==================== %
% == 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}
% Ici le point s'impose.
    \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-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{tdoccaution}
    Prudence, prudence...
\end{tdoccaution}

\begin{tdoccaution}[Mini titre]
    Utile ?
\end{tdoccaution}
\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}
Bla, bla, bla...

\begin{tdocexa}
    Ble, ble, ble...
\end{tdocexa}

\begin{tdocexa}[Magnifique]
    Bli, bli, bli...
\end{tdocexa}

\begin{tdocexa}<nonb>
    Blo, blo, blo...
\end{tdocexa}

\begin{tdocexa}<nonb>[Superbe]
    Blu, blu, blu...
\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{25 sept. 2024 - Version 1.3.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{Des exemples}

Des exemples numérotés, ou non, s'indiquent via l'environnement \tdocenv{tdocexa} qui propose deux arguments optionnels.

\begin{enumerate}
    \item Le 1\ier{} argument entre chevrons \tdocinlatex#<...># peut prendre au choix les valeurs \tdocinlatex#nb# pour numéroter, réglage par défaut, et \tdocinlatex#nonb# pour ne pas numéroter.

    \item Le 2\ieme{} argument entre crochets \tdocinlatex#[...]# sert à ajouter un mini-titre.
\end{enumerate}


Voici différents emplois 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|\subsubsection| est ouverte.
\end{tdocimp}


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


\begin{tdoctip}
    Il peut parfois être utile de revenir à la ligne dès le début du contenu. Voici comment faire (ce tour de passe-passe reste valable pour les environnements présentés dans les sous-sections suivantes). Noter au passage que la numérotation suit celle de l'exemple précédent comme souhaité.

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

\end{tdoctip}


\subsection{Des remarques}

Tout se passe via l'environnement \tdocenv{tdocrem} comme dans l'exemple suivant.

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



\subsection{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 fournies par les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor} qui admettent les codes suivants.

    \begin{tdoclatex}[code]
\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
    \end{tdoclatex}
\end{tdocnote}


\subsection{Note informative}

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

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



\subsection{Un truc important}

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

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



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

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

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



\subsection{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...

On a aussi :

\tdocenv[{[opt1]<opt2>}]{env}
\end{tdoclatex}


\begin{tdocrem}
    L'intérêt des macros précédentes vis à vis de l'usage de \tdocmacro{tdocinlatex}, voir la section \ref{tdoc-listing-inline} page \pageref{tdoc-listing-inline}, est l'absence de coloration.
    De plus, la macro \tdocmacro{tdocenv} demande juste de taper le nom de l'environnement
    \footnote{
        De plus, \tdocinlatex{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin.
    }
    avec des éventuelles options en tapant les bons délimiteurs
    \footnote{
        Se souvenir que tout est possible ou presque dorénavant.
    }
    à la main.
\end{tdocrem}


\begin{tdocwarn}
    L'argument optionnel de la macro \tdocmacro{tdocenv} est copié-collé lors du rendu. Ceci peut donc parfois nécessiter d'utiliser des accolades protectrices comme dans l'exemple précédent.
\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}

\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 et à un seul argument, la couleur choisie, admettent les codes suivants.

    \begin{tdoclatex}[code]
\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
    \end{tdoclatex}

    Il faut également savoir qu'en coulisses, 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}<nonb>
    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{tdocwarn}
	Version 3 of \tdocpack{minted} cannot be used at the moment, as it contains bugs: see \url{https://github.com/gpoore/minted/issues/401}. We therefore force the use of version 2 of \tdocpack{minted}.
\end{tdocwarn}


\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}[Showcase]
    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 \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 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{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 de petits outils de mise en forme pouvant rendre 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é.

    \item Autre chose utile.
\end{itemize}

\tdocsep % Un comportement uniforme.

Ble, ble, ble...

Bli, bli, bli...

\tdocxspace % Espace subtile
            % mais utile.

Blo, blo, blo...

Blu, blu, blu...

\end{tdoclatex}


\section{Historique}

\small

\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 \verb#tdocimportant# a été renommé \verb#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}{3.0pt plus 1.0pt minus 0.75pt}
    \begin{multicols}{3}
        \begin{enumerate}
        	\item \verb#tdoccaution#
        	\item \verb#tdocimp#
        	\item \verb#tdocnote#
        	\item \verb#tdoctip#
        	\item \verb#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]

Première version publique du projet.

\end{document}