texlive[72384] Master/texmf-dist: tutodoc (25sep24)
commits+karl at tug.org
commits+karl at tug.org
Wed Sep 25 21:28:01 CEST 2024
Revision: 72384
https://tug.org/svn/texlive?view=revision&revision=72384
Author: karl
Date: 2024-09-25 21:28:01 +0200 (Wed, 25 Sep 2024)
Log Message:
-----------
tutodoc (25sep24)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2024-09-25 19:27:52 UTC (rev 72383)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2024-09-25 19:28:01 UTC (rev 72384)
@@ -1,30 +1,103 @@
+% ==================== %
+% == RESOURCES USED == %
+% ==================== %
-% -------------------- %
-% -- RESOURCES USED -- %
-% -------------------- %
+\begin{filecontents*}[overwrite]{examples-version-n-change-dating.tex}
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
-\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
-Bla, bla, bla...
+\medskip % CAUTION! This prevents overlapping.
-\begin{tdocexa}
- Ble, ble, ble...
-\end{tdocexa}
+\tdocdate{2023-09-24}
-\begin{tdocexa}[Wonderful]
- Bli, bli, bli...
-\end{tdocexa}
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
-\begin{tdocexa}<nonb>
- Blo, blo, blo...
-\end{tdocexa}
+\medskip % CAUTION! This prevents overlapping.
-\begin{tdocexa}<nonb>[Superb]
- Blu, blu, blu...
-\end{tdocexa}
+\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}
+% This is where the point needs to be put.
+ \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-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
@@ -38,28 +111,17 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
-\begin{tdocrem}
- Just one remark...
-\end{tdocrem}
+\begin{filecontents*}[overwrite]{examples-focus-important.tex}
+\begin{tdocimp}
+ Important and harmless.
+\end{tdocimp}
-\begin{tdocrem}[Mini title]
+\begin{tdocimp}[Mini title]
Useful?
-\end{tdocrem}
+\end{tdocimp}
\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-note.tex}
\begin{tdocnote}
Something useful to tell you...
@@ -71,17 +133,6 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-important.tex}
-\begin{tdocimportant}
- Important and harmless.
-\end{tdocimportant}
-
-\begin{tdocimportant}[Mini title]
- Useful?
-\end{tdocimportant}
-\end{filecontents*}
-
-
\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
\begin{tdoccaution}
Caution, caution...
@@ -93,6 +144,17 @@
\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...
@@ -104,55 +166,47 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-showcase-default.tex}
-\begin{tdocshowcase}
- \bfseries A bit of code \LaTeX.
+\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
+Bla, bla, bla...
- \bigskip
+\begin{tdocexa}
+ Ble, ble, ble...
+\end{tdocexa}
- \emph{\large End of the awful demo.}
-\end{tdocshowcase}
-\end{filecontents*}
+\begin{tdocexa}[Wonderful]
+ Bli, bli, bli...
+\end{tdocexa}
+\begin{tdocexa}<nonb>
+ Blo, blo, blo...
+\end{tdocexa}
-\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}
+\begin{tdocexa}<nonb>[Superb]
+ Blu, blu, blu...
+\end{tdocexa}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-showcase-hook.tex}
-\begin{tdocshowcase}
- \string[This works...]
-\end{tdocshowcase}
-\end{filecontents*}
+\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
+\begin{tdocrem}
+ Just one remark...
+\end{tdocrem}
-
-\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}
+\begin{tdocrem}[Mini title]
+ Useful?
+\end{tdocrem}
\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}
+\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-showcase-external.tex}
-Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
-\end{filecontents*}
-
-
\begin{filecontents*}[overwrite]{examples-listing-ABC.tex}
\begin{tdoclatex}[sbs]
$A = B + C$
@@ -160,6 +214,12 @@
\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!]
@@ -174,111 +234,59 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-listing-xyz.tex}
-% Just one demo.
-$x y z = 1$
+\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-listing-latexshow-options.tex}
-\tdoclatexshow[explain = What comes next is colourful...,
- before = Rendering below.,
- after = Finished rendering.,
- color = orange]
- {examples-listing-xyz.tex}
+\begin{filecontents*}[overwrite]{examples-showcase-hook.tex}
+\begin{tdocshowcase}
+ \string[This works...]
+\end{tdocshowcase}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-dating.tex}
-Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
-
-\medskip % 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...
+\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-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...
+\begin{filecontents*}[overwrite]{examples-showcase-external.tex}
+Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
\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-showcase-default.tex}
+\begin{tdocshowcase}
+ \bfseries A bit of code \LaTeX.
+ \bigskip
-\begin{filecontents*}[overwrite]{examples-version-n-change-update.tex}
-\begin{tdocupdate}
- \item Info 1...
- \item Info 2...
-\end{tdocupdate}
+ \emph{\large End of the awful demo.}
+\end{tdocshowcase}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex}
-\begin{tdocbreak}
- \item Info 1...
- \item Info 2...
-\end{tdocbreak}
+\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*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-pb.tex}
-\begin{tdocprob}
- \item Info 1...
- \item Info 2...
-\end{tdocprob}
-\end{filecontents*}
+% ======================== %
+% == SOURCE FOR THE DOC == %
+% ======================== %
-
-\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-version-n-change-user-choice.tex}
-\begin{tdoctopic}{It's my choice}
-% This is where the point needs to be put.
- \item Info 1...
- \item Info 2...
-\end{tdoctopic}
-\end{filecontents*}
-
-
-% ------------------------ %
-% -- SOURCE FOR THE DOC -- %
-% ------------------------ %
-
\documentclass[10pt, a4paper]{article}
\usepackage[utf8]{inputenc}
@@ -288,15 +296,36 @@
\usepackage{enumitem}
-\usepackage{tabularray}
+\usepackage{multicol}
+
\usepackage{fmtcount}
\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
@@ -311,6 +340,8 @@
}
+% == FORDOC == %
+
% Source.
% * https://tex.stackexchange.com/a/604698/6880
@@ -340,30 +371,34 @@
}
-
\begin{document}
-\title{The \texttt{tutodoc} package - Tutorial-type documentation}
+
+\title{The \texttt{tutodoc} package - Tutorial-style documentation}
\author{Christophe BAL}
-\date{23 Aug. 2024 - Version 1.2.0-a}
+\date{Sep 25, 2024 - Version 1.3.0}
\maketitle
\begin{abstract}
-The \tdocpack{tutodoc} 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.
+ 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
-\begin{tdocnote}
- This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package.
-\end{tdocnote}
+ 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}
@@ -370,6 +405,8 @@
\newpage
\tableofcontents
\newpage
+
+
\section{General formatting imposed}
\subsection{Page geometry}
@@ -458,7 +495,7 @@
\section{Select language when loading package}
-By default, \tdocpack{tutodoc} is set for English, but it is possible to change the language: for example, a French documentation will use \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
+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}
@@ -487,7 +524,7 @@
\begin{tdocnote}
- As the text \tdocquote{in English} is translated into the language indicated when \tdocpack{tutodoc} is imported, the macro \tdocmacro{tdocinEN} and its starred version become useful for non-English speakers.
+ 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}
@@ -496,16 +533,14 @@
\begin{tdocnote}
The environments presented in this section
\footnote{
- The formatting comes from the \tdocpack{amsthm} package.
+ 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 \tdocpack{tutodoc} package is loaded.
+ This short text will always be translated into the language indicated when the \thispack{} package is loaded.
\end{tdocnote}
-% ------------------ %
-
\subsection{Examples}
Numbered or unnumbered examples can be indicated using the \tdocenv{tdocexa} environment, which offers two optional arguments.
@@ -522,12 +557,13 @@
\tdoclatexinput[sbs]{examples-focus-exa.tex}
+
% ------------------ %
-\begin{tdocimportant}
+\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|\subsubsection| is opened.
-\end{tdocimportant}
+\end{tdocimp}
% ------------------ %
@@ -537,6 +573,7 @@
It can sometimes be useful to return to the line at the start of the content. Here's how to do it (this trick remains valid for the environments presented in the following sub-sections). Note in passing that the numbering follows that of the previous example as desired.
\tdoclatexinput[sbs]{examples-focus-exa-leavevmode.tex}
+
\end{tdoctip}
@@ -547,6 +584,7 @@
\tdoclatexinput[sbs]{examples-focus-rmk.tex}
+
\subsection{A tip}
The \tdocenv{tdoctip} environment is used to give tips. Here's how to use it.
@@ -554,6 +592,19 @@
\tdoclatexinput[sbs]{examples-focus-tip.tex}
+
+\smallskip
+
+\begin{tdocnote}
+ Colors are provided by the extensible macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor}, which have the following codes.
+
+ \begin{tdoclatex}[code]
+\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
+\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
+ \end{tdoclatex}
+\end{tdocnote}
+
+
\subsection{Informative note}
The \tdocenv{tdocnote} environment is used to highlight useful information. Here's how to use it.
@@ -561,13 +612,15 @@
\tdoclatexinput[sbs]{examples-focus-note.tex}
+
\subsection{Something important}
-The \tdocenv{tdocimportant} environment is used to indicate something important but harmless.
+The \tdocenv{tdocimp} environment is used to indicate something important but harmless.
\tdoclatexinput[sbs]{examples-focus-important.tex}
+
\subsection{Caution about a delicate point}
The \tdocenv{tdoccaution} environment is used to indicate a delicate point to the user. Here's how to use it.
@@ -575,6 +628,7 @@
\tdoclatexinput[sbs]{examples-focus-caution.tex}
+
\subsection{Warning of danger}
The \tdocenv{tdocwarn} environment is used to warn the user of a trap to avoid. Here's how to use it.
@@ -582,6 +636,7 @@
\tdoclatexinput[sbs]{examples-focus-warn.tex}
+
\section{Specify packages, classes, macros or environments}
Here's what you can type semantically.
@@ -621,9 +676,7 @@
\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.
@@ -648,31 +701,31 @@
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}
\begin{tdocexa} [With default text]
- It can be useful to show a real rendering directly in a document
+ 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
+
+ The result is the following rendering.
\footnote{
Behind the scenes, the strip is created effortlessly using the \tdocpack{clrstrip} package.
- }.
+ }
+\end{tdocexa}
- \medskip
+\input{examples-showcase-default.tex}
- \input{examples-showcase-default.tex}
-\end{tdocexa}
+\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}
@@ -679,7 +732,7 @@
\begin{tdocnote}
- The explanatory texts adapt to the language chosen when \tdocpack{tutodoc} is loaded.
+ The explanatory texts adapt to the language chosen when \thispack{} is loaded.
\end{tdocnote}
@@ -691,22 +744,37 @@
\tdoclatexinput[code]{examples-showcase-customized.tex}
+
This will produce the following.
\medskip
\input{examples-showcase-customized.tex}
+
\end{tdocexa}
\begin{tdocnote}
- You will have noticed that we don't obtain a pure red: behind the scenes, the expandable macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor} are used to create the background and title colours respectively from the ones proposed in \tdocenv{tdocshowcase}.
- These macros have a single argument, the chosen colour, and accept the following codes.
+ 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 have a single argument, the chosen color, and accept the following codes.
+
\begin{tdoclatex}[code]
-\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
-\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
+\NewExpandableDocumentCommand{tdocbackcolor}{m}{#1!5}
+\NewExpandableDocumentCommand{tdocdarkcolor}{m}{#1!50!black}
\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}
@@ -718,21 +786,13 @@
\tdoclatexinput[code]{examples-showcase-hook.tex}
+
This will produce the following.
-
- \medskip
-
- \input{examples-showcase-hook.tex}
\end{tdocwarn}
-\begin{tdocnote}
- Behind the scenes, the \tdocmacro{tdocruler} macro is used.
+\input{examples-showcase-hook.tex}
- \begin{tdoclatex}[std]
- \tdocruler{Un pseudo-titre décoré}{red}
- \end{tdoclatex}
-\end{tdocnote}
\subsection{Without a colour strip}
@@ -747,11 +807,13 @@
\tdoclatexinput[code]{examples-showcase-no-clrstrip.tex}
+
This will produce the following.
\medskip
\input{examples-showcase-no-clrstrip.tex}
+
\end{tdocexa}
@@ -763,11 +825,13 @@
\tdoclatexinput[code]{examples-showcase-no-clrstrip-customized.tex}
+
This will produce the following.
\medskip
\input{examples-showcase-no-clrstrip-customized.tex}
+
\end{tdocexa}
@@ -783,6 +847,7 @@
\tdocshowcaseinput{examples-showcase-external.tex}
+
\medskip
As for \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+\,, this will produce the colour change shown below.
@@ -790,17 +855,18 @@
\medskip
\tdocshowcaseinput[color = orange]{examples-showcase-external.tex}
+
\end{tdocexa}
\section{Use cases in \LaTeX}
-Documenting a package or a class is done efficiently using use cases showing both the code and the corresponding result.
+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.
+}
-% ------------------ %
-
-
\subsection{\tdocquote{Inline} codes} \label{tdoc-listing-inline}
The \tdocmacro{tdocinlatex} macro
@@ -822,7 +888,7 @@
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}
@@ -835,6 +901,7 @@
\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}
@@ -842,10 +909,10 @@
\begin{tdocexa}[Following]
- \tdocenv{tdoclatex} produces the following result, which corresponds to the default option \tdocinlatex#std#
+ \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$
@@ -872,10 +939,12 @@
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}
@@ -885,6 +954,7 @@
\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.
@@ -898,11 +968,13 @@
\begin{tdoclatex}[code]
\tdoclatexinput[sbs]{examples-listing-xyz.tex}
+
\end{tdoclatex}
This produces the following layout.
\tdoclatexinput[sbs]{examples-listing-xyz.tex}
+
\end{tdocexa}
@@ -914,11 +986,13 @@
\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}
@@ -930,11 +1004,13 @@
\begin{tdoclatex}[code]
\tdoclatexinput[code]{examples-listing-xyz.tex}
+
\end{tdoclatex}
This produces the following layout.
\tdoclatexinput[code]{examples-listing-xyz.tex}
+
\end{tdocexa}
@@ -950,12 +1026,13 @@
\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 \tdocpack{tutodoc}.
+ The default texts take into account the language chosen when loading the package \thispack{}.
\end{tdocnote}
@@ -969,6 +1046,7 @@
\begin{tdoc-doc-showcase}
\tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex}
+
\end{tdoc-doc-showcase}
\end{tdocexa}
@@ -984,6 +1062,7 @@
\tdoclatexinput[code]{examples-listing-latexshow-options.tex}
+
\medskip
This will produce the following.
@@ -992,6 +1071,7 @@
\begin{tdoc-doc-showcase}
\input{examples-listing-latexshow-options.tex}
+
\end{tdoc-doc-showcase}
\end{tdocexa}
@@ -1001,9 +1081,7 @@
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.
@@ -1016,6 +1094,7 @@
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}
@@ -1026,18 +1105,17 @@
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{tdocimportant}
- \leavevmode
-
+\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 \tdocpack{tutodoc}: for example, if French is selected, the dates will be displayed in the format \texttt{DD/MM/YYYY}.
+ \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{tdocimportant}
+\end{tdocimp}
\begin{tdocwarn}
@@ -1051,11 +1129,10 @@
\subsection{What's new?}
-\tdocpack{tutodoc} offers different environments to indicate quickly and clearly what has been done
+\thispack{} offers 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.
}
-during the latest changes.
\begin{tdocexa}[For new features]
@@ -1062,6 +1139,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+
\end{tdocexa}
@@ -1072,6 +1150,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+
\end{tdocexa}
@@ -1082,6 +1161,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-break.tex}
+
\end{tdocexa}
@@ -1092,6 +1172,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-pb.tex}
+
\end{tdocexa}
@@ -1102,6 +1183,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
+
\end{tdocexa}
@@ -1108,10 +1190,22 @@
% ------------------ %
-\begin{tdocexa}[Chosen topics]
+\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}
@@ -1147,30 +1241,75 @@
Blu, blu, blu...
\end{tdoclatex}
+
+
\section{History}
+\small
+
+\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 \verb#tdocimportant# environment has been renamed \verb#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}{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}
+ \item \tdocmacro{tdocversion}
\begin{enumerate}
- \item The version number is above the date.
+ \item The version number is above the date.
- \item The spacing is better managed when the date is absent.
+ \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.
+ \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.
+ \item Change log : two new environments.
\begin{enumerate}
\item \tdocenv{tdocbreak} for breaking changes which are not backward compatible.
@@ -1177,24 +1316,31 @@
\item \tdocenv{tdocprob} for identified problems.
\end{enumerate}
- \item \tdocmacro{tdocinlatex}: a light yellow is used as the background color.
+ \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 \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.
+ \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]
First public version of the project.
-
\end{document}
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2024-09-25 19:27:52 UTC (rev 72383)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2024-09-25 19:28:01 UTC (rev 72384)
@@ -1,30 +1,103 @@
+% ==================== %
+% == RESOURCES USED == %
+% ==================== %
-% -------------------- %
-% -- RESOURCES USED -- %
-% -------------------- %
+\begin{filecontents*}[overwrite]{examples-version-n-change-dating.tex}
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
-\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
-Bla, bla, bla...
+\medskip % ATTENTION ! Ceci évite le chevauchement.
-\begin{tdocexa}
- Ble, ble, ble...
-\end{tdocexa}
+\tdocdate{2023-09-24}
-\begin{tdocexa}[Magnifique]
- Bli, bli, bli...
-\end{tdocexa}
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
-\begin{tdocexa}<nonb>
- Blo, blo, blo...
-\end{tdocexa}
+\medskip % ATTENTION ! Ceci évite le chevauchement.
-\begin{tdocexa}<nonb>[Superbe]
- Blu, blu, blu...
-\end{tdocexa}
+\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
@@ -38,28 +111,17 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
-\begin{tdocrem}
- Juste une remarque...
-\end{tdocrem}
+\begin{filecontents*}[overwrite]{examples-focus-important.tex}
+\begin{tdocimp}
+ Un truc important sans danger.
+\end{tdocimp}
-\begin{tdocrem}[Mini titre]
+\begin{tdocimp}[Mini titre]
Utile ?
-\end{tdocrem}
+\end{tdocimp}
\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-note.tex}
\begin{tdocnote}
Un truc utile à vous dire...
@@ -71,17 +133,6 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-important.tex}
-\begin{tdocimportant}
- Un truc important sans danger.
-\end{tdocimportant}
-
-\begin{tdocimportant}[Mini titre]
- Utile ?
-\end{tdocimportant}
-\end{filecontents*}
-
-
\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
\begin{tdoccaution}
Prudence, prudence...
@@ -93,6 +144,17 @@
\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...
@@ -104,55 +166,47 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-showcase-default.tex}
-\begin{tdocshowcase}
- \bfseries Un peu de code \LaTeX.
+\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
+Bla, bla, bla...
- \bigskip
+\begin{tdocexa}
+ Ble, ble, ble...
+\end{tdocexa}
- \emph{\large Fin de l'affreuse démo.}
-\end{tdocshowcase}
-\end{filecontents*}
+\begin{tdocexa}[Magnifique]
+ Bli, bli, bli...
+\end{tdocexa}
+\begin{tdocexa}<nonb>
+ Blo, blo, blo...
+\end{tdocexa}
-\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}
+\begin{tdocexa}<nonb>[Superbe]
+ Blu, blu, blu...
+\end{tdocexa}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-showcase-hook.tex}
-\begin{tdocshowcase}
- \string[Cela fonctionne...]
-\end{tdocshowcase}
-\end{filecontents*}
+\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
+\begin{tdocrem}
+ Juste une remarque...
+\end{tdocrem}
-
-\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}
+\begin{tdocrem}[Mini titre]
+ Utile ?
+\end{tdocrem}
\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}
+\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-showcase-external.tex}
-Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
-\end{filecontents*}
-
-
\begin{filecontents*}[overwrite]{examples-listing-ABC.tex}
\begin{tdoclatex}[sbs]
$A = B + C$
@@ -160,6 +214,12 @@
\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 !]
@@ -174,111 +234,59 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-listing-xyz.tex}
-% Juste une démo.
-$x y z = 1$
+\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-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}
+\begin{filecontents*}[overwrite]{examples-showcase-hook.tex}
+\begin{tdocshowcase}
+ \string[Cela fonctionne...]
+\end{tdocshowcase}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-dating.tex}
-Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
-
-\medskip % ATTENTION ! Ceci évite le chevauchement.
-
-\tdocdate{2023-09-24}
-
-Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
-
-\medskip % ATTENTION ! Ceci évite le chevauchement.
-
-\tdocdate[gray]{2020-05-08}
-
-Bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli...
-
-Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo...
-
-Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu...
+\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-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...
+\begin{filecontents*}[overwrite]{examples-showcase-external.tex}
+Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
\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-showcase-default.tex}
+\begin{tdocshowcase}
+ \bfseries Un peu de code \LaTeX.
+ \bigskip
-\begin{filecontents*}[overwrite]{examples-version-n-change-update.tex}
-\begin{tdocupdate}
- \item Info 1...
- \item Info 2...
-\end{tdocupdate}
+ \emph{\large Fin de l'affreuse démo.}
+\end{tdocshowcase}
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex}
-\begin{tdocbreak}
- \item Info 1...
- \item Info 2...
-\end{tdocbreak}
+\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*}
-\begin{filecontents*}[overwrite]{examples-version-n-change-pb.tex}
-\begin{tdocprob}
- \item Info 1...
- \item Info 2...
-\end{tdocprob}
-\end{filecontents*}
+% ======================== %
+% == SOURCE FOR THE DOC == %
+% ======================== %
-
-\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-version-n-change-user-choice.tex}
-\begin{tdoctopic}{C'est mon choix}
-% Ici le point s'impose.
- \item Info 1...
- \item Info 2...
-\end{tdoctopic}
-\end{filecontents*}
-
-
-% ------------------------ %
-% -- SOURCE FOR THE DOC -- %
-% ------------------------ %
-
\documentclass[10pt, a4paper]{article}
\usepackage[utf8]{inputenc}
@@ -289,6 +297,10 @@
\usepackage{enumitem}
\frenchsetup{StandardItemLabels=true}
+\usepackage{multicol}
+
+\newcommand\thispack{\tdocpack{tutodoc}}
+
% Package documented.
\usepackage[lang = french]{tutodoc}
@@ -336,51 +348,63 @@
}
-
\begin{document}
+
\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe BAL}
-\date{23 Août 2024 - Version 1.2.0-a}
+\date{25 sept. 2024 - Version 1.3.0}
\maketitle
\begin{abstract}
-Le package \tdocpack{tutodoc}
-\footnote{
- Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} 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.
+ 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
-\begin{tdocnote}
- Ce package impose un style de mise en forme.
- Dans un avenir plus ou moins proche, \tdocpack{tutodoc} sera sûrement éclaté en une classe et un package.
-\end{tdocnote}
+ \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.
-\tdocsep
+ \item Cette documentation est aussi disponible en anglais.
+ \end{itemize}
-{\small\itshape
-\textbf{Abstract.}
-The \tdocpack{tutodoc} 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.
+ \tdocsep
+ {\small\itshape
+ \vspace{-5pt}
+ \begin{center}
+ \textbf{Abstract.}
+ \end{center}
-\begin{tdocnote}
- This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package.
-\end{tdocnote}
-}
+ 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}
@@ -387,6 +411,8 @@
\newpage
\tableofcontents
\newpage
+
+
\section{Mises en forme générales imposées}
\subsection{Géométrie de la page}
@@ -504,7 +530,7 @@
\begin{tdocnote}
- Le texte \tdocquote{en anglais} est traduit dans la langue indiquée lors de l'importation de \tdocpack{tutodoc}.
+ Le texte \tdocquote{en anglais} est traduit dans la langue indiquée lors de l'importation de \thispack{}.
\end{tdocnote}
@@ -513,16 +539,14 @@
\begin{tdocnote}
Les environnements présentés dans cette section
\footnote{
- La mise en forme provient du package \tdocpack{amsthm}.
+ 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 \tdocpack{tutodoc}.
+ 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.
@@ -539,12 +563,13 @@
\tdoclatexinput[sbs]{examples-focus-exa.tex}
+
% ------------------ %
-\begin{tdocimportant}
+\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{tdocimportant}
+\end{tdocimp}
% ------------------ %
@@ -554,6 +579,7 @@
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}
@@ -564,6 +590,7 @@
\tdoclatexinput[sbs]{examples-focus-rmk.tex}
+
\subsection{Une astuce}
L'environnement \tdocenv{tdoctip} sert à donner des astuces. Voici comment l'employer.
@@ -571,6 +598,19 @@
\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.
@@ -578,13 +618,15 @@
\tdoclatexinput[sbs]{examples-focus-note.tex}
+
\subsection{Un truc important}
-L'environnement \tdocenv{tdocimportant} permet d'indiquer quelque chose d'important mais sans danger.
+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.
@@ -592,6 +634,7 @@
\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.
@@ -599,6 +642,7 @@
\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.
@@ -638,9 +682,7 @@
\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.
@@ -665,9 +707,7 @@
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]
@@ -679,6 +719,7 @@
\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}.
@@ -687,6 +728,7 @@
\medskip
\input{examples-showcase-default.tex}
+
\end{tdocexa}
@@ -696,7 +738,7 @@
\begin{tdocnote}
- Les textes explicatifs s'adaptent à la langue choisie lors du chargement de \tdocpack{tutodoc}.
+ Les textes explicatifs s'adaptent à la langue choisie lors du chargement de \thispack{}.
\end{tdocnote}
@@ -708,22 +750,37 @@
\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 noté que l'on n'obtient pas un rouge pur : en coulisse les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor} sont utilisées pour créer celles du fond et des titres respectivement à partir de la couleur proposée à \tdocenv{tdocshowcase}.
- Ces macros à un seul argument, la couleur choisie, admettent les codes suivants.
+ 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}
@@ -735,23 +792,14 @@
\tdoclatexinput[code]{examples-showcase-hook.tex}
+
Ceci produira ce qui suit.
-
- \medskip
-
- \input{examples-showcase-hook.tex}
\end{tdocwarn}
+\input{examples-showcase-hook.tex}
-\begin{tdocnote}
- Il faut 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}
-
\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}.
@@ -764,11 +812,13 @@
\tdoclatexinput[code]{examples-showcase-no-clrstrip.tex}
+
Ceci produira ce qui suit.
\medskip
\input{examples-showcase-no-clrstrip.tex}
+
\end{tdocexa}
@@ -780,11 +830,13 @@
\tdoclatexinput[code]{examples-showcase-no-clrstrip-customized.tex}
+
Ceci produira ce qui suit.
\medskip
\input{examples-showcase-no-clrstrip-customized.tex}
+
\end{tdocexa}
@@ -800,6 +852,7 @@
\tdocshowcaseinput{examples-showcase-external.tex}
+
\medskip
Quant à \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+\,, ceci produira le changement de couleur observable ci-après.
@@ -807,15 +860,21 @@
\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.
+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}
@@ -836,17 +895,15 @@
\begin{tdocnote}
- La macro \tdocmacro{tdocinlatex} est utilisable dans une note de pied de page : voir plus bas
+ 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]
@@ -853,6 +910,7 @@
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}
@@ -860,10 +918,10 @@
\begin{tdocexa}[À la suite]
- \tdocenv{tdoclatex} produit le résultat suivant qui correspond à l'option par défaut \tdocinlatex#std#
+ \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$
@@ -890,10 +948,12 @@
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}
@@ -903,6 +963,7 @@
\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}.
@@ -916,11 +977,13 @@
\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}
@@ -932,11 +995,13 @@
\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}
@@ -948,17 +1013,17 @@
\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]
@@ -968,12 +1033,13 @@
\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 \tdocpack{tutodoc}.
+ Les textes par défaut tiennent compte de la langue choisie lors du chargement du package \thispack{}.
\end{tdocnote}
@@ -987,6 +1053,7 @@
\begin{tdoc-doc-showcase}
\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}
+
\end{tdoc-doc-showcase}
\end{tdocexa}
@@ -1002,6 +1069,7 @@
\tdoclatexinput[code]{examples-listing-latexshow-options.tex}
+
\medskip
Ceci va produire ce qui suit.
@@ -1010,6 +1078,7 @@
\begin{tdoc-doc-showcase}
\input{examples-listing-latexshow-options.tex}
+
\end{tdoc-doc-showcase}
\end{tdocexa}
@@ -1019,9 +1088,7 @@
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é.
@@ -1034,6 +1101,7 @@
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}
@@ -1044,18 +1112,17 @@
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{tdocimportant}
- \leavevmode
-
+\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{tdocimportant}
+\end{tdocimp}
\begin{tdocwarn}
@@ -1065,18 +1132,17 @@
}
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 \tdocpack{tutodoc} est entrain de mettre en place un ensemble d'outils permettant une telle semi-automatisation.
+% 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 ?}
+\subsection{Quoi de neuf ?}
-\tdocpack{tutodoc} propose différents environnements pour indiquer rapidement et clairement ce qui a été fait
+\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.
}
-lors des derniers changements.
\begin{tdocexa}[Pour les nouveautés]
@@ -1083,6 +1149,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+
\end{tdocexa}
@@ -1093,6 +1160,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+
\end{tdocexa}
@@ -1103,6 +1171,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-break.tex}
+
\end{tdocexa}
@@ -1113,6 +1182,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-pb.tex}
+
\end{tdocexa}
@@ -1123,6 +1193,7 @@
\leavevmode
\tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
+
\end{tdocexa}
@@ -1129,16 +1200,28 @@
% ------------------ %
-\begin{tdocexa}[Thématiques aux choix]
+\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 petites outils de mise en forme pouvant rendre de grands services.
+Finissons cette documentation avec de petits outils de mise en forme pouvant rendre de grands services.
\begin{tdoclatex}[sbs]
@@ -1168,30 +1251,75 @@
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}
+ \item \tdocmacro{tdocversion}
\begin{enumerate}
- \item Le numéro de version est au-dessus de la date.
+ \item Le numéro de version est au-dessus de la date.
- \item L'espacement est mieux géré lorsque la date est absente.
+ \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.
+ \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.
+ \item Journal des changements : deux nouveaux environnements.
\begin{enumerate}
\item \tdocenv{tdocbreak} pour les \tdocquote{bifurcations}\,, soit les modifications non rétrocompatibles.
@@ -1198,24 +1326,31 @@
\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.
+ \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 \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.
+ \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}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty 2024-09-25 19:27:52 UTC (rev 72383)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty 2024-09-25 19:28:01 UTC (rev 72384)
@@ -4,13 +4,13 @@
\NewDocumentCommand{\tutodoc at trans@latex at show@start}{}{Start ~ of ~ the ~ real ~ output}
\NewDocumentCommand{\tutodoc at trans@latex at show@end}{}{End ~ of ~ the ~ real ~ output}
\NewDocumentCommand{\tutodoc at trans@exa at title}{}{Example}
-\NewDocumentCommand{\tutodoc at trans@rmk at title}{}{Remark}
+\NewDocumentCommand{\tutodoc at trans@rem at title}{}{Remark}
\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Tip}
-\NewDocumentCommand{\tutodoc at trans@important at title}{}{Important}
+\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
\NewDocumentCommand{\tutodoc at trans@caution at title}{}{Caution}
\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Warning}
-\NewDocumentCommand{\tutodoc at trans@chges at pb}{}{Problem}
+\NewDocumentCommand{\tutodoc at trans@chges at prob}{}{Problem}
\NewDocumentCommand{\tutodoc at trans@chges at break}{}{Break}
\NewDocumentCommand{\tutodoc at trans@chges at fix}{}{Fix}
\NewDocumentCommand{\tutodoc at trans@chges at new}{}{New}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty 2024-09-25 19:27:52 UTC (rev 72383)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty 2024-09-25 19:28:01 UTC (rev 72384)
@@ -4,13 +4,13 @@
\NewDocumentCommand{\tutodoc at trans@latex at show@start}{}{Début ~ du ~ rendu ~ réel}
\NewDocumentCommand{\tutodoc at trans@latex at show@end}{}{Fin ~ du ~ rendu ~ réel}
\NewDocumentCommand{\tutodoc at trans@exa at title}{}{Exemple}
-\NewDocumentCommand{\tutodoc at trans@rmk at title}{}{Remarque}
+\NewDocumentCommand{\tutodoc at trans@rem at title}{}{Remarque}
\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Astuce}
-\NewDocumentCommand{\tutodoc at trans@important at title}{}{Important}
+\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
\NewDocumentCommand{\tutodoc at trans@caution at title}{}{Mise ~ en ~ garde}
\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Avertissement}
-\NewDocumentCommand{\tutodoc at trans@chges at pb}{}{Problème}
+\NewDocumentCommand{\tutodoc at trans@chges at prob}{}{Problème}
\NewDocumentCommand{\tutodoc at trans@chges at break}{}{Bifurcation}
\NewDocumentCommand{\tutodoc at trans@chges at fix}{}{Réparation}
\NewDocumentCommand{\tutodoc at trans@chges at new}{}{Nouveau}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-09-25 19:27:52 UTC (rev 72383)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-09-25 19:28:01 UTC (rev 72384)
@@ -1,18 +1,23 @@
-% ------------------------------------------------------- %
-% - This is file `tutodoc.sty' generated automatically. - %
-% - - %
-% - Copyright (C) 2023-2024 by Christophe BAL - %
-% - - %
-% - This file may be distributed and/or modified under - %
-% - the conditions of the GNU 3 License. - %
-% ------------------------------------------------------- %
+% ********************************************************* %
+% ** This is file `tutodoc.sty' generated automatically. ** %
+% ** ** %
+% ** Copyright (C) 2023-2024 by Christophe BAL ** %
+% ** ** %
+% ** This file may be distributed and/or modified under ** %
+% ** the conditions of the GNU 3 License. ** %
+% ********************************************************* %
\ProvidesExplPackage
- {tutodoc}
- {2024-08-23} % Creation: 2023-11-29
- {1.2.0-a}
- {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
+ {tutodoc}
+ {2024-09-25} % Creation: 2023-11-29
+ {1.3.0}
+ {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
+
+% =================== %
+% == PACKAGES USED == %
+% =================== %
+
\RequirePackage[
top = 2.5cm,
bottom = 2.5cm,
@@ -43,27 +48,54 @@
[2022-09-14]
-\RequirePackage{amsthm}%
- [2017/09]
+\RequirePackage{fontawesome5}%
+ [2022-05-02]
+\RequirePackage{keytheorems}%
+ [2024/09/19]
+\RequirePackage[svgnames]%
+ {xcolor}%
+ [2023/11/15]
+
+\RequirePackage{tcolorbox}%
+ [2024/07/10]
+
+\tcbuselibrary{breakable, skins}
+
+
\RequirePackage{clrstrip}%
[2021-08-28]
-\RequirePackage{tcolorbox}[2023/06/19]
+\RequirePackage{minted2}% Temporary patch? minted3 seems very slow8
+
+\RequirePackage{tcolorbox}%
+ [2024/07/10]
+
\tcbuselibrary{minted, breakable, skins}
+\RequirePackage{fontawesome5}%
+ [2022-05-02]
+
\RequirePackage{marginnote}%
[2023-09-07]
+% ======================= %
+% == AVAILABLE OPTIONS == %
+% ======================= %
+
+% ----------------- %
% -- LOCALE LANG -- %
+% ----------------- %
\ExplSyntaxOn
+% ::::::::::::::::::: %
% :: SOME MESSAGES :: %
+% ::::::::::::::::::: %
\msg_set:nnnn { tdoc } { package-option-lang-unknown }
{ Unknown ~ language. }
@@ -70,7 +102,9 @@
{ See ~ the ~ documentation ~ for ~ the ~ supported ~ languages. }
+% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
+% ::::::::::::::::::::::: %
\str_new:N \l_tdoc_opt_lang_str
@@ -97,7 +131,13 @@
\ExplSyntaxOff
+% =============== %
+% == MAIN CODE == %
+% =============== %
+
+% --------------------- %
% -- LOCALE SETTINGS -- %
+% --------------------- %
\NewDocumentCommand{\tutodoc at colon}{}{:}
@@ -115,12 +155,16 @@
\ExplSyntaxOff
+% ---------------------- %
% -- GENERAL SETTINGS -- %
+% ---------------------- %
\setlength{\parindent}{0cm}
+% ----------- %
% -- LINKS -- %
+% ----------- %
\hypersetup{
colorlinks,
@@ -131,7 +175,9 @@
}
+% --------------- %
% -- TOC & Co. -- %
+% --------------- %
\ifcsundef{chapter}%
{}%
@@ -173,7 +219,35 @@
\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section}
+% --------------------------- %
+% -- COLOR TRANSFORMATIONS -- %
+% --------------------------- %
+
+%%%
+% prototype::
+% #1 : one color following the ''xcolor'' format.
+%
+% :return: a "darker" version of the color ''#1''.
+%%%
+\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{%
+ #1!50!black%
+}
+
+
+%%%
+% prototype::
+% #1 : one color following the ''xcolor'' format.
+%
+% :return: a "transparent" version of the color `#1`.
+%%%
+\NewExpandableDocumentCommand{\tdoclightcolor}{m}{%
+ #1!5%
+}
+
+
+% ------------- %
% -- QUOTING -- %
+% ------------- %
%%%
% prototype::
@@ -186,7 +260,9 @@
}
+% ------------------------------ %
% -- EXPLAINING ENGLISH NAMES -- %
+% ------------------------------ %
%%%
% prototype::
@@ -215,9 +291,13 @@
}
-% -- FOCUS ON SOME CONTENT -- %
+% ----------------------------------- %
+% -- SOBER HIGHLIGHTING OF CONTENT -- %
+% ----------------------------------- %
+% ::::::::::::::::::::::::::::::: %
% :: EXAMPLE - HIDDEN VERSIONS :: %
+% ::::::::::::::::::::::::::::::: %
%%%
% See the \doc of the macro ''\newtheorem'' from the package ''amsthm''
@@ -240,7 +320,9 @@
\newtheorem*{@@tdocexa at no@nb}{\tutodoc at trans@exa at title}
+% :::::::::::::::::::::::::::::: %
% :: EXAMPLE - PUBLIC VERSION :: %
+% :::::::::::::::::::::::::::::: %
\ExplSyntaxOn
@@ -248,7 +330,7 @@
{ Unknown ~ rafters ~ option. }
{ See ~ the ~ documentation ~ for ~ the ~ supported ~ options. }
-\NewDocumentEnvironment{tdocexa}{D<>{nb} O{}}{
+\NewDocumentEnvironment{ tdocexa } { D<>{nb} O{} } {
\str_case:nnF { #1 } {
{ nb } {
\begin{@@tdocexa at nb}[#2]
@@ -261,7 +343,7 @@
}
}{
\str_case:nnF { #1 } {
- { nb } {
+ { nb } {
\end{@@tdocexa at nb}
}
{ nonb } {
@@ -273,61 +355,85 @@
\ExplSyntaxOff
+% :::::::::::: %
% :: REMARK :: %
+% :::::::::::: %
%%%
% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
% to have \infos about the environment ''tdocrem''.
%%%
-\newtheorem*{tdocrem}{\tutodoc at trans@rmk at title}
+\newtheorem*{tdocrem}{\tutodoc at trans@rem at title}
-% :: IMPORTANT :: %
+% -------------------------------------- %
+% -- COLORFUL HIGHLIGHTING OF CONTENT -- %
+% -------------------------------------- %
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdocimportant''.
-%%%
-\newtheorem*{tdocimportant}{\tutodoc at trans@important at title}
+% ::::::::::::::::: %
+% :: ABSTRACTION :: %
+% ::::::::::::::::: %
+% Sources used.
+% + https://tex.stackexchange.com/a/727022/6880
+% + https://tex.stackexchange.com/a/682332/6880
-% :: NOTE :: %
+\tcbset{
+ tutodoc-focus-color-style/.style = {
+ breakable,
+ enhanced,
+% fonttitle = \itshape,
+% halign title = center,
+ fontupper = \color{\tdocdarkcolor{#1}},
+ colback = \tdoclightcolor{#1},
+ colframe = #1!75!black!45,
+ shadow = {.75mm}{-.75mm}{0mm}{black!30},
+% We want to use the same color for the footnotes in the frame.
+ before upper = {\let\default at color\current at color},
+ }
+}
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdocnote''.
-%%%
-\newtheorem*{tdocnote}{\tutodoc at trans@note at title}
+% ::::::::::::::::::::::::::::::::::::: %
+% :: LET'S GO BACK TO THE REAL WORLD :: %
+% ::::::::::::::::::::::::::::::::::::: %
-% :: TIP :: %
+\ExplSyntaxOn
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdoctip''.
-%%%
-\newtheorem*{tdoctip}{\tutodoc at trans@tip at title}
+\prop_set_from_keyval:Nn \__g_tutodoc_focus_color_prop {
+ note = cyan,
+ tip = ForestGreen,%lime,
+ imp = orange,
+ caution = violet,
+ warn = red,
+}
+\prop_set_from_keyval:Nn \__g_tutodoc_focus_icon_prop {
+ note = \faInfoCircle,
+ tip = \faLightbulb,
+ imp = \faHighlighter,
+ caution = \faBiohazard,
+ warn = \faSkullCrossbones,
+}
-% :: CUATION :: %
+\prop_map_inline:Nn \__g_tutodoc_focus_color_prop {
+ \newkeytheorem{tdoc#1}[
+ numbered = false,
+% tcolorbox-no-titlebar can be used.
+ tcolorbox = {tutodoc-focus-color-style=#2},
+ name = {
+ \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } \kern3.5pt
+ \use:c { tutodoc at trans@#1 at title }
+ },
+ ]
+}
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdoccaution''.
-%%%
-\newtheorem*{tdoccaution}{\tutodoc at trans@caution at title}
+\ExplSyntaxOff
-% :: WARNING :: %
-
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdocwarn''.
-%%%
-\newtheorem*{tdocwarn}{\tutodoc at trans@warn at title}
-
-
+% ---------------------------------------------- %
% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- %
+% ---------------------------------------------- %
%%%
% prototype::
@@ -380,11 +486,15 @@
}
+% ------------------------- %
% -- EXPLAINING PREFIXES -- %
+% ------------------------- %
\ExplSyntaxOn
+% :::::::::::::: %
% :: MESSAGES :: %
+% :::::::::::::: %
\msg_set:nnnn { bdoc } { prefixwhy-bad-format }
{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
@@ -391,7 +501,9 @@
{ You ~ must ~ use ~ one ~ single ~ point. }
+% :::::::::::::::::::: %
% :: PREFIX FROM... :: %
+% :::::::::::::::::::: %
%%%
% prototype::
@@ -421,7 +533,9 @@
\ExplSyntaxOff
+% ::::::::::::::::::::: %
% :: JUST ONE PREFIX :: %
+% ::::::::::::::::::::: %
%%%
% prototype::
@@ -438,9 +552,13 @@
}
+% ------------------------ %
% -- GENERAL FORMATTING -- %
+% ------------------------ %
+% :::::::::::::::::::::::: %
% :: TEXT INSIDE A RULE :: %
+% :::::::::::::::::::::::: %
\ExplSyntaxOn
@@ -483,31 +601,9 @@
\ExplSyntaxOff
-% :: COLOR TRANSFORMATIONS :: %
-
-%%%
-% prototype::
-% #1 : one color following the ''xcolor'' format.
-%
-% :return: a "darker" version of the color ''#1''.
-%%%
-\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{%
- #1!50!black%
-}
-
-
-%%%
-% prototype::
-% #1 : one color following the ''xcolor'' format.
-%
-% :return: a "transparent" version of the color `#1`.
-%%%
-\NewExpandableDocumentCommand{\tdoclightcolor}{m}{%
- #1!5%
-}
-
-
+% ::::::::::::::::::::::::::: %
% :: INTERNAL ENVIRONMENTS :: %
+% ::::::::::::::::::::::::::: %
%%%
% prototype::
@@ -556,7 +652,9 @@
\ExplSyntaxOn
+% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
+% ::::::::::::::::::::::: %
\tl_new:N \l_tdoc_showcase_before_tl
\tl_new:N \l_tdoc_showcase_after_tl
@@ -585,7 +683,9 @@
}
+% :::::::::::::::::::::::::::::: %
% :: SHOWCASE FROM TYPED CODE :: %
+% :::::::::::::::::::::::::::::: %
% prototype::
% #1 : the key-value options.
@@ -625,7 +725,9 @@
}
+% :::::::::::::::::::::::: %
% :: SHOWCASE FROM FILE :: %
+% :::::::::::::::::::::::: %
%%%
% prototype::
@@ -647,9 +749,13 @@
\ExplSyntaxOff
+% -------------------- %
% -- LATEX EXAMPLES -- %
+% -------------------- %
+% ::::::::::::::::::::::::::::: %
% :: INLINE SHORT LATEX CODE :: %
+% ::::::::::::::::::::::::::::: %
%%%
% See the \doc of the macro ''\newmintinline'' from the package ''minted''
@@ -658,7 +764,9 @@
\newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4}
+% ::::::::::::::::::::::::::::::::::::::::::::::: %
% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: %
+% ::::::::::::::::::::::::::::::::::::::::::::::: %
\ExplSyntaxOn
@@ -684,7 +792,9 @@
\ExplSyntaxOff
+% ::::::::::::::::::::::::::::::::: %
% :: THE TCOLORBOX LISTING STYLE :: %
+% ::::::::::::::::::::::::::::::::: %
%%%
% note::
@@ -696,6 +806,7 @@
tdoclatex_tcbstyle/.style = {
minted language = latex,
breakable,
+ enhanced,
% Code and output
colback = yellow!5,
% Frame
@@ -707,7 +818,6 @@
% We can use ''sharp corners'' to obtain an "old school" style.
%
% Separating line
- enhanced,
segmentation style = {
gray,
dash pattern = {on 5pt off 2.5pt},
@@ -718,7 +828,9 @@
}
+% ::::::::::::::::::::::::::::::::::: %
% :: TCOLORBOX LISTING ENVIRONMENT :: %
+% ::::::::::::::::::::::::::::::::::: %
%%%
% prototype::
@@ -736,7 +848,9 @@
}
+% :::::::::::::::::::::::::::::::::::::: %
% :: TCOLORBOX IMPORTED LISTING MACRO :: %
+% :::::::::::::::::::::::::::::::::::::: %
%%%
% prototype::
@@ -753,11 +867,15 @@
}
+% -------------------------- %
% -- LATEX REAL USE CASES -- %
+% -------------------------- %
\ExplSyntaxOn
+% ::::::::::::::::::::::: %
% :: SETTING SOME KEYS :: %
+% ::::::::::::::::::::::: %
\tl_new:N \l_tdoc_listing_explain_tl
@@ -773,7 +891,9 @@
}
+% ::::::::::::::::::::: %
% :: LATEXSHOW MACRO :: %
+% ::::::::::::::::::::: %
%%%
% prototype::
@@ -805,7 +925,9 @@
\ExplSyntaxOn
+% :::::::::::::: %
% :: MESSAGES :: %
+% :::::::::::::: %
\msg_set:nnnn { tdoc } { date-bad-format }
{ Bad ~ format ~ for ~ a ~ date. }
@@ -812,7 +934,9 @@
{ Use ~ YYYY-MM-DD. }
+% ::::::::::::::::: %
% :: MARGIN NOTE :: %
+% ::::::::::::::::: %
\reversemarginpar{}
@@ -890,8 +1014,12 @@
{#3}
}
+\ExplSyntaxOff
+
+% :::::::::::::::::::::: %
% :: VERSION AND DATE :: %
+% :::::::::::::::::::::: %
%%%
% prototype::
@@ -916,7 +1044,9 @@
}
+% :::::::::: %
% :: DATE :: %
+% :::::::::: %
%%%
% prototype::
@@ -928,15 +1058,21 @@
%%%
\NewDocumentCommand{\tdocdate}{O{blue} m}{
\tutodoc at new@change at margin{#1} % Color
- {#2} % Date
- {} % Version
- {-5.35pt} % Last negative spacing
+ {#2} % Date
+ {} % Version
+ {-5.35pt} % Last negative spacing
}
+% --------------------- %
% -- CHANGES - WHAT? -- %
+% --------------------- %
+\ExplSyntaxOn
+
+% :::::::::::::: %
% :: MESSAGES :: %
+% :::::::::::::: %
\msg_set:nnnn { tdoc } { changes-topic-missing-title }
{ Missing ~ title. }
@@ -943,7 +1079,9 @@
{ One ~ single ~ title ~ must ~ be ~ indicated. }
+% ::::::::::::::::::::: %
% :: CHANGES - TOPIC :: %
+% ::::::::::::::::::::: %
%%%
% prototype::
@@ -952,12 +1090,13 @@
% :action: this environment prints some ¨infos about specific changes
% achieved in a new version (no special formatting is applied).
%%%
-\NewDocumentEnvironment{tdoctopic}{ m }{
+\NewDocumentEnvironment{tdoctopic}{ m O{} }{
\IfBlankT{#1}{
\msg_fatal:nn { tdoc } { changes-topic-missing-title }
}
\textbf{
+ \IfBlankF{#2}{#2\kern3.5pt}%
\textsc{#1.}
}
@@ -967,89 +1106,40 @@
}
+% :::::::::::::::::::::::::: %
% :: CHANGES - NEW THINGS :: %
+% :::::::::::::::::::::::::: %
-%%%
-% prototype::
-% :see: env.tdoctopic
-%
-% :action: similar to the \env ''tdoctopic'' with the title "New"
-% translated into the good language.
-%%%
-\NewDocumentEnvironment{tdocnew}{}{
- \begin{tdoctopic}{\tutodoc at trans@chges at new}
-}{
- \end{tdoctopic}
+\prop_set_from_keyval:Nn \__g_tutodoc_topic_change_prop {
+ break = \faCodeBranch,
+ fix = \faWrench,
+ new = \faGem,
+ prob = \faFire*,
+ update = \faMagic,
}
-% :: CHANGES - UPDATE :: %
-
%%%
% prototype::
% :see: env.tdoctopic
%
-% :action: similar to the \env ''tdoctopic'' with the title "Update"
+% :action: similar to the \env ''tdoctopic'' with the title "New"
% translated into the good language.
%%%
-\NewDocumentEnvironment{tdocupdate}{}{
- \begin{tdoctopic}{\tutodoc at trans@chges at update}
-}{
- \end{tdoctopic}
+\prop_map_inline:Nn \__g_tutodoc_topic_change_prop {
+ \NewDocumentEnvironment{ tdoc#1 } {} {
+ \begin{tdoctopic}{ \use:c { tutodoc at trans@chges@#1 } } [ #2 ]
+ }{
+ \end{tdoctopic}
+ }
}
-
-% :: CHANGES - BREAK :: %
-
-%%%
-% prototype::
-% :see: env.tdoctopic
-%
-% :action: similar to the \env ''tdoctopic'' with the title "Break"
-% translated into the good language.
-%%%
-\NewDocumentEnvironment{tdocbreak}{}{
- \begin{tdoctopic}{\tutodoc at trans@chges at break}
-}{
- \end{tdoctopic}
-}
-
-
-% :: CHANGES - PROBLEM :: %
-
-%%%
-% prototype::
-% :see: env.tdoctopic
-%
-% :action: similar to the \env ''tdoctopic'' with the title "Problem"
-% translated into the good language.
-%%%
-\NewDocumentEnvironment{tdocprob}{}{
- \begin{tdoctopic}{\tutodoc at trans@chges at pb}
-}{
- \end{tdoctopic}
-}
-
-
-% :: CHANGES - FIX :: %
-
-%%%
-% prototype::
-% :see: env.tdoctopic
-%
-% :action: similar to the \env ''tdoctopic'' with the title "Fix"
-% translated into the good language.
-%%%
-\NewDocumentEnvironment{tdocfix}{}{
- \begin{tdoctopic}{\tutodoc at trans@chges at fix}
-}{
- \end{tdoctopic}
-}
-
\ExplSyntaxOff
+% ----------------- %
% -- DECORATIONS -- %
+% ----------------- %
% Source for \addvspace{\medskipamount} instead of \medskip.
% * https://tex.stackexchange.com/a/705938/6880
More information about the tex-live-commits
mailing list.