% ==================== %
% == 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 % CAUTION! This prevents overlapping.

\tdocdate{2023-09-24}

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

\medskip % CAUTION! This prevents overlapping.

\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}{Don't look}[\faEyeSlash]
% An icon from fontawesome5.
    \item Info 1...
    \item Info 2...
\end{tdoctopic}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
\begin{tdoctopic}{End of icons}
    \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 % CAUTION! This prevents overlapping.

\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{1st version of the project.}
\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}
    Important and harmless.
\end{tdocimp}

\begin{tdocimp}[Mini title]
    Useful?
\end{tdocimp}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-focus-note.tex}
\begin{tdocnote}
    Something useful to tell you...
\end{tdocnote}

\begin{tdocnote}[Mini title]
    Useful?
\end{tdocnote}
\end{filecontents*}


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

\begin{tdoccaut}[Mini title]
    Useful?
\end{tdoccaut}
\end{filecontents*}


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

\begin{tdoctip}[Mini title]
    Useful?
\end{tdoctip}
\end{filecontents*}


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

\begin{tdocwarn}[Mini title]
    Useful?
\end{tdocwarn}
\end{filecontents*}


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

\begin{tdocexa}[Mini title]
    Useful?
\end{tdocexa}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
\begin{tdocrem}
    Just one remark...
\end{tdocrem}

\begin{tdocrem}
    Another?
\end{tdocrem}

\begin{tdocrem}[Mini title]
    Useful?
\end{tdocrem}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-latexshow-options.tex}
\tdoclatexshow[explain = What comes next is colourful...,
               before  = Rendering below.,
               after   = Finished rendering.,
               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}
% Just one demo.
$x y z = 1$
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-strange.tex}
\begin{tdoclatex}[std]
    [Strange... Or not!]
\end{tdoclatex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex}
\begin{tdoclatex}
    \string[Strange... Or not!]
\end{tdoclatex}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-customized.tex}
\begin{tdocshowcase}[before = My beginning,
                     after  = My end,
                     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[This works...]
\end{tdocshowcase}
\end{filecontents*}


\begin{filecontents*}[overwrite]{examples-showcase-no-clrstrip-customized.tex}
\begin{tdocshowcase}[nostripe,
                     before = My beginning,
                     after  = My end,
                     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 A bit of code \LaTeX.

    \bigskip

    \emph{\large End of the awful demo.}
\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[english]{babel, varioref}





\usepackage{enumitem}
\usepackage{fmtcount}

\usepackage{multicol}
\setlength{\parindent}{0em}

\newcommand\thispack{\tdocpack{tutodoc}}

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


% --------------- %
% -- IMPORTANT -- %
% --------------- %
%
% See the French version of this file for the text to be used
% for languages other than English.


% --------------- %
% -- IMPORTANT -- %
% --------------- %
%
% See the French version of this file for the text to be used
% for languages other than English.


% == FORDOC == %

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

\NewDocumentCommand{ \tdocdocbasicinput }{ m }{%
    Consider the following code.

    \tdoclatexinput[code]{#1}

    This will produce the following.

    \input{#1}
}


% == FORDOC == %

% 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{ Start of the rendering in this doc. }
                         O{ End of rendering in this doc. } }{
        \tdocdocextraruler{#1}
        \nopagebreak\smallskip\nopagebreak
}{
        \nopagebreak\smallskip\nopagebreak
        \tdocdocextraruler{#2}
}


\begin{document}


\title{The \texttt{tutodoc} package - Tutorial-style documentation}
\author{Christophe BAL}
\date{Sep 28, 2024 - Version 1.4.0}

\maketitle

\begin{abstract}
    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{General formatting imposed}

\subsection{Page geometry}

The \tdocpack{geometry} package is loaded with the following settings.


\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{Title and table of contents}

The \tdocpack{titlesec} and \tdocpack{tocbasic} packages are set as follows.


\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{Dynamic links}

The \tdocpack{hyperref} package is imported behind the scenes with the settings below.


\begin{tdoclatex}[code]
\hypersetup{
  colorlinks,
  citecolor = orange!75!black,
  filecolor = orange!75!black,
  linkcolor = orange!75!black,
  urlcolor  = orange!75!black
}
\end{tdoclatex}


\section{Select language when loading package}

By default, \thispack{} is set for English, but it is possible to change the language: for example, a French documentation will use \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
For the moment, we only have the following two choices.

\begin{enumerate}
    \item \tdocinlatex|english| is the default value.

    \item \tdocinlatex|french|
\end{enumerate}


\begin{tdocnote}
    Language names are those suggested by the \tdocpack{babel} package.
\end{tdocnote}


\section{What does that mean in \tdocquote{English}?}

The macro \tdocmacro{tdocinEN} and its starred version are useless for English speakers because they have the following effects.


\begin{tdoclatex}
Cool and top stand for \tdocinEN*{cool} and \tdocinEN{top}.
\end{tdoclatex}


The macro \tdocmacro{tdocinEN} and its starred version are based on \tdocmacro{tdocquote} : for example, \tdocquote{semantic} is obtained via \tdocinlatex|tdocquote{semantic}| .


\begin{tdocnote}
    As the text \tdocquote{in English} is translated into the language indicated when \thispack{} is imported, the macro \tdocmacro{tdocinEN} and its starred version become useful for non-English speakers.
\end{tdocnote}


\section{Highlighting content}

\begin{tdocnote}
    The environments presented in this section
    \footnote{
        The formatting comes from the \tdocpack{keytheorems} package.
    }
    add a short title indicating the type of information provided.
    This short text will always be translated into the language indicated when the \thispack{} package is loaded.
\end{tdocnote}


\subsection{Content in the reading flow}


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


\begin{tdocimp}
    All the environments presented in this section share the same counter.
\end{tdocimp}


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


\subsubsection{Examples}

Numbered examples, if required, are indicated via \tdocenv{tdocexa}, which offers an optional argument for adding a mini-title.
Here are two possible uses.

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



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


\begin{tdocimp}
    The numbering of the examples is reset to zero as soon as a section with a level at least equal to a \tdocinlatex|\section| is opened.
\end{tdocimp}


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


\begin{tdoctip}
    It can sometimes be useful to return to the line at the start of the content. The code below shows how to proceed (this trick also applies to the \verb#tdocrem# environment presented next). Note in passing that the numbering follows that of the previous example as desired.
\end{tdoctip}

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



% \subsection{Content in the reading flow}

\subsubsection{Some remarks}

Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocenv*{tdocexa} environment, as shown in the following example.

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



\subsection{Flashy content} \label{tdoc-colorful-focus}

\begin{tdocnote}
    Icons are obtained via the \tdocpack{fontawesome5} package, and text spacing is managed by the \tdocmacro{tdocicon} macro.
    \footnote{
        For example,
        \tdocinlatex|\tdocicon{\faBed}{Tired}|
        produces\,
        \tdocicon{\faBed}{Tired}.
    }
\end{tdocnote}


\subsubsection{A tip}

The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it.

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



\smallskip

\begin{tdocnote}
    Colors are obtained via the expandable macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor}.
    For further information, please refer to the end of the section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}.
\end{tdocnote}


%\subsection{Flashy content}

\subsubsection{Informative note}

The \tdocenv*{tdocnote} environment is used to highlight useful information. Here's how to use it.

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



%\subsection{Flashy content}

\subsubsection{Something important}

The \tdocenv*{tdocimp} environment is used to indicate something important but harmless.

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



%\subsection{Flashy content}

\subsubsection{Caution about a delicate point}

The \tdocenv*{tdoccaut} environment is used to indicate a delicate point to the user. Here's how to use it.

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



%\subsection{Flashy content}

\subsubsection{Warning of danger}

The \tdocenv*{tdocwarn} environment is used to warn the user of a trap to avoid. Here's how to use it.

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



\section{Specify packages, classes, macros or environments}

Here's what you can type semantically.


\begin{tdoclatex}[sbs]
\tdoccls{myclass} is for...              \\
\tdocpack{mypackage} is for...           \\
\tdocmacro{onemacro} is for...           \\
\tdocenv{env} produces...                \\
\tdocenv[{[opt1]<opt2>}]{env}            \\
Just \tdocenv*{env}...                   \\
Finally \tdocenv*[{[opt1]<opt2>}]{env}...
\end{tdoclatex}


\begin{tdocrem}
	Unlike \tdocmacro{tdocinlatex}, \tdocmacro{tdocenv} and \tdocmacro{tdocenv*} macros don't color the text they produce.
    In addition, \tdocinlatex{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if required.
\end{tdocrem}


\begin{tdocwarn}
	The optional argument of the \tdocmacro{tdocenv} macro is copied and pasted
    \footnote{
        Remember that almost anything is possible from now on.
    }
    when rendering. This may sometimes require the use of protective braces, as in the example above.
\end{tdocwarn}



\section{Origin of a prefix or suffix}

To explain the names chosen, there is nothing like indicating and explaining the short prefixes and suffixes used. This is easily done as follows.


\begin{tdoclatex}[sbs]
\tdocpre{sup} relates to...      \\
\tdocprewhy{sup.erbe} means...   \\
\emph{\tdocprewhy{sup.er} for...}
\end{tdoclatex}


\begin{tdocrem}
    The choice of a full stop to split a word allows words with a hyphen to be used, as in \tdocinlatex+\tdocprewhy{bric.k-breaker}+ which gives \tdocprewhy{bric.k-breaker}.
\end{tdocrem}


\section{A real-life rendering} \label{tdoc-showcase}

It is sometimes useful to render code directly in the documentation. This type of rendering must be dissociable from the explanatory text.



\subsection{With a coloured stripe} \label{tdoc-color-macros}

\begin{tdocexa} [With default text]
    It can be useful to show a real rendering directly in a document.
    \footnote{
        Typically when making a demo.
    }
    This is done via \tdocenv{tdocshowcase} as follows.

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


    The result is the following rendering.
    \footnote{
        Behind the scenes, the strip is created effortlessly using the \tdocpack{clrstrip} package.
    }
\end{tdocexa}

\input{examples-showcase-default.tex}



\smallskip

\begin{tdocrem}
    See the section \ref{tdoc-latexshow} on page \pageref{tdoc-latexshow} to easily obtain code followed by its actual rendering as in the previous example.
\end{tdocrem}


\begin{tdocnote}
    The explanatory texts adapt to the language chosen when \thispack{} is loaded.
\end{tdocnote}


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


\begin{tdocexa}[Change the default colour and/or text]
    \leavevmode

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


    This will produce the following.

    \medskip

    \input{examples-showcase-customized.tex}

\end{tdocexa}


\begin{tdocnote}
    You've probably noticed that red is used as a base to obtain the colors used.

    \begin{itemize}
    	\item The background color is provided by \tdocmacro{tdocbackcolor}.

    	\item The color of titles and lines is provided by \tdocmacro{tdocdarkcolor}.
    \end{itemize}

    These expandable macros accept the following codes.

    \begin{tdoclatex}[code]
% Argument 1 : optionally, the amount of color relative to black can be specified.
%              In general, there's no need to change this setting!
% Argument 2 : a color in xcolor format.
\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}

% Argument 1 : optionally, the transparency rate can be specified.
%              In general, there's no need to change this setting!
% Argument 2 : a color in xcolor format.
\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
    \end{tdoclatex}

    You also have to know that behind the scene, the \tdocmacro{tdocruler} macro is used.

    \begin{tdoclatex}[std]
        \tdocruler{A decorated pseudo-title}{red}
    \end{tdoclatex}
\end{tdocnote}


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


\begin{tdocwarn}
    With the default settings, if the code to be formatted begins with an opening bracket, use \tdocmacro{string} as in the following example.

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


    This will produce the following.
\end{tdocwarn}


\input{examples-showcase-hook.tex}



\subsection{Without a colour strip}

The rendering of \tdocenv{tdocshowcase} with a coloured strip may not be suitable, or sometimes may not be acceptable despite the work done by \tdocpack{clrstrip}.
It is possible not to use a coloured strip, as we will see straight away.


\begin{tdocexa}
    The use of \tdocenv[{[nostripe]}]{tdocshowcase} indicate to not use \tdocpack{clrstrip}.
    Here is an example.

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


    This will produce the following.

    \medskip

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

\end{tdocexa}


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


\begin{tdocexa}[Change the default colour and/or text]
    \leavevmode

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


    This will produce the following.

    \medskip

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

\end{tdocexa}


\subsection{By importing the \LaTeX\ code}

To obtain renderings by importing the code from an external file, instead of typing it, simply use the \tdocmacro{tdocshowcaseinput} macro whose option uses the syntax of that of \tdocenv{tdocshowcase} and the mandatory argument corresponds to the path of the file.


\begin{tdocexa}
    The following was obtained via \tdocinlatex+\tdocshowcaseinput{external.tex}+.

    \medskip

    \tdocshowcaseinput{examples-showcase-external.tex}


    \medskip

    As for \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+\,, this will produce the colour change shown below.

    \medskip

    \tdocshowcaseinput[color = orange]{examples-showcase-external.tex}

\end{tdocexa}


\section{Use cases in \LaTeX}

Documenting a package or class is best done through use cases showing both the code and the corresponding result.
\footnote{
	Code is formatted using the \tdocpack{minted} package.
}


\begin{tdoccaut}
	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 minted.

\end{tdoccaut}


\subsection{\tdocquote{Inline} codes} \label{tdoc-listing-inline}

The \tdocmacro{tdocinlatex} macro
\footnote{
    The name of the macro \tdocmacro{tdocinlatex} comes from \tdocquote{\tdocprewhy{in.line} \LaTeX}.
}
can be used to type inline code in a similar way to \tdocmacro{verb}.
Here are some examples.


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

    2: \tdocinlatex+\tdocinlatex|$a^b = c$|+
\end{tdoclatex}


\begin{tdocnote}
    The \tdocmacro{tdocinlatex} macro can be used in a footnote: see below.
    \footnote{
        \tdocinlatex+$minted = TOP$+ has been typed \tdocinlatex|\tdocinlatex+$minted = TOP$+| in this footnote...
    }
    In addition, a background color is deliberately used to subtly highlight the codes \tdocinlatex#\LaTeX#\,.
\end{tdocnote}


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


\subsection{Directly typed codes}

\begin{tdocexa}[Side by side]
    Using \tdocenv[{[sbs]}]{tdoclatex}, we can display a code and its rendering side by side.
    \tdocdocbasicinput{examples-listing-ABC.tex}

\end{tdocexa}


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


\begin{tdocexa}[Following]
    \tdocenv{tdoclatex} produces the following result, which corresponds to the default option \tdocinlatex#std#\,.
    \footnote{
        \tdocinlatex{std} refers to the \tdocquote{standard} behaviour of \tdocpack{tcolorbox} in relation to the \tdocpack{minted} library.
    }

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


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


\begin{tdocexa}[Just the code]
    Via \tdocenv[{[code]}]{tdoclatex}, we'll just get the code as shown below.

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


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


\begin{tdocwarn}
    With default formatting, if the code begins with an opening bracket, the default option must be explicitly indicated.
    \tdocdocbasicinput{examples-listing-strange.tex}


    \smallskip

    Another method is to use the \tdocmacro{string} primitive.
    \tdocdocbasicinput{examples-listing-strange-bis.tex}

\end{tdocwarn}


\subsection{Imported codes}

For the following codes, consider a file with the relative path \verb+examples-listing-xyz.tex+, and with the following contents.

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


\medskip

The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same options as the \tdocenv*{tdoclatex} environment.


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


\begin{tdocexa}[Side by side]
    \leavevmode

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

    \end{tdoclatex}

    This produces the following layout.

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

\end{tdocexa}


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


\begin{tdocexa}[Following]
    \leavevmode

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

    \end{tdoclatex}

    This produces the following formatting where the default option is \tdocinlatex#std#.

    \tdoclatexinput{examples-listing-xyz.tex}

\end{tdocexa}


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


\begin{tdocexa}[Just the code]
    \leavevmode

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

    \end{tdoclatex}

    This produces the following layout.

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

\end{tdocexa}


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


\subsection{Imported codes put into practice} \label{tdoc-latexshow}

\begin{tdocexa}[Showcase]
    The following comes from \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+.

    \medskip

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

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


\begin{tdocnote}
    The default texts take into account the language chosen when loading the package \thispack{}.
\end{tdocnote}


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


\begin{tdocexa}[Changing the explanatory text]
    Using the key \tdocinlatex|explain|, you can use custom text. Thus, \tdocinlatex|tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex}| will produce the following.

    \medskip

    \begin{tdoc-doc-showcase}
        \tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex}

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


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


\begin{tdocexa}[The options available]
    In addition to the explanatory text, it is also possible to use all the options of \tdocenv*{tdocshowcase} environment, see \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
    Here is an example to illustrate this.

    \medskip

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


    \medskip

    This will produce the following.

    \medskip

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

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


\section{Indicate changes}

To make it easier to monitor a package, it is essential to provide a history indicating the changes made when a new version is published.



\subsection{When?}

You can either date something, or version it, in which case the version number can be dated.


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


\begin{tdocexa}[Dating new products]
    The \tdocmacro{tdocdate} macro is used to indicate a date in the margin, as in the following example.

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

\end{tdocexa}


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


\begin{tdocexa}[Versioning new features, possibly with a date]
    Associating a version number with a new feature is done using the \tdocmacro{tdocversion} macro, with the colour and date being optional arguments.

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

\end{tdocexa}


\begin{tdocimp}
    \begin{enumerate}
        \item The \tdocmacro{tdocdate} and \tdocmacro{tdocversion} macros require two compilations.

        \item The final rendering of the dates takes into account the language specified when loading the package \thispack{}: for example, if French is selected, the dates will be displayed in the format \texttt{DD/MM/YYYY}.
    \end{enumerate}
\end{tdocimp}


\begin{tdocwarn}
    Only the use of the digital format \tdocinlatex+YYYY-MM-DD+ is verified.
    \footnote{
        Technically, checking the validity of a date using \LaTeX3 presents no difficulty.
    },
    and this is a choice! Why? Quite simply because dating and versioning explanations should be done semi-automatically to avoid any human bugs.
\end{tdocwarn}


\subsection{What's new?}

\thispack{} offers the macro \tdocmacro{tdocstartproj} and different environments to indicate quickly and clearly what has been done during the latest changes.%
\footnote{
    The user doesn't need all the technical details.
}


\begin{tdocnote}
    For icons, see the note at the beginning of the section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
\end{tdocnote}


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


\begin{tdocexa}[Just for the very first version]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[For new features]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[For updates]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[For breaks]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[For problems]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[For fixes]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Selectable themes with an icon]
    \leavevmode

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

\end{tdocexa}


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


\begin{tdocexa}[Selectable themes without icons]
    \leavevmode

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

\end{tdocexa}


\section{Ornaments}

Let's finish this documentation with a small formatting tool that is very useful.


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

\tdocsep % Practical for demarcation.

This works with enumerations.

\begin{itemize}
    \item Underline.
\end{itemize}

\tdocsep % Uniform behaviour.

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


\section{History}

\small

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

\begin{tdocbreak}
	\item The \tdocenv*{tdoccaution} environment has been renamed \tdocenv*{tdoccaut} for simplified input.

	\item Content highlighting: examples and remarks, indicated via the \tdocenv*{tdocexa} and \tdocenv*{tdocrem} environments, are always numbered, and share the same counter.

	\item The unused macro \tdocmacro{tdocxspace} has been deleted.
\end{tdocbreak}


\begin{tdocnew}
    \item Change log: the \tdocmacro{tdocstartproj} macro is used to manage the case of the first public version.

    \item Code factorization: the \tdocmacro{tdocicon} macro is responsible for adding icons in front of text.
\end{tdocnew}


\begin{tdocupdate}
	\item Colors: the \tdocmacro{tdocdarkcolor} and \tdocmacro{tdoclightcolor} macros offer an optional argument.
	\begin{enumerate}
		\item \tdocmacro{tdocdarkcolor} : the amount of color in relation to black can be optionally defined.

		\item \tdocmacro{tdoclightcolor} : the transparency rate can be optionally defined.
	\end{enumerate}

    \item Content highlighting: reduced space around content in colored frames.

	\item Versioning: better vertical spacing thanks to \tdocmacro{vphantom}.
\end{tdocupdate}

\tdocsep


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


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

\begin{tdocnew}
    \item Star version of \tdocmacro{tdocenv} to display only the environment name.
\end{tdocnew}

\tdocsep


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


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

\begin{tdocprob}
	\item Version 3 of \tdocpack{minted} cannot be used for 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{tdocprob}


\begin{tdocbreak}
	\item The \tdocenv*{tdocimportant} environment has been renamed \tdocenv*{tdocimp} for simplified input.
\end{tdocbreak}


\begin{tdocnew}
    \item Change log: proposed environments use icons.


    \item Content highlighting: colored frames with icons are proposed for the following environments.
    \bgroup
    \setlength\multicolsep{5pt}
    \begin{multicols}{3}
        \begin{enumerate}[topsep=0pt]
        	\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 The version number is above the date.

        \item The spacing is better managed when the date is absent.
    \end{enumerate}
\end{tdocupdate}


\begin{tdocfix}
    \item Content highlighting: the French translations of \tdocinEN*{caution} and \tdocinEN*{danger} were incorrect.
\end{tdocfix}

\tdocsep


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


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

\begin{tdocnew}
    \item Change log : two new environments.
    \begin{enumerate}
        \item \tdocenv{tdocbreak} for breaking changes which are not backward compatible.

        \item \tdocenv{tdocprob} for identified problems.
    \end{enumerate}

    \item \tdocmacro{tdocinlatex}: a light yellow is used as the background color.
\end{tdocnew}

\tdocsep


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


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

\begin{tdocfix}
    \item \tdocmacro{tdocenv}: spacing is now correct, even if the \tdocpack{babel} package is not loaded with the French language.

    \item \tdocenv[{[nostripe]}]{tdocshowcase}: page breaks around \tdocquote{framing} lines should be rare from now on.
\end{tdocfix}

\tdocsep


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


\tdocversion{1.0.0}[2023-11-29]

\tdocstartproj{First public version of the project.}

\end{document}