texlive[72596] Master/texmf-dist: tutodoc (19oct24)
commits+karl at tug.org
commits+karl at tug.org
Sat Oct 19 22:26:08 CEST 2024
Revision: 72596
https://tug.org/svn/texlive?view=revision&revision=72596
Author: karl
Date: 2024-10-19 22:26:08 +0200 (Sat, 19 Oct 2024)
Log Message:
-----------
tutodoc (19oct24)
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
Added Paths:
-----------
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-en.cfg.cls.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-fr.cfg.cls.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls
Removed Paths:
-------------
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-10-19 20:25:40 UTC (rev 72595)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2024-10-19 20:26:08 UTC (rev 72596)
@@ -102,7 +102,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-exa-leavevmode.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-exa-leavevmode.tex}
\begin{tdocexa}
\leavevmode
\begin{enumerate}
@@ -114,7 +114,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-important.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-important.tex}
\begin{tdocimp}
Important and harmless.
\end{tdocimp}
@@ -125,7 +125,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-note.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-note.tex}
\begin{tdocnote}
Something useful to tell you...
\end{tdocnote}
@@ -136,7 +136,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-caution.tex}
\begin{tdoccaut}
Caution, caution...
\end{tdoccaut}
@@ -147,7 +147,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-tip.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-tip.tex}
\begin{tdoctip}
A tip.
\end{tdoctip}
@@ -158,7 +158,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-warn.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-warn.tex}
\begin{tdocwarn}
Avoid the dangers...
\end{tdocwarn}
@@ -169,7 +169,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-exa.tex}
\begin{tdocexa}
An example...
\end{tdocexa}
@@ -180,7 +180,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-rmk.tex}
\begin{tdocrem}
Just one remark...
\end{tdocrem}
@@ -284,30 +284,32 @@
% == SOURCE FOR THE DOC == %
% ======================== %
-\documentclass[10pt, a4paper]{article}
+\documentclass[10pt, a4paper]{tutodoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
-
\usepackage[english]{babel, varioref}
-
-
-
-
\usepackage{enumitem}
\usepackage{fmtcount}
\usepackage{multicol}
+\usepackage{wrapfig2}
+
\setlength{\parindent}{0em}
-\newcommand\thispack{\tdocpack{tutodoc}}
-% Package documented.
-\usepackage[lang = english]{tutodoc}
+\newcommand\thisproj{\tdoccls{tutodoc}}
+\newcommand\thisrepo{\url{https://github.com/bc-tools/for-latex/tree/tutodoc}}
+\newcommand\thismonorepo{\url{https://github.com/bc-tools/for-latex}}
+\NewDocumentCommand{\trademark}{m}{\texttt{#1}}
+\newcommand\ctan{\href{https://ctan.org/}{\trademark{CTAN}}}
+\newcommand\git{\trademark{git}}
+
+
% --------------- %
% -- IMPORTANT -- %
% --------------- %
@@ -371,37 +373,131 @@
}
+\NewDocumentCommand{\mailsubject}{m}% <-- Translate me!
+ {subject \tdocquote{\texttt{tutodoc - CONTRIB - #1}}}
+
+% Source: https://tex.stackexchange.com/a/424061/6880
+
+\newcommand{\FTdirO}{}
+\def\FTdirO(#1,#2,#3){%
+ \FTfile(#1,{\color{blue!40!black}\faFolderOpen\hspace{-.35pt}}{\hspace{0.2em}#3})
+ (tmp.west)++(0.8em,-0.4em)node(#2){}
+ (tmp.west)++(1.5em,0)
+ ++(0,-1.3em)
+}
+
+\newcommand{\FTdirC}{}
+\def\FTdirC(#1,#2,#3){%
+ \FTfile(#1,{\color{blue!40!black}\faFolder\hspace{.75pt}}{\hspace{0.2em}#3})
+ (tmp.west)++(0.8em,-0.4em)node(#2){}
+ (tmp.west)++(1.5em,0)
+ ++(0,-1.3em)
+}
+
+\newcommand{\FTfile}{}
+\def\FTfile(#1,#2){%
+ node(tmp){}
+ (#1|-tmp)++(0.6em,0)
+ node(tmp)[anchor=west,black]{\tt #2}
+ (#1)|-(tmp.west)
+ ++(0,-1.2em)
+}
+
+\newcommand{\FTroot}{}
+\def\FTroot{tmp.west}
+
+\newcommand\contribtranslatedirtree{
+ \begin{tikzpicture}%
+ \draw[color=black, thick]
+% en : parent = \FTroot
+% normal dir: (parentID, currentID, label)
+% file : (parentID, label)
+ \FTdirO(\FTroot,root,translate){
+ \FTdirC(root,changes,changes){
+ }
+ \FTdirO(root,en,en) {
+ \FTdirC(en,api,api) {
+ }
+ \FTdirC(en,doc,doc) {
+ }
+ }
+ \FTdirC(root,fr,fr){
+ }
+ \FTdirC(root,status,status){
+ \FTdirO(status,en,en) {
+ \FTfile(en,api.yaml)
+ \FTfile(en,manual.yaml)
+ }
+ \FTdirC(status,fr,fr){
+ }
+ }
+ \FTfile(root,README.md)
+ \FTfile(root,LICENSE.txt)
+ };
+ \end{tikzpicture}
+}
+
+
\begin{document}
-\title{The \texttt{tutodoc} package - Tutorial-style documentation}
+\title{The \texttt{tutodoc} class - Tutorial-style documentation}
\author{Christophe BAL}
-\date{Sep 28, 2024 - Version 1.4.0}
+\date{Oct 19, 2024 - Version 1.5.0}
\maketitle
\begin{abstract}
- The \thispack{} package\,%
+ The \thisproj{} class\,%
\footnote{
The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
}
- is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style,%
+ 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.
+ using a sober rendering for reading on screen.
- \medskip
+ \smallskip
- 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}
+ \noindent
+ \emph{\textbf{Remark :} this documentation is also available in French.}
\end{abstract}
+\medskip
+\begin{center}
+\small
+\begin{minipage}{.9\textwidth}
+\begin{tdocnote}[Last changes]
+\small
+
+\begin{tdocbreak}
+ \item The \thisproj\ class replaces the now-defunct \thisproj\ package (for the moment, the young class offers no specific options).
+
+ \item The \tdocmacro{tdocruler} macro is now used via \tdocinlatex{\tdocruler[<color>]{<text>}} (remember that the old syntax was \tdocinlatex{\tdocruler{<text>}{<color>}}).
+\end{tdocbreak}
+
+
+\begin{tdocfix}
+ \item Version 3 of \tdocpack{minted} is taken into account.
+
+ \item The \tdocmacro{tdocdate} macro did not handle date format and formatting.
+
+ \item Colored frames did not color text after a page break.
+\end{tdocfix}
+
+
+\begin{tdocnew}
+ \item The class is usable in Spanish.
+
+ \item The documentation contains a new section explaining how to contribute.
+\end{tdocnew}
+\end{tdocnote}
+\end{minipage}
+\end{center}
+
+
\newpage
\tableofcontents
\newpage
@@ -483,30 +579,49 @@
\begin{tdoclatex}[code]
+\newcommand{\tdoclinkcolor}{NavyBlue!85!white}
+
\hypersetup{
colorlinks,
- citecolor = orange!75!black,
- filecolor = orange!75!black,
- linkcolor = orange!75!black,
- urlcolor = orange!75!black
+ citecolor = \tdoclinkcolor,
+ filecolor = \tdoclinkcolor,
+ linkcolor = \tdoclinkcolor,
+ urlcolor = \tdoclinkcolor
}
\end{tdoclatex}
-\section{Select language when loading package}
+\section{What language is used by the \thisproj\ class?}
-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.
+This documentation loads the \tdocpack{babel} package via \tdocinlatex|\usepackage[english]{babel}|\,.
+As a result, the \thisproj\ class identifies \tdocinlatex|en| as the main language used by \tdocpack{babel}.%.
+\footnote{
+ Technically, we use \tdocinlatex|\BCPdata{language}| which returns a language in short format.
+}
+As this language is included in the list of languages taken into account, see below, the \thisproj\ class will produce the expected effects.
-\begin{enumerate}
- \item \tdocinlatex|english| is the default value.
+\begin{multicols}{3}
+ \begin{itemize}
+ \item \tdocinlatex|en| : English.
+ \item \tdocinlatex|es| : Spanish.
+ \item \tdocinlatex|fr| : French.
+ \end{itemize}
+\end{multicols}
+
- \item \tdocinlatex|french|
-\end{enumerate}
+\begin{tdoccaut}
+ If the choice of main language is not made in the preamble, the mechanism used will fail with unintended side effects (see warning that follows).
+\end{tdoccaut}
+
+\begin{tdocwarn}
+ When a language is not supported by \thisproj, a warning message is issued, and English is selected as the language for \thisproj.
+\end{tdocwarn}
+
+
\begin{tdocnote}
- Language names are those suggested by the \tdocpack{babel} package.
+ The mechanism used should be compatible with the \tdocpack{polyglossia} package.
\end{tdocnote}
@@ -524,7 +639,7 @@
\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.
+ As the text \tdocquote{in English} is translated into the language detected by \thisproj, the macro \tdocmacro{tdocinEN} and its starred version become useful for non-English speakers.
\end{tdocnote}
@@ -536,7 +651,7 @@
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.
+ This short text will always be translated into the language detected by the \thisproj\ class.
\end{tdocnote}
@@ -559,7 +674,7 @@
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}
+\tdoclatexinput[sbs]{examples-admonitions-exa.tex}
@@ -578,7 +693,7 @@
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}
+\tdoclatexinput[sbs]{examples-admonitions-exa-leavevmode.tex}
@@ -588,19 +703,19 @@
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}
+\tdoclatexinput[sbs]{examples-admonitions-rmk.tex}
-\subsection{Flashy content} \label{tdoc-colorful-focus}
+\subsection{Flashy content} \label{tdoc-admonitions}
\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}|
+ \tdocinlatex|\fbox{\tdocicon{\faBed}{Tired}}|
produces\,
- \tdocicon{\faBed}{Tired}.
+ \fbox{\tdocicon{\faBed}{Tired}}\,.
}
\end{tdocnote}
@@ -609,7 +724,7 @@
The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it.
-\tdoclatexinput[sbs]{examples-focus-tip.tex}
+\tdoclatexinput[sbs]{examples-admonitions-tip.tex}
@@ -621,46 +736,32 @@
\end{tdocnote}
-%\subsection{Flashy content}
+\foreach \sectitle/\desc/\filename in {
+ {Informative note}/%<-- Translate me!
+ {The \tdocenv*{tdocnote} environment is used to highlight useful information. Here's how to use it.}/%<-- Translate me!
+ note,
+ %
+ {Something important}/%<-- Translate me!
+ {The \tdocenv*{tdocimp} environment is used to indicate something important but harmless.}/%<-- Translate me!
+ important,
+ %
+ {Caution about a delicate point}/%<-- Translate me!
+ {The \tdocenv*{tdoccaut} environment is used to indicate a delicate point to the user. Here's how to use it.}/% <-- Translate me!
+ caution,
+ %
+ {Warning of danger}/%<-- Translate me!
+ {The \tdocenv*{tdocwarn} environment is used to warn the user of a trap to avoid. Here's how to use it.}/%<-- Translate me!
+ warn%
+} {
+ \subsubsection{\sectitle}
-\subsubsection{Informative note}
+ \desc
-The \tdocenv*{tdocnote} environment is used to highlight useful information. Here's how to use it.
+ \tdoclatexinput[sbs]{examples-admonitions-\filename.tex}
-\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.
@@ -716,7 +817,7 @@
-\subsection{With a coloured stripe} \label{tdoc-color-macros}
+\subsection{With a colored stripe} \label{tdoc-color-macros}
\begin{tdocexa} [With default text]
It can be useful to show a real rendering directly in a document.
@@ -746,7 +847,7 @@
\begin{tdocnote}
- The explanatory texts adapt to the language chosen when \thispack{} is loaded.
+ The explanatory texts adapt to the language detected by \thisproj.
\end{tdocnote}
@@ -794,7 +895,7 @@
You also have to know that behind the scene, the \tdocmacro{tdocruler} macro is used.
\begin{tdoclatex}[std]
- \tdocruler{A decorated pseudo-title}{red}
+ \tdocruler[red]{A decorated pseudo-title}
\end{tdoclatex}
\end{tdocnote}
@@ -888,12 +989,12 @@
}
-\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.
+%\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}
-\end{tdoccaut}
-
\subsection{\tdocquote{Inline} codes} \label{tdoc-listing-inline}
The \tdocmacro{tdocinlatex} macro
@@ -900,14 +1001,14 @@
\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}.
+can be used to type inline code in a similar way to \tdocmacro{verb} or like a standard macro (see brace management in the last case below).
Here are some examples.
\begin{tdoclatex}[sbs]
- 1: \tdocinlatex|$a^b = c$|
-
- 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+
+ 1: \tdocinlatex|$a^b = c$| \\
+ 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+ \\
+ 3: \tdocinlatex{\tdocinlatex{$a^b = c$}}
\end{tdoclatex}
@@ -1059,7 +1160,7 @@
\begin{tdocnote}
- The default texts take into account the language chosen when loading the package \thispack{}.
+ The default texts take into account the language detected by \thisproj.
\end{tdocnote}
@@ -1105,7 +1206,7 @@
\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.
+To make it easier to monitor a project, it is essential to provide a history indicating the changes made when a new version is published.
@@ -1140,16 +1241,16 @@
\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}.
+ \item The final rendering of the dates takes into account the language detected by \thisproj{}: 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.
+ 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}
@@ -1156,7 +1257,7 @@
\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.%
+\thisproj\ 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.
}
@@ -1163,130 +1264,241 @@
\begin{tdocnote}
- For icons, see the note at the beginning of the section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
+ For icons, see the note at the beginning of the section \ref{tdoc-admonitions} page \pageref{tdoc-admonitions}.
\end{tdocnote}
-% ------------------ %
+\foreach \exatitle/\filename in {
+ {Just for the very first version}/%<-- Translate me!
+ first,
+ {For new features}/% <-- Translate me!
+ new,
+ {For updates}/% <-- Translate me!
+ update,
+ {For breaks}/% <-- Translate me!
+ break,
+ {For problems}/% <-- Translate me!
+ pb,
+ {For fixes}/% <-- Translate me!
+ fix,
+ {Selectable themes with an icon}/% <-- Translate me!
+ user-choice-icon,
+ {Selectable themes without icons}/%<-- Translate me!
+ user-choice%
+} {
+ \begin{tdocexa}[\exatitle]
+ \leavevmode
+ \tdoclatexinput[sbs]{examples-version-n-change-\filename.tex}
-\begin{tdocexa}[Just for the very first version]
- \leavevmode
+ \end{tdocexa}
+}
- \tdoclatexinput[sbs]{examples-version-n-change-first.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...
-\begin{tdocexa}[For new features]
- \leavevmode
+\tdocsep % Practical for demarcation.
- \tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+This works with enumerations.
-\end{tdocexa}
+\begin{itemize}
+ \item Underline.
+\end{itemize}
+\tdocsep % Uniform behaviour.
-% ------------------ %
+Ble, ble, ble...
+\end{tdoclatex}
-\begin{tdocexa}[For updates]
- \leavevmode
+\section{Contribute}
- \tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+\begin{tdocnote}
+ \textbf{You don't need to be a coder to take part in translations}, including those that are useful for the running of \thisproj.
+\end{tdocnote}
-\end{tdocexa}
+%\section{Contribute}
-% ------------------ %
+\subsection{Complete the translations}
+\begin{tdocnote}
+ The author of \thisproj\ manages the French and English versions of the translations.
+\end{tdocnote}
-\begin{tdocexa}[For breaks]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-break.tex}
+\begin{tdoccaut}
+ Although we're going to explain how to translate the documentation, it doesn't seem relevant to do so, as English should suffice these days.%
+ \footnote{
+ The existence of a French version is simply a consequence of the native language of the author of \thisproj.
+ }
+\end{tdoccaut}
-\end{tdocexa}
+\begin{wrapfigure}{R}
+ \contribtranslatedirtree\
+ \caption{Simplified view of the translation folder}
+ \label{tdoc-contrib-translate-dir}
+\end{wrapfigure}{}
-% ------------------ %
+The translations are roughly organized as in figure \ref{tdoc-contrib-translate-dir} where only the folders important for the translations have been \tdocquote{opened}\,.%}.
+\footnote{
+ This was the organization on October 5, 2024, but it's still relevant today.
+}
+\textbf{A little further down, the \ref{tdoc-contrib-translate} section explains how to add new translations}.
-\begin{tdocexa}[For problems]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-pb.tex}
+\subsubsection{The \texttt{fr} and \texttt{en} folders}
-\end{tdocexa}
+These two folders, managed by the author of \thisproj, have the same organization; they contain files that are easy to translate even if you're not a coder.
-% ------------------ %
+\subsubsection{The \texttt{changes} folder}
+This folder is a communication tool where important changes are indicated without dwelling on minor modifications specific to one or more translations.
-\begin{tdocexa}[For fixes]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
+\subsubsection{The \texttt{status} folder}
-\end{tdocexa}
+This folder is used to keep track of translations from the project's point of view. Everything is done via well-commented \verb#YAML# files, readable by a non-coder.
-% ------------------ %
+\subsubsection{The \texttt{README.md} and \texttt{LICENSE.txt} files}
+The \texttt{LICENSE.txt} file is aptly named, while the \texttt{README.md} file takes up in English the important points of what is said in this section about new translations.
-\begin{tdocexa}[Selectable themes with an icon]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-user-choice-icon.tex}
+\subsubsection{New translations}
+\label{tdoc-contrib-translate}
-\end{tdocexa}
+\begin{tdocimp}
+ The \verb#api# folder contains translations relating to the functionalities of \thisproj.
+ Here you'll find \verb#TXT# files for editing with a text or code editor, but not with a word processor.
+ The content of these files uses commented lines in English to explain what \thisproj\ will do; these lines begin with \verb#//#\,. Here's an extract from such a file, where translations are made after each \,$=$\ sign, without touching the preceding, as this initial piece is used internally by the \thisproj code.
+ \tdocsep
+ \vspace{-10pt}
+ \begin{verbatim}
+ // #1: year in format YYYY like 2023.
+ // #2: month in format MM like 04.
+ // #3: day in format DD like 29.
+ date = #1-#2-#3
-% ------------------ %
+ // #1: the idea is to produce one text like
+ // "this word means #1 in english".
+ in_EN = #1 in english\end{verbatim}
+\end{tdocimp}
-\begin{tdocexa}[Selectable themes without icons]
- \leavevmode
+\begin{tdocnote}
+ The \verb#doc# folder is reserved for documentation. It contains files of type \verb#TEX# that can be compiled directly for real-time validation of translations.
+\end{tdocnote}
- \tdoclatexinput[sbs]{examples-version-n-change-user-choice.tex}
-\end{tdocexa}
+\begin{tdocwarn}
+ Only start from one of the \verb#fr# and \verb#en# folders, as these are the responsibility of the \thisproj\ author.
+\end{tdocwarn}
-\section{Ornaments}
+\medskip
-Let's finish this documentation with a small formatting tool that is very useful.
+\emph{\textbf{Let's say you want to add support for Italian from files written in English.}}%
+\footnote{
+ As mentioned above, there is no real need for the \texttt{doc} documentation folder.
+}
-\begin{tdoclatex}[sbs]
-Bla, bla, bla...
-\tdocsep % Practical for demarcation.
+\paragraph{Method 1 : \git.}
-This works with enumerations.
+\begin{enumerate}
+ \item Obtain the entire project folder via \thisrepo\,.
+ Do not use the \verb#main# branch, which is used to freeze the latest stable versions of projects in the single \thismonorepo\ repository,.
-\begin{itemize}
- \item Underline.
-\end{itemize}
+ \item In the \verb#tutodoc/contrib/translate# folder, create a \verb#it# copy of the \verb#en# folder, with the short name of the language documented in
+ \href{https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags}%
+ {the page \tdocquote{IIETF language tag}}
+ from \texttt{Wikipedia}.
-\tdocsep % Uniform behaviour.
+ \item Once the translation is complete in the \verb#it# folder, you'll need to communicate it via \thisrepo\ using a classic \verb#git push#\,.
+\end{enumerate}
-Ble, ble, ble...
-\end{tdoclatex}
+\paragraph{Method 2 : communicate by e-mail.}
+\begin{enumerate}
+ \item By e-mail with the \mailsubject{en FOR italian}, request a version of the English translations (note the use of the English name for the new language).
+ Be sure to respect the subject of the e-mail, as the author of \thisproj\ automates the pre-processing of this type of e-mail.
+
+ \item You will receive a folder named \verb#italian# containing the English version of the latest translations.
+ This folder will be the place for your contribution.
+
+ \item Once the translation is complete, you will need to compress your \verb#italian# file in \verb#zip# or \verb#rar# format before sending it by e-mail with the \mailsubject{italian}\,.
+\end{enumerate}
+
+
+%\section{Contribute}
+
+\subsection{Improving the source code}
+
+\begin{tdocimp}
+ If you want to participate in \thisproj\, you'll need to use the \LaTeX3 programming paradigm.
+\end{tdocimp}
+
+
+Participation as a coder is made via the \thisrepo\ repository corresponding to the \verb#tutodoc# development branch.
+Do not use the \verb#main# branch, which is used to freeze the latest stable versions of projects in the single \thismonorepo\ repository.
+
+
\section{History}
\small
+\tdocversion{1.5.0}[2024-10-19]
+
+\small
+
+\begin{tdocbreak}
+ \item The \thisproj\ class replaces the now-defunct \thisproj\ package (for the moment, the young class offers no specific options).
+
+ \item The \tdocmacro{tdocruler} macro is now used via \tdocinlatex{\tdocruler[<color>]{<text>}} (remember that the old syntax was \tdocinlatex{\tdocruler{<text>}{<color>}}).
+\end{tdocbreak}
+
+
+\begin{tdocfix}
+ \item Version 3 of \tdocpack{minted} is taken into account.
+
+ \item The \tdocmacro{tdocdate} macro did not handle date format and formatting.
+
+ \item Colored frames did not color text after a page break.
+\end{tdocfix}
+
+
+\begin{tdocnew}
+ \item The class is usable in Spanish.
+
+ \item The documentation contains a new section explaining how to contribute.
+\end{tdocnew}
+
+\tdocsep
+
+
+% ------------------ %
+
+
\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 Content highlighting: examples and remarks, indicated via the \tdocenv*{tdocexa} and \tdocenv*{tdocrem} environments, are always numbered using a common counter.
\item The unused macro \tdocmacro{tdocxspace} has been deleted.
\end{tdocbreak}
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-10-19 20:25:40 UTC (rev 72595)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2024-10-19 20:26:08 UTC (rev 72596)
@@ -102,7 +102,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-exa-leavevmode.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-exa-leavevmode.tex}
\begin{tdocexa}
\leavevmode
\begin{enumerate}
@@ -114,7 +114,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-important.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-important.tex}
\begin{tdocimp}
Un truc important sans danger.
\end{tdocimp}
@@ -125,7 +125,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-note.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-note.tex}
\begin{tdocnote}
Un truc utile à vous dire...
\end{tdocnote}
@@ -136,7 +136,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-caution.tex}
\begin{tdoccaut}
Prudence, prudence...
\end{tdoccaut}
@@ -147,7 +147,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-tip.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-tip.tex}
\begin{tdoctip}
Une astuce.
\end{tdoctip}
@@ -158,7 +158,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-warn.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-warn.tex}
\begin{tdocwarn}
Evitez les dangers...
\end{tdocwarn}
@@ -169,7 +169,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-exa.tex}
\begin{tdocexa}
Un exemple...
\end{tdocexa}
@@ -180,7 +180,7 @@
\end{filecontents*}
-\begin{filecontents*}[overwrite]{examples-focus-rmk.tex}
+\begin{filecontents*}[overwrite]{examples-admonitions-rmk.tex}
\begin{tdocrem}
Juste une remarque...
\end{tdocrem}
@@ -280,24 +280,31 @@
% == SOURCE FOR THE DOC == %
% ======================== %
-\documentclass[10pt, a4paper]{article}
+\documentclass[10pt, a4paper]{tutodoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
+\usepackage{enumitem}
+
+% \usepackage[german]{babel}
\usepackage[french]{babel, varioref}
-
-\usepackage{enumitem}
\frenchsetup{StandardItemLabels=true}
\usepackage{multicol}
+\usepackage{wrapfig2}
-\newcommand\thispack{\tdocpack{tutodoc}}
-% Package documented.
-\usepackage[lang = french]{tutodoc}
+\newcommand\thisproj{\tdoccls{tutodoc}}
+\newcommand\thisrepo{\url{https://github.com/bc-tools/for-latex/tree/tutodoc}}
+\newcommand\thismonorepo{\url{https://github.com/bc-tools/for-latex}}
+\NewDocumentCommand{\trademark}{m}{\texttt{#1}}
+\newcommand\ctan{\href{https://ctan.org/}{\trademark{CTAN}}}
+\newcommand\git{\trademark{git}}
+
+
% Source.
% * https://tex.stackexchange.com/a/604698/6880
@@ -341,36 +348,97 @@
}
+\NewDocumentCommand{\mailsubject}{m}% <-- Translate me!
+ {sujet \tdocquote{\texttt{tutodoc - CONTRIB - #1}}}
+
+% Source: https://tex.stackexchange.com/a/424061/6880
+
+\newcommand{\FTdirO}{}
+\def\FTdirO(#1,#2,#3){%
+ \FTfile(#1,{\color{blue!40!black}\faFolderOpen\hspace{-.35pt}}{\hspace{0.2em}#3})
+ (tmp.west)++(0.8em,-0.4em)node(#2){}
+ (tmp.west)++(1.5em,0)
+ ++(0,-1.3em)
+}
+
+\newcommand{\FTdirC}{}
+\def\FTdirC(#1,#2,#3){%
+ \FTfile(#1,{\color{blue!40!black}\faFolder\hspace{.75pt}}{\hspace{0.2em}#3})
+ (tmp.west)++(0.8em,-0.4em)node(#2){}
+ (tmp.west)++(1.5em,0)
+ ++(0,-1.3em)
+}
+
+\newcommand{\FTfile}{}
+\def\FTfile(#1,#2){%
+ node(tmp){}
+ (#1|-tmp)++(0.6em,0)
+ node(tmp)[anchor=west,black]{\tt #2}
+ (#1)|-(tmp.west)
+ ++(0,-1.2em)
+}
+
+\newcommand{\FTroot}{}
+\def\FTroot{tmp.west}
+
+\newcommand\contribtranslatedirtree{
+ \begin{tikzpicture}%
+ \draw[color=black, thick]
+% en : parent = \FTroot
+% normal dir: (parentID, currentID, label)
+% file : (parentID, label)
+ \FTdirO(\FTroot,root,translate){
+ \FTdirC(root,changes,changes){
+ }
+ \FTdirO(root,en,en) {
+ \FTdirC(en,api,api) {
+ }
+ \FTdirC(en,doc,doc) {
+ }
+ }
+ \FTdirC(root,fr,fr){
+ }
+ \FTdirC(root,status,status){
+ \FTdirO(status,en,en) {
+ \FTfile(en,api.yaml)
+ \FTfile(en,manual.yaml)
+ }
+ \FTdirC(status,fr,fr){
+ }
+ }
+ \FTfile(root,README.md)
+ \FTfile(root,LICENSE.txt)
+ };
+ \end{tikzpicture}
+}
+
+
\begin{document}
-\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
+\title{La classe \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe BAL}
-\date{28 sept. 2024 - Version 1.4.0}
+\date{19 oct. 2024 - Version 1.5.0}
\maketitle
+
\begin{abstract}
- Le package \thispack{}\,%
+ La classe \thisproj{}\,%
\footnote{
Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} qui se traduit en \tdocquote{documentation de type tutoriel}.
}
- est utilisé par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel,%
+ est utilisée par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel\,%
\footnote{
L'idée est de produire un fichier \texttt{PDF} efficace à parcourir pour des besoins ponctuels. C'est généralement ce que l'on attend d'une documentation liée au codage.
}
- et avec un rendu sobre pour une lecture sur écran.
+ via un rendu sobre pour une lecture sur écran.
- \medskip
+ \smallskip
- \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.
+ \noindent
+ \emph{\textbf{Remarque :} cette documentation est aussi disponible en anglais.}
- \item Cette documentation est aussi disponible en anglais.
- \end{itemize}
-
\tdocsep
{\small\itshape
@@ -379,28 +447,55 @@
\textbf{Abstract.}
\end{center}
- The \thispack{} package\,%
+ The \thisproj{} class\,%
\footnote{
The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
}
- is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style,%
+ 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.
+ using a sober rendering for reading on screen.
- \medskip
+ \smallskip
- 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}
+ \noindent
+ \emph{\textbf{Remark :} this documentation is also available in French.}
}
\end{abstract}
+\medskip
+\begin{center}
+\small
+\begin{minipage}{.9\textwidth}
+\begin{tdocnote}[Derniers changements]
+\begin{tdocbreak}
+ \item La classe \thisproj\ remplace le défunt package \thisproj\ (pour le moment, la toute jeune classe ne propose aucune option spécifique).
+
+ \item La macro \tdocmacro{tdocruler} s'emploie dorénavant via \tdocinlatex{\tdocruler[<color>]{<text>}} (avant il fallait utiliser \tdocinlatex{\tdocruler{<text>}{<color>}}).
+\end{tdocbreak}
+
+
+\begin{tdocfix}
+ \item La version 3 de \tdocpack{minted} est prise en compte.
+
+ \item La macro \tdocmacro{tdocdate} ne gérait pas le format et la mise en forme de la date.
+
+ \item Les cadres colorés ne coloraient pas le texte après un saut de page.
+\end{tdocfix}
+
+
+\begin{tdocnew}
+ \item La classe est utilisable en langue espagnole.
+
+ \item La documentation contient une nouvelle section expliquant comment contribuer.
+\end{tdocnew}
+\end{tdocnote}
+\end{minipage}
+\end{center}
+
+
\newpage
\tableofcontents
\newpage
@@ -482,30 +577,49 @@
\begin{tdoclatex}[code]
+\newcommand{\tdoclinkcolor}{NavyBlue!85!white}
+
\hypersetup{
colorlinks,
- citecolor = orange!75!black,
- filecolor = orange!75!black,
- linkcolor = orange!75!black,
- urlcolor = orange!75!black
+ citecolor = \tdoclinkcolor,
+ filecolor = \tdoclinkcolor,
+ linkcolor = \tdoclinkcolor,
+ urlcolor = \tdoclinkcolor
}
\end{tdoclatex}
-\section{Choisir la langue au chargement du package}
+\section{Quelle langue est utilisée par la classe \thisproj\ ?}
-La présente documentation utilise le français via \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
-Pour le moment, on a juste les deux choix suivants.
+Cette documentation charge le package \tdocpack{babel} via \tdocinlatex|\usepackage[french]{babel}|\,.
+Dès lors, la classe \thisproj\ repère \tdocinlatex|fr| comme langue principale utilisée par \tdocpack{babel}.%
+\footnote{
+ Techniquement, on utilise \tdocinlatex|\BCPdata{language}| qui renvoie une langue au format court.
+}
+Comme cette langue fait partie de la liste des langues prises en compte, voir ci-dessous, la classe \thisproj\ produira les effets attendus.
-\begin{enumerate}
- \item \tdocinlatex|english| est la valeur par défaut.
+\begin{multicols}{3}
+ \begin{itemize}
+ \item \tdocinlatex|en| : anglais.
+ \item \tdocinlatex|es| : espagnol.
+ \item \tdocinlatex|fr| : français.
+ \end{itemize}
+\end{multicols}
+
- \item \tdocinlatex|french| est pour \tdocinEN{français}.
-\end{enumerate}
+\begin{tdoccaut}
+ Si le choix de la langue principale n'est pas faite dans le préambule, le mécanisme employé échouera avec des effets de bord non voulus (voir l'avertissement qui suit).
+\end{tdoccaut}
+
+\begin{tdocwarn}
+ Lorsqu'une langue n'est pas prise en compte par \thisproj, un message d'avertissement est émis, et l'anglais est alors choisi comme langue vis-à-vis de \thisproj.
+\end{tdocwarn}
+
+
\begin{tdocnote}
- Les noms des langues sont ceux proposés par le package \tdocpack{babel}.
+ Le mécanisme utilisé devrait être compatible avec le package \tdocpack{polyglossia}.
\end{tdocnote}
@@ -523,7 +637,7 @@
\begin{tdocnote}
- Le texte \tdocquote{en anglais} est traduit dans la langue indiquée lors de l'importation de \thispack{}.
+ Le texte \tdocquote{en anglais} est traduit dans la langue détectée par \thisproj.
\end{tdocnote}
@@ -535,7 +649,7 @@
La mise en forme provient du package \tdocpack{keytheorems}.
}
ajoutent un court titre indiquant le type d'informations fournies.
- Ce court texte sera toujours traduit dans la langue indiquée lors du chargement du package \thispack{}.
+ Ce court texte sera toujours traduit dans la langue repérée par la classe \thisproj.
\end{tdocnote}
@@ -542,43 +656,31 @@
\subsection{Du contenu dans le flot de la lecture}
-
-% ------------------ %
-
-
\begin{tdocimp}
Tous les environnements présentés dans cette section partagent le même compteur.
\end{tdocimp}
-% ------------------ %
-
\subsubsection{Des exemples}
Des exemples numérotés, si besoin, s'indiquent via \tdocenv{tdocexa} qui propose un argument optionnel pour ajouter un mini-titre.
Voici deux usages possibles.
-\tdoclatexinput[sbs]{examples-focus-exa.tex}
+\tdoclatexinput[sbs]{examples-admonitions-exa.tex}
-% ------------------ %
-
-
\begin{tdocimp}
La numérotation des exemples est remise à zéro dès qu'une section de niveau au moins égale à une \tdocinlatex|\section| est ouverte.
\end{tdocimp}
-% ------------------ %
-
-
\begin{tdoctip}
Il peut parfois être utile de revenir à la ligne dès le début du contenu. Le code suivant montre comment faire (ce tour de passe-passe reste valable pour l'environnement \verb#tdocrem# présenté juste après). Noter au passage que la numérotation suit celle de l'exemple précédent comme souhaité.
\end{tdoctip}
-\tdoclatexinput[sbs]{examples-focus-exa-leavevmode.tex}
+\tdoclatexinput[sbs]{examples-admonitions-exa-leavevmode.tex}
@@ -588,33 +690,36 @@
Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'environnement \tdocenv*{tdocexa} comme le montre l'exemple suivant.
-\tdoclatexinput[sbs]{examples-focus-rmk.tex}
+\tdoclatexinput[sbs]{examples-admonitions-rmk.tex}
-\subsection{Du contenu tape-à-l'oeil} \label{tdoc-colorful-focus}
+\subsection{Du contenu tape-à-l'oeil} \label{tdoc-admonitions}
+
\begin{tdocnote}
Les icônes sont obtenues via le package \tdocpack{fontawesome5}, et la gestion de l'espacement avec le texte est faite par la macro \tdocmacro{tdocicon}.
\footnote{
Par exemple,
- \tdocinlatex|\tdocicon{\faBed}{Fatigué}|
+ \tdocinlatex|\fbox{\tdocicon{\faBed}{Fatigué}}|
produit\,
- \tdocicon{\faBed}{Fatigué}.
+ \fbox{\tdocicon{\faBed}{Fatigué}}\,.
}
\end{tdocnote}
+
\subsubsection{Une astuce}
L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'employer.
-\tdoclatexinput[sbs]{examples-focus-tip.tex}
+\tdoclatexinput[sbs]{examples-admonitions-tip.tex}
\smallskip
+
\begin{tdocnote}
Les couleurs sont obtenues via les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor}.
Pour des informations complémentaires à ce sujet, se reporter à la fin de la section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}.
@@ -621,46 +726,32 @@
\end{tdocnote}
-%\subsection{Du contenu tape-à-l'oeil}
+\foreach \sectitle/\desc/\filename in {
+ {Note informative}/% <-- Translate me!
+ {L'environnement \tdocenv*{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.}/% <-- Translate me!
+ note,
+ %
+ {Un truc important}/% <-- Translate me!
+ {L'environnement \tdocenv*{tdocimp} permet d'indiquer quelque chose d'important mais sans danger.}/% <-- Translate me!
+ important,
+ %
+ {Avertir d'un point très délicat}/% <-- Translate me!
+ {L'environnement \tdocenv*{tdoccaut} sert à indiquer un point délicat à l'utilisateur. Voici comment l'employer.}/%<-- Translate me!
+ caution,
+ %
+ {Avertir d'un danger}/% <-- Translate me!
+ {L'environnement \tdocenv*{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.}/% <-- Translate me!
+ warn%
+} {
+ \subsubsection{\sectitle}
-\subsubsection{Note informative}
+ \desc
-L'environnement \tdocenv*{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.
+ \tdoclatexinput[sbs]{examples-admonitions-\filename.tex}
-\tdoclatexinput[sbs]{examples-focus-note.tex}
+}
-
-%\subsection{Du contenu tape-à-l'oeil}
-
-\subsubsection{Un truc important}
-
-L'environnement \tdocenv*{tdocimp} permet d'indiquer quelque chose d'important mais sans danger.
-
-\tdoclatexinput[sbs]{examples-focus-important.tex}
-
-
-
-%\subsection{Du contenu tape-à-l'oeil}
-
-\subsubsection{Avertir d'un point très délicat}
-
-L'environnement \tdocenv*{tdoccaut} sert à indiquer un point délicat à l'utilisateur. Voici comment l'employer.
-
-\tdoclatexinput[sbs]{examples-focus-caution.tex}
-
-
-
-%\subsection{Du contenu tape-à-l'oeil}
-
-\subsubsection{Avertir d'un danger}
-
-L'environnement \tdocenv*{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.
-
-\tdoclatexinput[sbs]{examples-focus-warn.tex}
-
-
-
\section{Indiquer des packages, des classes, des macros ou des environnements}
Voici ce qu'il est possible de taper de façon sémantique.
@@ -746,13 +837,10 @@
\begin{tdocnote}
- Les textes explicatifs s'adaptent à la langue choisie lors du chargement de \thispack{}.
+ Les textes explicatifs s'adaptent à la langue détectée par \thisproj.
\end{tdocnote}
-% ------------------ %
-
-
\begin{tdocexa}[Changer la couleur et/ou les textes par défaut]
\leavevmode
@@ -795,14 +883,11 @@
Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est utilisée.
\begin{tdoclatex}[std]
- \tdocruler{Un pseudo-titre décoré}{red}
+ \tdocruler[red]{Un pseudo-titre décoré}
\end{tdoclatex}
\end{tdocnote}
-% ------------------ %
-
-
\begin{tdocwarn}
Avec les réglages par défaut, si le code \LaTeX\ à mettre en forme commence par un crochet ouvrant, il faudra user de \tdocmacro{string} comme dans l'exemple suivant.
@@ -838,9 +923,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[Changer la couleur et/ou les textes par défaut]
\leavevmode
@@ -888,11 +970,12 @@
}
-\begin{tdoccaut}
- La version 3 de \tdocpack{minted} ne peut pas être prise en compte pour le moment car elle comporte des bugs : voir \url{https://github.com/gpoore/minted/issues/401}. On force donc l'usage de la version 2 de \tdocpack{minted}.
-\end{tdoccaut}
+%\begin{tdoccaut}
+% La version 3 de \tdocpack{minted} ne peut pas être prise en compte pour le moment car elle comporte des bugs : voir \url{https://github.com/gpoore/minted/issues/401}. On force donc l'usage de la version 2 de \tdocpack{minted}.
+%\end{tdoccaut}
+
\subsection{Codes \tdocquote{en ligne}} \label{tdoc-listing-inline}
La macro \tdocmacro{tdocinlatex}
@@ -899,14 +982,14 @@
\footnote{
Le nom de la macro \tdocmacro{tdocinlatex} vient de \tdocquote{\tdocprewhy{in.line} \LaTeX} soit \tdocinEN{\LaTeX\ en ligne}.
}
-permet de taper du code en ligne via un usage similaire à \tdocmacro{verb}.
+permet de taper du code en ligne via un usage similaire à \tdocmacro{verb} ou bien comme une macro standard (voir la gestion des accolades dans le dernier cas ci-dessous).
Voici des exemples d'utilisation.
\begin{tdoclatex}[sbs]
- 1: \tdocinlatex|$a^b = c$|
-
- 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+
+ 1: \tdocinlatex|$a^b = c$| \\
+ 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+ \\
+ 3: \tdocinlatex{\tdocinlatex{$a^b = c$}}
\end{tdoclatex}
@@ -930,9 +1013,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[À la suite]
\tdocenv{tdoclatex} produit le résultat suivant qui correspond à l'option par défaut \tdocinlatex#std#\,.
\footnote{
@@ -945,9 +1025,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[Juste le code]
Via \tdocenv[{[code]}]{tdoclatex}, on aura juste le code comme ci-après.
@@ -957,9 +1034,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocwarn}
Avec la mise en forme par défaut, si le code commence par un crochet ouvrant, il faudra indiquer explicitement l'option par défaut.
\tdocdocbasicinput{examples-listing-strange.tex}
@@ -977,17 +1051,17 @@
Pour les codes suivants, on considère un fichier de chemin relatif \verb+examples-listing-xyz.tex+, et ayant le contenu suivant.
+
\tdoclatexinput[code]{examples-listing-xyz.tex}
+
\medskip
+
La macro \tdocmacro{tdoclatexinput}, présentée ci-dessous, attend le chemin d'un fichier et propose les mêmes options que l'environnement \tdocenv*{tdoclatex}.
-% ------------------ %
-
-
\begin{tdocexa}[Face à face]
\leavevmode
@@ -1003,9 +1077,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[À la suite]
\leavevmode
@@ -1021,9 +1092,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[Juste le code]
\leavevmode
@@ -1055,13 +1123,10 @@
\begin{tdocnote}
- Les textes par défaut tiennent compte de la langue choisie lors du chargement du package \thispack{}.
+ Les textes par défaut tiennent compte de la langue détectée par \thisproj.
\end{tdocnote}
-% ------------------ %
-
-
\begin{tdocexa}[Changer le texte explicatif]
Via la clé \tdocinlatex|explain|, on peut utiliser un texte personnalisé. Ainsi, \tdocinlatex|\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}| produira ce qui suit.
@@ -1074,9 +1139,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[Les options disponibles]
En plus du texte explicatif, il est aussi possible d'utiliser toutes les options de l'environnement \tdocenv*{tdocshowcase}, voir \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
Voici un exemple illustrant ceci.
@@ -1101,7 +1163,7 @@
\section{Indiquer les changements}
-Afin de faciliter le suivi d'un package, il est indispensable de fournir un historique indiquant les changements effectués lors de la publication d'une nouvelle version.
+Afin de faciliter le suivi d'un projet, il est indispensable de fournir un historique indiquant les changements effectués lors de la publication d'une nouvelle version.
@@ -1110,9 +1172,6 @@
On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas le numéro de version pourra éventuellement être daté.
-% ------------------ %
-
-
\begin{tdocexa}[Dater des nouveautés]
La macro \tdocmacro{tdocdate} permet d'indiquer une date dans la marge comme dans l'exemple suivant.
@@ -1121,9 +1180,6 @@
\end{tdocexa}
-% ------------------ %
-
-
\begin{tdocexa}[Versionner des nouveautés en les datant événtuellement]
Associer un numéro de version à une nouveauté se fait via la macro \tdocmacro{tdocversion}, la couleur et la date étant des arguments optionnels.
@@ -1136,7 +1192,7 @@
\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}.
+ \item Comme la langue détectée pour cette documentation est le français, la date dans le rendu final est au format \texttt{JJ/MM/AAAA} alors que dans le code celle-ci devra toujours être saisie au format anglais \texttt{AAAA-MM-JJ}.
\end{enumerate}
\end{tdocimp}
@@ -1155,7 +1211,7 @@
\subsection{Quoi de neuf ?}
-\thispack{} propose la macro \tdocmacro{tdocstartproj} et différents environnements pour indiquer rapidement et clairement ce qui a été fait lors des derniers changements.%
+\thisproj\ propose la macro \tdocmacro{tdocstartproj} et différents environnements pour indiquer rapidement et clairement ce qui a été fait lors des derniers changements.%
\footnote{
L'utilisateur n'a pas besoin de tous les détails techniques.
}
@@ -1162,130 +1218,242 @@
\begin{tdocnote}
- Concernant les icônes, voir la note au début de la section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
+ Concernant les icônes, voir la note au début de la section \ref{tdoc-admonitions} page \pageref{tdoc-admonitions}.
\end{tdocnote}
-% ------------------ %
+\foreach \exatitle/\filename in {
+ {Juste pour la toute première version}/%<-- Translate me!
+ first,
+ {Pour les nouveautés}/% <-- Translate me!
+ new,
+ {Pour les mises à jour}/% <-- Translate me!
+ update,
+ {Pour les bifurcations}/% <-- Translate me!
+ break,
+ {Pour les problèmes}/% <-- Translate me!
+ pb,
+ {Pour les réparations}/% <-- Translate me!
+ fix,
+ {Thématiques aux choix avec une icône}/%<-- Translate me!
+ user-choice-icon,
+ {Thématiques aux choix sans icône}/% <-- Translate me!
+ user-choice%
+} {
+ \begin{tdocexa}[\exatitle]
+ \leavevmode
+ \tdoclatexinput[sbs]{examples-version-n-change-\filename.tex}
-\begin{tdocexa}[Juste pour la toute première version]
- \leavevmode
+ \end{tdocexa}
+}
- \tdoclatexinput[sbs]{examples-version-n-change-first.tex}
-\end{tdocexa}
+\section{Décorations}
+Finissons cette documentation avec un petit outil de mise en forme qui rend de grands services.
-% ------------------ %
+\begin{tdoclatex}[sbs]
+Bla, bla, bla...
-\begin{tdocexa}[Pour les nouveautés]
- \leavevmode
+\tdocsep % Pratique pour délimiter.
- \tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+Ceci fonctionne avec des énumérations.
-\end{tdocexa}
+\begin{itemize}
+ \item Point souligné.
+\end{itemize}
+\tdocsep % Un comportement uniforme.
-% ------------------ %
+Ble, ble, ble...
+\end{tdoclatex}
-\begin{tdocexa}[Pour les mises à jour]
- \leavevmode
+\section{Contribuer}
- \tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+\begin{tdocnote}
+ \textbf{Nul besoin d'être un codeur pour participer aux traductions}, y compris pour celles utiles au fonctionnement de \thisproj.
+\end{tdocnote}
-\end{tdocexa}
+%\section{Contribuer}
-% ------------------ %
+\subsection{Compléter les traductions}
+\begin{tdocnote}
+ L'auteur de \thisproj\ gère les versions françaises et anglaises des traductions.
+\end{tdocnote}
-\begin{tdocexa}[Pour les bifurcations]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-break.tex}
+\begin{tdoccaut}
+ Même si nous allons expliquer comment traduire les documentations, il semble peu pertinent de le faire, car l'anglais devrait suffire de nos jours.%
+ \footnote{
+ L'existence d'une version française est une simple conséquence de la langue maternelle de l'auteur de \thisproj.
+ }
+\end{tdoccaut}
-\end{tdocexa}
+\begin{wrapfigure}{R}
+ \contribtranslatedirtree\
+ \caption{Vue simplifiée du dossier des traductions}
+ \label{tdoc-contrib-translate-dir}
+\end{wrapfigure}{}
-% ------------------ %
+Les traductions sont organisées grosso-modo comme dans la figure \ref{tdoc-contrib-translate-dir} où seuls les dossiers importants pour les traductions ont été \tdocquote{ouverts}\,.%
+\footnote{
+ Cette organisation était celle du 5 octobre 2024, mais elle reste d'actualité.
+}
+\textbf{Un peu plus bas, la section \ref{tdoc-contrib-translate} donne les démarches à suivre pour ajouter de nouvelles traductions.}
-\begin{tdocexa}[Pour les problèmes]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-pb.tex}
+\subsubsection{Les dossiers \texttt{fr} et \texttt{en}}
-\end{tdocexa}
+Ces deux dossiers, gérés par l'auteur de \thisproj, ont la même organisation ; ils contiennent des fichiers faciles à traduire même si l'on n'est pas un codeur.
-% ------------------ %
+\subsubsection{Le dossier \texttt{changes}}
+Ce dossier est un outil de communication où sont indiqués les changements importants sans s'attarder sur les modifications mineures propres à une ou plusieurs traductions.
-\begin{tdocexa}[Pour les réparations]
- \leavevmode
- \tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
-\end{tdocexa}
+\subsubsection{Le dossier \texttt{status}}
+Ce dossier permet de savoir où en sont les traductions du point de vue du projet. Tout se passe via des fichiers \verb#YAML# bien commentés, et lisibles par un non codeur.
-% ------------------ %
-\begin{tdocexa}[Thématiques aux choix avec une icône]
- \leavevmode
+\subsubsection{Les fichiers \texttt{README.md} et \texttt{LICENSE.txt}}
- \tdoclatexinput[sbs]{examples-version-n-change-user-choice-icon.tex}
+Le fichier \texttt{LICENSE.txt} est bien nommé, tandis que le fichier \texttt{README.md} reprend en anglais les points importants de ce qui est dit dans cette section sur les nouvelles traductions.
-\end{tdocexa}
-% ------------------ %
+\subsubsection{De nouvelles traductions}
+\label{tdoc-contrib-translate}
+\begin{tdocimp}
+ Le dossier \verb#api# contient les traductions relatives aux fonctionnalités de \thisproj.
+ Vous y trouverez des fichiers de type \verb#TXT# à modifier via un éditeur de texte, ou de code, mais non via un traitement de texte.
+ Les contenus de ces fichiers utilisent des lignes commentées en anglais pour expliquer ce que fera \thisproj\ ; ces lignes commencent par \verb#//#\,. Voici un extrait de ce type de fichier où \textbf{les traductions se font après chaque signe \,$=$\, sans toucher à ce qui se trouve avant}, car ce morceau initial est utilisé en interne par le code de \thisproj..
-\begin{tdocexa}[Thématiques aux choix sans icône]
- \leavevmode
+ \tdocsep
+ \vspace{-10pt}
+ \begin{verbatim}
+ // #1: year in format YYYY like 2023.
+ // #2: month in format MM like 04.
+ // #3: day in format DD like 29.
+ date = #1-#2-#3
- \tdoclatexinput[sbs]{examples-version-n-change-user-choice.tex}
+ // #1: the idea is to produce one text like
+ // "this word means #1 in english".
+ in_EN = #1 in english\end{verbatim}
+\end{tdocimp}
-\end{tdocexa}
+\begin{tdocnote}
+ Le dossier \verb#doc# est réservé aux documentations. Il contient des fichiers de type \verb#TEX# compilables directement pour une validation en temps réel des traductions faites.
+\end{tdocnote}
-\section{Décorations}
-Finissons cette documentation avec un petit outil de mise en forme qui rend de grands services.
+\begin{tdocwarn}
+ Ne partir que de l'un des dossiers \verb#fr# et \verb#en#, car ceux-ci sont de la responsabilité de l'auteur de \thisproj.
+\end{tdocwarn}
-\begin{tdoclatex}[sbs]
-Bla, bla, bla...
+\medskip
-\tdocsep % Pratique pour délimiter.
-Ceci fonctionne avec des énumérations.
+\emph{\textbf{Imaginons que vous souhaitiez ajouter le support de l'italien en partant de fichiers rédigés en anglais.}}%
+\footnote{
+ Comme indiqué plus haut, il n'y a pas de besoin réel du côté du dossier \texttt{doc} de la documentation.
+}
-\begin{itemize}
- \item Point souligné.
-\end{itemize}
-\tdocsep % Un comportement uniforme.
+\paragraph{Méthode 1 : \git.}
-Ble, ble, ble...
-\end{tdoclatex}
+\begin{enumerate}
+ \item Obtenir tout le dossier du projet via \thisrepo\,.
+ Ne pas passer via la branche \verb#main# qui sert à figer les dernières versions stables des projets du dépôt unique \thismonorepo\,.
+
+ \item Dans le dossier \verb#tutodoc/contrib/translate#, créer une copie \verb#it# du dossier \verb#en#\,, le nom court de la langue étant documenté dans
+ \href{https://en.wikipedia.org/wiki/IETF_language_tag#List_of_common_primary_language_subtags}%
+ {la page \tdocquote{IIETF language tag}}
+ de \texttt{Wikipédia}.
+
+ \item Une fois la traduction achevée dans le dossier \verb#it# , il faudra la communiquer via \thisrepo\ en usant d'un classique \verb#git push#\,.
+\end{enumerate}
+\paragraph{Méthode 2 : communiquer par courriels.}
+
+\begin{enumerate}
+ \item Via un courriel de \mailsubject{en FOR italian}\,, demander une version des traductions anglaises (noter l'emploi du nom anglais de la nouvelle langue).
+ Bien respecter le sujet du courriel, car l'auteur de \thisproj\ automatise le pré-traitement de ce type de courriels.
+
+ \item Vous recevrez un dossier nommé \verb#italian# contenant la version anglaise des dernières traductions.
+ Ce dossier sera le lieu de votre contribution.
+
+ \item Une fois la traduction achevée, il faudra compresser votre dossier \verb#italian# au format \verb#zip# ou \verb#rar# avant de l'envoyer par courriel avec le \mailsubject{italian}\,.
+\end{enumerate}
+
+
+%\section{Contribuer}
+
+\subsection{Améliorer le code source}
+
+\begin{tdocimp}
+ Si vous souhaitez participer à \thisproj\,, il faudra privilégier le paradigme de programmation \LaTeX3.
+\end{tdocimp}
+
+
+La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrepo\ correspondant à la branche de développement \verb#tutodoc#.
+Ne pas passer via la branche \verb#main# qui sert à figer les dernières versions stables des projets du dépôt unique \thismonorepo\,.
+
+
\section{Historique}
\small
+\tdocversion{1.5.0}[2024-10-19]
+
+\begin{tdocbreak}
+ \item La classe \thisproj\ remplace le défunt package \thisproj\ (pour le moment, la toute jeune classe ne propose aucune option spécifique).
+
+ \item La macro \tdocmacro{tdocruler} s'emploie dorénavant via \tdocinlatex{\tdocruler[<color>]{<text>}} (avant il fallait utiliser \tdocinlatex{\tdocruler{<text>}{<color>}}).
+\end{tdocbreak}
+
+
+\begin{tdocfix}
+ \item La version 3 de \tdocpack{minted} est prise en compte.
+
+ \item La macro \tdocmacro{tdocdate} ne gérait pas le format et la mise en forme de la date.
+
+ \item Les cadres colorés ne coloraient pas le texte après un saut de page.
+\end{tdocfix}
+
+
+\begin{tdocnew}
+ \item La classe est utilisable en langue espagnole.
+
+ \item La documentation contient une nouvelle section expliquant comment contribuer.
+\end{tdocnew}
+
+\tdocsep
+
+
+% ------------------ %
+
+
\tdocversion{1.4.0}[2024-09-28]
\begin{tdocbreak}
\item L'environnement \tdocenv*{tdoccaution} a été renommé \tdocenv*{tdoccaut} pour une saisie simplifiée.
- \item Mise en avant de contenus : les exemples et remarques, indiqués via les environnements \tdocenv*{tdocexa} et \tdocenv*{tdocrem}, sont toujours numérotés, et ils partagent le même compteur.
+ \item Mise en avant de contenus : les exemples et remarques, indiqués via les environnements \tdocenv*{tdocexa} et \tdocenv*{tdocrem}, sont toujours numérotés via un compteur commun.
\item La macro inutilisée \tdocmacro{tdocxspace} a été supprimée.
\end{tdocbreak}
@@ -1308,7 +1476,7 @@
\item Mise en avant de contenus : réduction de l'espace autour du contenu dans les cadres colorés.
- \item Gestion des versions: un meilleur espacement verticalement via \tdocmacro{vphantom}.
+ \item Gestion des versions: un meilleur espacement vertical via \tdocmacro{vphantom}.
\end{tdocupdate}
\tdocsep
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-en.cfg.cls.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-en.cfg.cls.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-en.cfg.cls.sty 2024-10-19 20:26:08 UTC (rev 72596)
@@ -0,0 +1,17 @@
+\NewDocumentCommand{\tutodoc at trans@date}{mmm}{#1-#2-#3}
+\NewDocumentCommand{\tutodoc at trans@in at EN}{m}{#1 in english}
+\NewDocumentCommand{\tutodoc at trans@this at gives}{m}{This gives #1}
+\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@rem at title}{}{Remark}
+\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
+\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Tip}
+\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
+\NewDocumentCommand{\tutodoc at trans@caut at title}{}{Caution}
+\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Warning}
+\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}
+\NewDocumentCommand{\tutodoc at trans@chges at update}{}{Update}
\ No newline at end of file
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-en.cfg.cls.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: 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-10-19 20:25:40 UTC (rev 72595)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty 2024-10-19 20:26:08 UTC (rev 72596)
@@ -1,17 +0,0 @@
-\NewDocumentCommand{\tutodoc at trans@date}{mmm}{#1-#2-#3}
-\NewDocumentCommand{\tutodoc at trans@in at EN}{m}{#1 ~ in ~ english}
-\NewDocumentCommand{\tutodoc at trans@this at gives}{m}{This ~ gives ~ #1}
-\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@rem at title}{}{Remark}
-\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
-\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Tip}
-\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
-\NewDocumentCommand{\tutodoc at trans@caut at title}{}{Caution}
-\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Warning}
-\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}
-\NewDocumentCommand{\tutodoc at trans@chges at update}{}{Update}
\ No newline at end of file
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-fr.cfg.cls.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-fr.cfg.cls.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-fr.cfg.cls.sty 2024-10-19 20:26:08 UTC (rev 72596)
@@ -0,0 +1,17 @@
+\NewDocumentCommand{\tutodoc at trans@date}{mmm}{#3/#2/#1}
+\NewDocumentCommand{\tutodoc at trans@in at EN}{m}{#1 en anglais}
+\NewDocumentCommand{\tutodoc at trans@this at gives}{m}{Ceci donne #1}
+\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@rem at title}{}{Remarque}
+\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
+\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Astuce}
+\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
+\NewDocumentCommand{\tutodoc at trans@caut at title}{}{Mise en garde}
+\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Avertissement}
+\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}
+\NewDocumentCommand{\tutodoc at trans@chges at update}{}{Mise à jour}
\ No newline at end of file
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-fr.cfg.cls.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: 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-10-19 20:25:40 UTC (rev 72595)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty 2024-10-19 20:26:08 UTC (rev 72596)
@@ -1,17 +0,0 @@
-\NewDocumentCommand{\tutodoc at trans@date}{mmm}{#3/#2/#1}
-\NewDocumentCommand{\tutodoc at trans@in at EN}{m}{#1 ~ en ~ anglais}
-\NewDocumentCommand{\tutodoc at trans@this at gives}{m}{Ceci ~ donne ~ #1}
-\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@rem at title}{}{Remarque}
-\NewDocumentCommand{\tutodoc at trans@note at title}{}{Note}
-\NewDocumentCommand{\tutodoc at trans@tip at title}{}{Astuce}
-\NewDocumentCommand{\tutodoc at trans@imp at title}{}{Important}
-\NewDocumentCommand{\tutodoc at trans@caut at title}{}{Mise ~ en ~ garde}
-\NewDocumentCommand{\tutodoc at trans@warn at title}{}{Avertissement}
-\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}
-\NewDocumentCommand{\tutodoc at trans@chges at update}{}{Mise ~ à ~ jour}
\ No newline at end of file
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls 2024-10-19 20:26:08 UTC (rev 72596)
@@ -0,0 +1,1144 @@
+% ********************************************************* %
+% ** This is file `tutodoc.cls' 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. ** %
+% ********************************************************* %
+
+\ProvidesExplClass
+ {tutodoc}
+ {2024-10-19} % Creation: 2023-11-29
+ {1.5.0}
+ {This LaTeX class proposes tools for writing "human friendly" PDF documentations of LaTeX packages and classes.}
+
+
+% == PACKAGES USED == %
+
+\LoadClassWithOptions{article}%
+ [2022-06-01]
+
+\RequirePackage[svgnames]%
+ {xcolor}%
+ [2023/11/15]
+
+\RequirePackage[
+ top = 2.5cm,
+ bottom = 2.5cm,
+ left = 2.5cm,
+ right = 2.5cm,
+ marginparwidth = 2cm,
+ marginparsep = 2mm,
+ heightrounded
+]{geometry}%
+ [2020-01-02]
+
+\RequirePackage[raggedright]%
+ {titlesec}%
+ [2021/07/05]
+
+\RequirePackage{tocbasic}
+
+\RequirePackage{xcolor}%
+ [2022/06/12]
+
+\RequirePackage{hyperref}%
+ [2023-02-07]
+
+
+% We delegate the management of quoting to the ''csquotes'' package,
+% which takes care of the locale settings.
+\RequirePackage{csquotes}%
+ [2022-09-14]
+
+
+\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{minted2}% Old implementation.
+
+\RequirePackage[highlightmode = immediate]%
+ {minted}%
+ [2024/09/22]
+
+\RequirePackage{tcolorbox}%
+ [2024/07/10]
+
+\tcbuselibrary{minted,
+ breakable,
+ skins}
+
+
+\RequirePackage{fontawesome5}%
+ [2022-05-02]
+
+\RequirePackage{marginnote}%
+ [2023-09-07]
+
+
+% == MAIN CODE == %
+
+% -- LOCALE SETTINGS -- %
+
+\ExplSyntaxOn
+
+\msg_set:nnnn { tutodoc ~ (main) }
+ { main : unsupported-lang }
+ { unsupported ~ language ~ << ~ #1 ~ >>. }
+ { \msg_see_documentation_text:n { tutodoc } }
+
+
+\newcommand{\tutodoc at colon}{:}
+
+\AtBeginDocument{
+% We must take care of colons and spacing.
+ \@ifpackageloaded{babel}{
+ \iflanguage{french}{
+ \renewcommand{\tutodoc at colon}{\babelshorthand{:}}
+ }{}
+ }{}
+
+ \newcommand{\tdoclang}{\BCPdata{language}}
+
+% If the lang is not supported, we emit a warning and just turn
+% to the english language.
+ \makeatletter
+ \InputIfFileExists{tutodoc-locale-main-\tdoclang.cfg.cls.sty}{}{
+ \input{tutodoc-locale-main-en.cfg.cls.sty}
+
+ \msg_critical:nnx { tutodoc ~ (main) }
+ { main : unsupported-lang }
+ { \tdoclang }
+ }
+ \makeatother
+}
+
+\ExplSyntaxOff
+
+
+% -- GENERAL SETTINGS -- %
+
+\setlength{\parindent}{0cm}
+
+
+% -- LINKS -- %
+
+\newcommand{\tdoclinkcolor}{NavyBlue!85!white}
+
+\hypersetup{
+ colorlinks,
+ citecolor = \tdoclinkcolor,
+ filecolor = \tdoclinkcolor,
+ linkcolor = \tdoclinkcolor,
+ urlcolor = \tdoclinkcolor
+}
+
+
+% -- TOC & Co. -- %
+
+\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}
+
+
+% -- COLOR TRANSFORMATIONS -- %
+
+%%%
+% prototype::
+% #1 : (black-rate)
+% the amount of color relative to black.
+% #2 : (color)
+% one color following the ''xcolor'' format.
+%
+% :return: a "darker" version of the color ''#1''.
+%%%
+\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}
+
+
+%%%
+% prototype::
+% #1 : (transparency)
+% the transparency rate.
+% #2 : (color)
+% one color following the ''xcolor'' format.
+%
+% :return: a "transparent" version of the color `#1`.
+%%%
+\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
+
+
+% -- ICONS -- %
+
+%%%
+% prototype::
+% #1 : (aws-icon)
+% one material that expects to be an icon command from the
+% ''fontawsome5'' \pack.
+%
+% :return: the icon followed by a small insecable space.
+%%%
+\NewDocumentCommand{\tdocicon}{m}{%
+ #1\kern.45em%
+}
+
+
+% -- QUOTING -- %
+
+%%%
+% prototype::
+% #1 : (text)
+% a text to quote.
+%
+% For example, ''\tdocquote{Something}'' prints **"Something"**.
+%%%
+\NewDocumentCommand{\tdocquote}{m}{%
+ \enquote{\emph{#1}}%
+}
+
+
+% -- EXPLAINING ENGLISH NAMES -- %
+
+%%%
+% prototype::
+% #1 : (text-en)
+% an english text that will be explained in another \lang.
+%
+% :extra: this macro has a star version.
+%
+% For example, if the language chosen is ''french'', we have
+% the following outputs.
+%
+% 1) ''\tdocinEN{Something}'' prints
+% **"Something" en anglais**.
+%
+% 2) ''\tdocinEN*{Something}'' just prints
+% **"Something"**.
+%
+% 3) ''\tdocinEN*{Something} et \tdocinEN{Another thing}''
+% gives
+% **"Something" et "Another thing" en anglais**.
+%%%
+\NewDocumentCommand{\tdocinEN}{s m}{%
+ \tdocquote{#2}%
+ \IfBooleanF{#1}{% No star used.
+ \tutodoc at trans@in at EN{}%
+ }%
+}
+
+
+% -- SOBER HIGHLIGHTING OF CONTENT -- %
+
+% :: EXAMPLE - REMARK :: %
+
+\ExplSyntaxOn
+
+%%%
+% We use a ''seq'' variable to factorize the code just after.
+%%%
+\seq_new:N \__g_tutodoc_focus_std_seq
+\seq_set_from_clist:Nn \__g_tutodoc_focus_std_seq {
+ exa,
+ rem
+}
+
+
+%%%
+% prototype::
+% :action: looping over ''\__g_tutodoc_focus_std_seq'' to build new
+% numbered theorems sharing the same section level counter.
+% To achieve that, we use the ''\newkeytheorem'' macro from
+% the ''keytheorems'' \pack.
+%%%
+\seq_map_inline:Nn \__g_tutodoc_focus_std_seq {
+ \str_if_eq:nnTF { #1 } { exa } {
+ \newkeytheorem{tdoc#1}[
+ name = \use:c { tutodoc at trans@#1 at title },
+ within = section,
+ ]
+ } {
+ \newkeytheorem{tdoc#1}[
+ name = \use:c { tutodoc at trans@#1 at title },
+ numberlike = tdocexa,
+ ]
+ }
+
+ \cs_set:cpn { the tdoc #1 } { \thesection\arabic{tdoc#1} }
+}
+
+\ExplSyntaxOff
+
+
+% -- COLORFUL HIGHLIGHTING OF CONTENT -- %
+
+% :: ABSTRACTION :: %
+
+%%%
+% note::
+% The settings used come from the following sources.
+% * https://tex.stackexchange.com/a/727022/6880
+% * https://tex.stackexchange.com/a/682332/6880
+% * https://tex.stackexchange.com/a/623232/6880
+%%%
+\tcbset{
+ tutodoc-focus-color-style/.style = {
+ use color stack, % Must be before breakable!
+ breakable,
+ enhanced,
+ left = 3pt,
+ right = 3pt,
+ 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},
+ }
+}
+
+
+% :: LET'S GO BACK TO THE REAL WORLD :: %
+
+\ExplSyntaxOn
+
+%%%
+% We use two ''prop'' variables to factorize the code just after.
+%%%
+\prop_set_from_keyval:Nn \__g_tutodoc_focus_color_prop {
+ note = cyan,
+ tip = ForestGreen,
+ imp = orange,
+ caut = violet,
+ warn = red,
+}
+
+\prop_set_from_keyval:Nn \__g_tutodoc_focus_icon_prop {
+ note = \faInfoCircle,
+ tip = \faLightbulb,
+ imp = \faHighlighter,
+ caut = \faBiohazard,
+ warn = \faSkullCrossbones,
+}
+
+
+%%%
+% prototype::
+% :action: ''key/value'' iteration over ''\__g_tutodoc_focus_color_prop''
+% to build new colorful unumbered theorems. To achieve that,
+% we use a ''tcolorbox'' style given to the ''\newkeytheorem''
+% macro from the ''keytheorems'' \pack, and icons from the
+% ''fontawesome5'' \pack.
+%%%
+\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 = {
+ \tdocicon{ \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } }
+ \use:c { tutodoc at trans@#1 at title }
+ },
+ ]
+}
+
+\ExplSyntaxOff
+
+
+% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- %
+
+%%%
+% prototype::
+% #1 : (cls-name)
+% the name of a class
+%
+% :action: ''\tdoccls{myclass}'' prints verb::''myclass''.
+%%%
+\NewDocumentCommand{\tdoccls}{m}{%
+ \texttt{#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : (pck-name)
+% the name of a package
+%
+% :action:''\tdocpack{mypack}'' prints verb::''mypack''.
+%%%
+\NewDocumentCommand{\tdocpack}{m}{%
+ \texttt{#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : (cmd-name)
+% the name of a macro
+%
+% :action: ''\tdocmacro{mymacro}'' prints verb::''\mymacro''.
+%%%
+\NewDocumentCommand{\tdocmacro}{m}{%
+ \texttt{\textbackslash{}#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : (env-options)
+% hard typed options with the good delimiters
+% #2 : (env-name)
+% the name of an environment
+%
+% :extra: this macro has a star version.
+%
+% Here are the four kind of outputs.
+%
+% 1) ''\tdocenv{myenv}'' prints
+% verb::''\begin{myenv} ... \end{myenv}''.
+%
+% 2) ''\tdocenv[{<opt1>[mando2]}]{myenv}'' prints
+% verb::''\begin{myenv}<opt1>[mando2] ... \end{myenv}''.
+%
+% 3) ''\tdocenv*{myenv}'' prints
+% verb::''myenv''.
+%
+% 4) ''\tdocenv*[{<opt1>[mando2]}]{myenv}'' prints
+% verb::''myenv''.
+%%%
+%
+% Cleaner code from https://tex.stackexchange.com/a/703379/6880 .
+\NewDocumentCommand{\tdocenv}{s O{} m}{%
+ \IfBooleanTF{#1}{%
+ \texttt{#3}%
+ }{%
+ \texttt{\string\begin\string{#3\string}#2 %
+ \!\!...\@\!\!\! %
+ \string\end\string{#3\string}}%
+ }%
+}
+
+
+% -- EXPLAINING PREFIXES -- %
+
+\ExplSyntaxOn
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { tutodoc ~ (macroenv) }
+ { macroenv : prefix-why-bad-format }
+ { Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
+ { You ~ must ~ use ~ one ~ single ~ point. }
+
+
+% :: PREFIX FROM... :: %
+
+%%%
+% prototype::
+% #1 : (pre.fix)
+% a prefix and a suffix separated by one colon.
+%
+% :action: ''\tdocprewhy{pre.fix}'' prints verb::''pre''.fix.
+%%%
+\NewDocumentCommand{\tdocprewhy}{m}{%
+% Do we have 2 parts?
+ \seq_set_split:Nnn \l_tmpa_seq { . } { #1 }
+
+ \int_set:Nn \l_tmpa_int
+ {\int_eval:n {\seq_count:N \l_tmpa_seq}}
+
+ \if_int_compare:w \l_tmpa_int = 2
+ \else:
+ \msg_error:nn { tutodoc ~ (macroenv) }
+ { macroenv : prefix-why-bad-format }
+ \fi:
+
+% Let's go.
+ \seq_pop:NN \l_tmpa_seq \l_tmpa_tl
+ \seq_pop:NN \l_tmpa_seq \l_tmpb_tl
+
+ \textbf{\tdocpre{\tl_use:N \l_tmpa_tl}\kern.5pt\textperiodcentered\kern.5pt{\tl_use:N \l_tmpb_tl}}
+}
+
+\ExplSyntaxOff
+
+
+% :: JUST ONE PREFIX :: %
+
+%%%
+% prototype::
+% #1 : (pre)
+% just a prefix
+%
+% :action: ''\tdocpre{pre}'' only prints verb::''pre''.
+% This can be useful in a case like
+% ''\tdocpre{pre} comes from \tdocprewhy{pre}{fix}''
+% which prints:
+% verb::''pre'' comes from verb::''pre''-fix.
+%%%
+\NewDocumentCommand{\tdocpre}{m}{%
+ \texttt{#1}%
+}
+
+
+% -- GENERAL FORMATTING -- %
+
+% :: TEXT INSIDE A RULE :: %
+
+\ExplSyntaxOn
+
+%%%
+% prototype::
+% #1 : (color)
+% the color for the rule and the text
+% #2 : (text)
+% the text surrounded by two horizontal rules
+%
+% :action: this macro adds two horizontal lines on either side of the text.
+% The final output is centered.
+%
+% note::
+% The code used comes from
+% cf::''this post ;
+% https://tex.stackexchange.com/a/604708/6880''.
+%%%
+\NewDocumentCommand{\tdocruler}{O{black} m}{
+ \par
+ {
+ \centering
+ \scriptsize
+ \itshape
+ \bfseries
+ \color{#1}
+
+ \hbox_set:Nn \l_tmpa_box { \,\, #2 \,\, }
+ \dim_set:Nn \l_tmpa_dim {
+ .35 \linewidth - .5 \box_wd:N \l_tmpa_box
+ }
+
+ \rule[.75pt] { \dim_use:N \l_tmpa_dim }
+ { 2.5pt }
+ \box_use:N \l_tmpa_box
+ \rule[.75pt] { \dim_use:N \l_tmpa_dim }
+ { 2.5pt }
+ \par
+ }
+}
+
+\ExplSyntaxOff
+
+
+% :: INTERNAL ENVIRONMENTS :: %
+
+%%%
+% prototype::
+% #1 : (up-text)
+% the descriptive text before the real output
+% #2 : (down-text)
+% the descriptive text after the real output
+% #3 : (color)
+% one color following the ''xcolor'' format.
+% This color is used to set the one for the decorated texts printed
+% corresponding to the two first arguments.
+%
+% :action: this environment just adds its content processed by \latex
+% between centered materials produced by the macro ''\tdocruler''
+% such as to stress the start and the end of the content.
+%%%
+\NewDocumentEnvironment{tutodoc at showcase@basic}{m m m}{
+ \tdocruler[\tdocdarkcolor{#3}]{#1}
+ \nopagebreak\medskip\nopagebreak
+}{
+ \nopagebreak\medskip\nopagebreak
+ \tdocruler[\tdocdarkcolor{#3}]{#2}
+}
+
+
+%%%
+% prototype::
+% #1 : (up-text)
+% :see: env.tutodoc at showcase@basic
+% #2 : (down-text)
+% :see: env.tutodoc at showcase@basic
+% #3 : (color)
+% :see: env.tutodoc at showcase@basic
+%
+% :action: this environment adds a page-width colored stripe in the
+% background of the environment content processed by \latex.
+% This stripe is preceded and followed by centered materials
+% produced by the macro ''\tdocruler'' such as to stress the
+% start and the end of the content.
+%%%
+
+\NewDocumentEnvironment{tutodoc at showcase@colorstrip}{m m m}{
+ \begin{colorstrip}{\tdoclightcolor{#3}}
+ \begin{tutodoc at showcase@basic}{#1}{#2}{#3}
+}{
+ \end{tutodoc at showcase@basic}
+ \end{colorstrip}
+}
+
+
+\ExplSyntaxOn
+
+% :: SETTING SOME KEYS :: %
+
+\tl_new:N \l_tutodoc_showcase_before_tl
+\tl_new:N \l_tutodoc_showcase_after_tl
+\tl_new:N \l_tutodoc_showcase_color_tl
+\bool_new:N \l_tutodoc_showcase_nostripe_bool
+
+
+%%%
+% We define the key-val options that will be exposed by the \env
+% ''tdocshowcase''.
+%%%
+\keys_define:nn { tutodoc / showcase } {
+% Texts.
+ before .tl_set:N = \l_tutodoc_showcase_before_tl,
+ before .initial:n = \tutodoc at trans@latex at show@start,
+ after .tl_set:N = \l_tutodoc_showcase_after_tl,
+ after .initial:n = \tutodoc at trans@latex at show@end,
+% Decorations.
+ color .tl_set:N = \l_tutodoc_showcase_color_tl,
+ color .initial:n = cyan,
+ nostripe .bool_set:N = \l_tutodoc_showcase_nostripe_bool,
+ nostripe .initial:n = false,
+}
+
+
+% :: SHOWCASE FROM TYPED CODE :: %
+
+% prototype::
+% #1 : (key-val)
+% the key-value options (see above).
+%
+% :action: this \env formats \latex code, given as an argument,
+% by framing it with texts decorated by ''\tdocruler'',
+% in order to clearly identify a rendering used as an
+% example.
+% It is also possible to have a coloured strip of the width
+% of the page in the background of the content.
+%
+% :see: env.tutodoc at showcase@basic ,
+% env.tutodoc at showcase@colorstrip
+%%%
+\NewDocumentEnvironment{tdocshowcase}{ O{} }{
+ \group_begin:
+ \keys_set:nn { tutodoc / showcase } { #1 }
+
+ \bool_if:NTF \l_tutodoc_showcase_nostripe_bool {
+ \begin{tutodoc at showcase@basic}%
+ { \tl_use:N \l_tutodoc_showcase_before_tl }%
+ { \tl_use:N \l_tutodoc_showcase_after_tl }%
+ { \tl_use:N \l_tutodoc_showcase_color_tl }
+ }{
+ \begin{tutodoc at showcase@colorstrip}%
+ { \tl_use:N \l_tutodoc_showcase_before_tl }%
+ { \tl_use:N \l_tutodoc_showcase_after_tl }%
+ { \tl_use:N \l_tutodoc_showcase_color_tl }
+ }
+}{
+ \bool_if:NTF \l_tutodoc_showcase_nostripe_bool {
+ \end{tutodoc at showcase@basic}
+ }{
+ \end{tutodoc at showcase@colorstrip}
+ }
+ \group_end:
+}
+
+
+% :: SHOWCASE FROM FILE :: %
+
+%%%
+% prototype::
+% #1 : (key-val)
+% :see: env.tdocshowcase
+% #2 : (file-path)
+% the path of a file
+%%%
+\NewDocumentCommand{\tdocshowcaseinput}{O{} m}{
+ \group_begin:
+ \keys_set_known:nnN { tutodoc / showcase }
+ { #1 }
+ \l_tmpa_tl
+
+ \exp_last_unbraced:NNV \tdocshowcase [\l_tmpa_tl]
+ \input{#2}
+ \endtdocshowcase
+ \group_end:
+}
+
+\ExplSyntaxOff
+
+
+% -- LATEX EXAMPLES -- %
+
+% :: INLINE SHORT LATEX CODE :: %
+
+%%%
+% See the \doc of the macro ''\newmintinline'' from the package ''minted''
+% to have \infos about the macro ''tdocinlatex''.
+%%%
+\newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4}
+
+
+% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: %
+
+\ExplSyntaxOn
+
+%%%
+% prototype::
+% #1 : (tdoclatex-style)
+% a style of formatting for a \latex listing and its output.
+%
+% :see: macro.tdoclatex ,
+% macro.tdoclatexinput
+%
+% In the following easy-to-understand macro, we use one fictive ''tcolorbox''
+% style such as to indicate an unknown ''tutodoc'' style to the user.
+% For example, this can give one message similar to the following one.
+%
+% term::
+% Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option
+% "NOT-A-STYLE"' and I am going to ignore it. Perhaps you misspelled it.
+%
+% See the pgfkeys package documentation for explanation.
+%%%
+\NewExpandableDocumentCommand{\tutodoc at latex@listing at formating}{ m }{
+ \str_case:nnF { #1 } {
+ { sbs } { listing ~ side ~ text }
+ { code } { listing ~ only }
+ { std } { listing ~ and ~ text }
+ } { tdoclatex ~ bad ~ option ~ "#1" }
+}
+
+\ExplSyntaxOff
+
+
+% :: THE TCOLORBOX LISTING STYLE :: %
+
+% Source.
+% * https://tex.stackexchange.com/a/604821/6880
+% * https://tex.stackexchange.com/a/327983/6880
+\tcbset{
+ tutodoc-latex-listing-style/.style = {
+ minted language = latex,
+ breakable,
+ enhanced,
+% Code and output
+ colback = yellow!5,
+% Frame
+ colframe = darkgray,
+ shadow = {.75mm}{-.75mm}{0mm}{black!30},
+ arc = .75mm,
+ left = 1mm, right = 1mm,
+ bottom = 1mm, top = 1mm,
+% We can use ''sharp corners'' to obtain an "old school" style.
+%
+% Separating line
+ segmentation style = {
+ gray,
+ dash pattern = {on 5pt off 2.5pt},
+ line width = 1.25pt
+ },
+ #1
+ },
+}
+
+
+% :: TCOLORBOX LISTING ENVIRONMENT :: %
+
+%%%
+% prototype::
+% #1 : (tdoclatex-style)
+% the style to be used (code only, code and output side by side,
+% or the standard style corresponding to the code followed by
+% its output)
+% @ #1 in [code, sbs, std]
+%
+% note::
+% See the \doc of the macro ''\newtcblisting'' from the package
+% ''tcolorbox'' to have \infos about the environment ''tdoclatex''.
+%%%
+\newtcblisting{tdoclatex}[1][std]{%
+ tutodoc-latex-listing-style = \tutodoc at latex@listing at formating{#1}
+}
+
+
+% :: TCOLORBOX IMPORTED LISTING MACRO :: %
+
+%%%
+% prototype::
+% #1 : (tdoclatex-style)
+% :see: ''\newtcblisting{tdoclatex}''
+% #2 : (file-path)
+% the path of the file to input and format.
+%
+% note::
+% See the \doc of the macro ''\newtcbinputlisting'' from the package
+% ''tcolorbox'' to have more \infos about the macro ''\tdoclatexinput''.
+%%%
+\newtcbinputlisting{\tdoclatexinput}[2][std]{
+ listing file = {#2},
+ tutodoc-latex-listing-style = \tutodoc at latex@listing at formating{#1}
+}
+
+
+% -- LATEX REAL USE CASES -- %
+
+\ExplSyntaxOn
+
+% :: SETTING THE KEY :: %
+
+\tl_new:N \l_tutodoc_listing_explain_tl
+
+%%%
+% prototype::
+% :see: macro.tdoclatexshow
+%
+% We add a key-val option specific to ''\tdoclatexshow'', the other ones
+% will be sent to ''\tdocshowcaseinput''.
+%%%
+\keys_define:nn { tutodoc / listing / latexshow } {
+ explain .tl_set:N = \l_tutodoc_listing_explain_tl,
+ explain .initial:n = { \tutodoc at trans@this at gives \tutodoc at colon },
+}
+
+
+% :: LATEXSHOW MACRO :: %
+
+%%%
+% prototype::
+% #1 : (key-val)
+% the key-value options supported by the ''tdocshowcase'' \env,
+% plus one allowing you to change the description of a line
+% printed between the code and its highlighted output.
+% #2 : (file-path)
+% the path of a file
+%
+% :see: env.tdocshowcase ,
+% macro.tdoclatexinput
+%%%
+\NewDocumentCommand{\tdoclatexshow}{O{} m}{
+ \group_begin:
+ \keys_set_known:nnN { tutodoc / listing / latexshow }
+ { #1 }
+ \l_tmpa_tl
+
+ \tdoclatexinput[code]{#2}
+
+ \tl_use:N \l_tutodoc_listing_explain_tl
+
+% Source: https://tex.stackexchange.com/a/696700/6880
+ \exp_last_unbraced:NNV \tdocshowcaseinput [\l_tmpa_tl] {#2}
+ \group_end:
+}
+
+\ExplSyntaxOff
+
+
+% -- CHANGES - WHEN? --%
+
+\ExplSyntaxOn
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { tutodoc ~ (version-n-change) }
+ { version-n-change : date-bad-format }
+ { Bad ~ format ~ for ~ a ~ date. }
+ { Use ~ YYYY-MM-DD. }
+
+
+% :: MARGIN NOTE :: %
+
+\reversemarginpar{}
+
+%%%
+% prototype::
+% #1 : (color)
+% the color of the margin note
+% #2 : (up-text)
+% the first material (a version number or nothing)
+% #3 : (down-text)
+% the second material (a date or nothing)
+% #4 : (spacing)
+% the last negative vertical spacing for the 2nd rule
+%
+% :action: this macro factorizes the printing of the changes
+% in the left margin.
+%
+% :see: \__tutodoc_translate_date:n
+%%%
+\NewDocumentCommand{\tutodoc at new@change at margin}{m m m m}{
+ \marginnote{
+ \color{#1}
+ \scriptsize
+ \centering
+
+ \vspace{0pt}
+ \rule{1.65cm}{.95pt}
+ \vspace{-2.9pt}
+
+ \IfBlankTF{#2}{}{
+ \par
+ #2\vphantom{Mp}
+ \par
+ }
+
+ \IfBlankTF{#3}{}{
+ \IfBlankTF{#2}{}{
+ \vspace{1pt}
+ }
+
+ \par
+ \__tutodoc_translate_date:n { #3 }\vphantom{Mp}
+ \par
+ }
+
+ \vspace{#4}
+ \rule{1.65cm}{.95pt}
+ }[-.345cm]
+}
+
+
+%%%
+% prototype::
+% :action: this function checks if we have something like
+% ''YYYY-MM-DD'' and then it calls the function
+% ''\__tutodoc_translate_date_process:w'' to finish
+% the job.
+%
+% :see: \__tutodoc_translate_date_process:w
+%%%
+\cs_new:Nn \__tutodoc_translate_date:n {
+ \regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{
+ \__tutodoc_translate_date_process:w #1 \q_stop
+ }{
+ \msg_error:nn { tutodoc ~ (version-n-change) }
+ { version-n-change : date-bad-format }
+ }
+}
+
+
+%%%
+% prototype::
+% :action: this function extracts year, month and day in something
+% like ''YYYY-MM-DD'' and then it calls ''\tutodoc at trans@date''
+% to use the format expected for a "localised" date.
+%%%
+\cs_new:Npn \__tutodoc_translate_date_process:w #1 - #2 - #3 \q_stop {
+ \tutodoc at trans@date{#1}
+ {#2}
+ {#3}
+}
+
+\ExplSyntaxOff
+
+
+% :: VERSION AND DATE :: %
+
+%%%
+% prototype::
+% #1 : (color)
+% the color of the margin note
+% #2 : (version)
+% a version number
+% #3 : (date)
+% a date ''YYYY-MM-DD''
+%
+% :action: this macro prints a margin note showing a version number
+% below a date, and the optional argument is used to colorize
+% all this text.
+%
+% warning::
+% The date must use an english formatting like ''2021-07-14''. This allows
+% to parse the date such as to display it following the standard convention
+% of the language chosen when loading the package.
+%%%
+\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{
+ \tutodoc at new@change at margin{#1} % Color
+ {#2} % Version
+ {#3} % Date
+ {-4.25pt} % Last negative vertical spacing
+}
+
+
+% :: DATE :: %
+
+%%%
+% prototype::
+% #1 : (color)
+% the color of the margin note
+% #2 : (date)
+% a date ''YYYY-MM-DD''
+%
+% :action: this macro is similar to ''\tdocversion'' except that it just
+% prints a date.
+%%%
+\NewDocumentCommand{\tdocdate}{O{blue} m}{
+ \tutodoc at new@change at margin{#1} % Color
+ {} % Version
+ {#2} % Date
+ {-5.35pt} % Last negative spacing
+}
+
+
+% -- CHANGES - WHAT? -- %
+
+\ExplSyntaxOn
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { tutodoc ~ (version-n-change) }
+ { version-n-change : topic-missing-title }
+ { Missing ~ title. }
+ { One ~ single ~ title ~ must ~ be ~ indicated. }
+
+
+% :: CHANGES - TOPIC :: %
+
+%%%
+% prototype::
+% #1 : (title)
+% a title that will be followed by a colon.
+% #2 : (aws-icon)
+% one material that expects to be an icon command from the
+% ''fontawsome5'' \pack.
+%
+% :action: this environment prints some \infos about specific changes
+% achieved in a new version (no special formatting is applied).
+%%%
+\NewDocumentEnvironment{tdoctopic}{ m O{} }{
+ \IfBlankT{#1}{
+ \msg_fatal:nn { tutodoc ~ (version-n-change) }
+ { version-n-change : topic-missing-title }
+ }%
+ \textbf{%
+ \IfBlankF{#2}{\tdocicon{#2}}%
+ \textsc{#1.}
+ }
+
+ \begin{itemize}
+}{
+ \end{itemize}
+}
+
+
+% :: CHANGES - NEW THINGS :: %
+
+%%%
+% We use a ''prop'' variable to factorize the code just after.
+%%%
+\prop_new:N \__g_tutodoc_topic_change_prop
+\prop_set_from_keyval:Nn \__g_tutodoc_topic_change_prop {
+ break = \faCodeBranch,
+ fix = \faWrench,
+ new = \faGem,
+ prob = \faFire*,
+ update = \faMagic,
+}
+
+
+%%%
+% prototype::
+% :see: env.tdoctopic
+%
+% :action: ''key/value'' iteration over ''\__g_tutodoc_topic_change_prop''
+% to build topic-like \envs using the \env ''tdoctopic''
+% (the title used is translated into the good language).
+%%%
+\prop_map_inline:Nn \__g_tutodoc_topic_change_prop {
+ \NewDocumentEnvironment{ tdoc#1 } {} {
+ \begin{tdoctopic}{ \use:c { tutodoc at trans@chges@#1 } } [ #2 ]
+ }{
+ \end{tdoctopic}
+ }
+}
+
+
+%%%
+% prototype::
+% #1 : (short-desc)
+% a short text expected t indicate the very first version of a project.
+%
+% :action: the short text printed will be preceded by a pretty anchor icon.
+%%%
+\NewDocumentCommand{ \tdocstartproj }{ m } {
+ \tdocicon{\faAnchor}#1
+}
+
+\ExplSyntaxOff
+
+
+% -- DECORATIONS -- %
+
+% Source
+% * https://tex.stackexchange.com/a/705938/6880
+% (for \addvspace{\medskipamount} instead of \medskip)
+
+%%%
+% prototype::
+% :action: this macro draws a centered horizontal rule with a height
+% of qty::''0.75 pt'', and a width equal to half of the current
+% text width, and extra vertical spaces are added above and
+% below the rule.
+%%%
+\NewDocumentCommand{\tdocsep}{}{
+ \par\addvspace{\medskipamount}
+ \hfill\rule{0.5\textwidth}{0.75pt}\hfill\null
+ \medskip
+ \smallskip
+}
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-10-19 20:25:40 UTC (rev 72595)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-10-19 20:26:08 UTC (rev 72596)
@@ -1,1201 +0,0 @@
-% ********************************************************* %
-% ** 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-09-28} % Creation: 2023-11-29
- {1.4.0}
- {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
-
-
-% =================== %
-% == PACKAGES USED == %
-% =================== %
-
-\RequirePackage[
- top = 2.5cm,
- bottom = 2.5cm,
- left = 2.5cm,
- right = 2.5cm,
- marginparwidth = 2cm,
- marginparsep = 2mm,
- heightrounded
-]{geometry}%
- [2020-01-02]
-
-\RequirePackage[raggedright]%
- {titlesec}%
- [2021/07/05]
-
-\RequirePackage{tocbasic}
-
-\RequirePackage{xcolor}%
- [2022/06/12]
-
-\RequirePackage{hyperref}%
- [2023-02-07]
-
-
-% We delegate the management of quoting to the `csquotes' package,
-% which takes care of the linguistic parameters.
-\RequirePackage{csquotes}%
- [2022-09-14]
-
-
-\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[highlightmode = immediate]% Too slow!
-% {minted}%
-% [2024/09/22]
-
-\RequirePackage{minted2}% Temporary patch.
-
-\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. }
- { See ~ the ~ documentation ~ for ~ the ~ supported ~ languages. }
-
-
-% ::::::::::::::::::::::: %
-% :: SETTING SOME KEYS :: %
-% ::::::::::::::::::::::: %
-
-\str_new:N \l_tdoc_opt_lang_str
-
-%%%
-% We define the key-val options that will be exposed by the package.
-%%%
-\keys_define:nn { tdoc } {
- lang .choices:nn =
- { french, english }
- {
- \tl_set:Nn \l_tdoc_opt_lang_str
- { \tl_use:N \l_keys_choice_tl }
- },
- lang .initial:n = english,
- lang / unknown .code:n =
- \msg_error:nnxxx { tdoc } { package-option-lang-unknown }
- { lang } % Name of choice key
- { french, english } % Valid choices
- { \exp_not:n {#1} } % Invalid choice given
-}
-
-\ProcessKeyOptions[tdoc]
-
-\ExplSyntaxOff
-
-
-% =============== %
-% == MAIN CODE == %
-% =============== %
-
-% --------------------- %
-% -- LOCALE SETTINGS -- %
-% --------------------- %
-
-\NewDocumentCommand{\tutodoc at colon}{}{:}
-
-% We must take care of the colons, babel and spacing.
-\@ifpackageloaded{babel}{
- \iflanguage{french}{
- \RenewDocumentCommand{\tutodoc at colon}{}{\babelshorthand{:}}
- }{}
-}{}
-
-\ExplSyntaxOn
-
-\input{tutodoc-locale-main-\l_tdoc_opt_lang_str.cfg.sty}
-
-\ExplSyntaxOff
-
-
-% ---------------------- %
-% -- GENERAL SETTINGS -- %
-% ---------------------- %
-
-\setlength{\parindent}{0cm}
-
-
-% ----------- %
-% -- LINKS -- %
-% ----------- %
-
-\hypersetup{
- colorlinks,
- citecolor = orange!75!black,
- filecolor = orange!75!black,
- linkcolor = orange!75!black,
- urlcolor = orange!75!black
-}
-
-
-% --------------- %
-% -- TOC & Co. -- %
-% --------------- %
-
-\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}
-
-
-% --------------------------- %
-% -- COLOR TRANSFORMATIONS -- %
-% --------------------------- %
-
-%%%
-% prototype::
-% #1 : the amount of color relative to black.
-% #2 : one color following the ''xcolor'' format.
-%
-% :return: a "darker" version of the color ''#1''.
-%%%
-\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}
-
-
-%%%
-% prototype::
-% #1 : the transparency rate.
-% #2 : one color following the ''xcolor'' format.
-%
-% :return: a "transparent" version of the color `#1`.
-%%%
-\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
-
-
-% ----------- %
-% -- ICONS -- %
-% ----------- %
-
-%%%
-% prototype::
-% #1 : one material that expects to be an icon command from the
-% ''fontawsome5'' \pack.
-%
-% :return: the icon followed by a small insecable space.
-%%%
-\NewDocumentCommand{\tdocicon}{m}{%
- #1\kern.45em%
-}
-
-
-% ------------- %
-% -- QUOTING -- %
-% ------------- %
-
-%%%
-% prototype::
-% #1 : a text to quote.
-%
-% For example, ''\tdocquote{Something}'' prints something like **"Something"**.
-%%%
-\NewDocumentCommand{\tdocquote}{m}{%
- \enquote{\emph{#1}}%
-}
-
-
-% ------------------------------ %
-% -- EXPLAINING ENGLISH NAMES -- %
-% ------------------------------ %
-
-%%%
-% prototype::
-% #1 : an english text to explain in another language.
-%
-% :extra: this macro has a star version.
-%
-% For example, if the language chosen is ''french'', we have
-% the following outputs.
-%
-% 1) ''\tdocinEN{Something}'' prints
-% **"Something" en anglais**.
-%
-% 2) ''\tdocinEN*{Something}'' just prints
-% **"Something"**.
-% This can be useful in a case like
-% ''\tdocinEN*{Something} et \tdocinEN{Another thing}''
-% which gives
-% **"Something" et "Another thing" en anglais**.
-%%%
-\NewDocumentCommand{\tdocinEN}{s m}{%
- \tdocquote{#2}%
- \IfBooleanF{#1}{% No star used.
- \ \tutodoc at trans@in at EN{}%
- }%
-}
-
-
-% ----------------------------------- %
-% -- SOBER HIGHLIGHTING OF CONTENT -- %
-% ----------------------------------- %
-
-% :::::::::::::::::::::: %
-% :: EXAMPLE - REMARK :: %
-% :::::::::::::::::::::: %
-
-\ExplSyntaxOn
-
-%%%
-% We use a ''seq'' variable to factorize the code just after.
-%%%
-\seq_new:N \__g_tutodoc_focus_sober_seq
-\seq_set_from_clist:Nn \__g_tutodoc_focus_sober_seq {
- exa,
- rem
-}
-
-
-%%%
-% prototype::
-% :action: looping over ''\__g_tutodoc_focus_sober_seq'' to build new
-% numbered theorems sharing the same section level counter.
-% To achieve that, we use the ''\newkeytheorem'' macro from
-% the ''keytheorems'' \pack.
-%%%
-\seq_map_inline:Nn \__g_tutodoc_focus_sober_seq {
- \str_if_eq:nnTF { #1 } { exa } {
- \newkeytheorem{tdoc#1}[
- name = \use:c { tutodoc at trans@#1 at title },
- within = section,
- ]
- } {
- \newkeytheorem{tdoc#1}[
- name = \use:c { tutodoc at trans@#1 at title },
- numberlike = tdocexa,
- ]
- }
-
- \cs_set:cpn { the tdoc #1 } { \thesection\arabic{tdoc#1} }
-}
-
-\ExplSyntaxOff
-
-
-% -------------------------------------- %
-% -- COLORFUL HIGHLIGHTING OF CONTENT -- %
-% -------------------------------------- %
-
-% ::::::::::::::::: %
-% :: ABSTRACTION :: %
-% ::::::::::::::::: %
-
-%%%
-% note::
-% The settings used come from the following sources.
-% * https://tex.stackexchange.com/a/727022/6880
-% * https://tex.stackexchange.com/a/682332/6880
-%%%
-\tcbset{
- tutodoc-focus-color-style/.style = {
- breakable,
- enhanced,
- left = 3pt,
- right = 3pt,
- 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},
- }
-}
-
-
-% ::::::::::::::::::::::::::::::::::::: %
-% :: LET'S GO BACK TO THE REAL WORLD :: %
-% ::::::::::::::::::::::::::::::::::::: %
-
-\ExplSyntaxOn
-
-%%%
-% We use two ''prop'' variables to factorize the code just after.
-%%%
-\prop_set_from_keyval:Nn \__g_tutodoc_focus_color_prop {
- note = cyan,
- tip = ForestGreen,
- imp = orange,
- caut = violet,
- warn = red,
-}
-
-\prop_set_from_keyval:Nn \__g_tutodoc_focus_icon_prop {
- note = \faInfoCircle,
- tip = \faLightbulb,
- imp = \faHighlighter,
- caut = \faBiohazard,
- warn = \faSkullCrossbones,
-}
-
-
-%%%
-% prototype::
-% :action: ''key/value'' iteration over ''\__g_tutodoc_focus_color_prop''
-% to build new colorful unumbered theorems. To achieve that,
-% we use a ''tcolorbox'' style givent to the ''\newkeytheorem''
-% macro from the ''keytheorems'' \pack, and icons from the
-% ''fontawesome5'' \pack.
-%%%
-\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 = {
- \tdocicon{ \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } }
- \use:c { tutodoc at trans@#1 at title }
- },
- ]
-}
-
-\ExplSyntaxOff
-
-
-% ---------------------------------------------- %
-% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- %
-% ---------------------------------------------- %
-
-%%%
-% prototype::
-% #1 : the name of a class
-%
-% :action: ''\tdoccls{myclass}'' prints verb::''myclass''.
-%%%
-\NewDocumentCommand{\tdoccls}{m}{%
- \texttt{#1}%
-}
-
-
-%%%
-% prototype::
-% #1 : the name of a package
-%
-% :action:''\tdocpack{mypack}'' prints verb::''mypack''.
-%%%
-\NewDocumentCommand{\tdocpack}{m}{%
- \texttt{#1}%
-}
-
-
-%%%
-% prototype::
-% #1 : the name of a macro
-%
-% :action: ''\tdocmacro{mymacro}'' prints verb::''\mymacro''.
-%%%
-\NewDocumentCommand{\tdocmacro}{m}{%
- \texttt{\textbackslash{}#1}%
-}
-
-
-%%%
-% prototype::
-% #1 : hard typed options with the good delimiters
-% #2 : the name of an environment
-%
-% :extra: this macro has a star version.
-%
-% Here are the four kind of outputs.
-%
-% 1) ''\tdocenv{myenv}'' prints
-% verb::''\begin{myenv} ... \end{myenv}''.
-%
-% 2) ''\tdocenv[{<opt1>[mando2]}]{myenv}'' prints
-% verb::''\begin{myenv}<opt1>[mando2] ... \end{myenv}''.
-%
-% 3) ''\tdocenv*{myenv}'' prints
-% verb::''myenv''.
-%
-% 4) ''\tdocenv*[{<opt1>[mando2]}]{myenv}'' prints
-% verb::''myenv''.
-%%%
-%
-% Cleaner code from https://tex.stackexchange.com/a/703379/6880 .
-\NewDocumentCommand{\tdocenv}{s O{} m}{%
- \IfBooleanTF{#1}{%
- \texttt{#3}%
- }{%
- \texttt{\string\begin\string{#3\string}#2 %
- \!\!...\@\!\!\! %
- \string\end\string{#3\string}}%
- }%
-}
-
-
-% ------------------------- %
-% -- EXPLAINING PREFIXES -- %
-% ------------------------- %
-
-\ExplSyntaxOn
-
-% :::::::::::::: %
-% :: MESSAGES :: %
-% :::::::::::::: %
-
-\msg_set:nnnn { bdoc } { prefixwhy-bad-format }
-{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
-{ You ~ must ~ use ~ one ~ single ~ point. }
-
-
-% :::::::::::::::::::: %
-% :: PREFIX FROM... :: %
-% :::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : a prefix and a suffix separated by one colon.
-%
-% :action: ''\tdocprewhy{pre.fix}'' prints verb::''pre''.fix.
-%%%
-\NewDocumentCommand{\tdocprewhy}{m}{%
-% Do we have 2 parts?
- \seq_set_split:Nnn \l_tmpa_seq { . } { #1 }
-
- \int_set:Nn \l_tmpa_int
- {\int_eval:n {\seq_count:N \l_tmpa_seq}}
-
- \if_int_compare:w \l_tmpa_int = 2
- \else:
- \msg_error:nn { bdoc } { prefixwhy-bad-format }
- \fi:
-
-% Let's go.
- \seq_pop:NN \l_tmpa_seq \l_tmpa_tl
- \seq_pop:NN \l_tmpa_seq \l_tmpb_tl
-
- \textbf{\tdocpre{\tl_use:N \l_tmpa_tl}\kern.5pt\textperiodcentered\kern.5pt{\tl_use:N \l_tmpb_tl}}
-}
-
-\ExplSyntaxOff
-
-
-% ::::::::::::::::::::: %
-% :: JUST ONE PREFIX :: %
-% ::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : just a prefix
-%
-% :action: ''\tdocpre{pre}'' only prints verb::''pre''.
-% This can be useful in a case like
-% ''\tdocpre{pre} comes from \tdocprewhy{pre}{fix}''
-% which prints:
-% verb::''pre'' comes from verb::''pre''-fix.
-%%%
-\NewDocumentCommand{\tdocpre}{m}{%
- \texttt{#1}%
-}
-
-
-% ------------------------ %
-% -- GENERAL FORMATTING -- %
-% ------------------------ %
-
-% :::::::::::::::::::::::: %
-% :: TEXT INSIDE A RULE :: %
-% :::::::::::::::::::::::: %
-
-\ExplSyntaxOn
-
-%%%
-% prototype::
-% #1 : a text
-% #2 : a color
-%
-% :action: this macro adds two horizontal lines on either side of the text.
-% The final output is centered.
-%
-% note::
-% The code used comes from
-% cf::''this post ;
-% https://tex.stackexchange.com/a/604708/6880''.
-%%%
-\NewDocumentCommand{\tdocruler}{m m}{
- \par
- {
- \centering
- \scriptsize
- \itshape
- \bfseries
- \color{#2}
-
- \hbox_set:Nn \l_tmpa_box { \,\, #1 \,\, }
- \dim_set:Nn \l_tmpa_dim {
- .35 \linewidth - .5 \box_wd:N \l_tmpa_box
- }
-
- \rule[.75pt] { \dim_use:N \l_tmpa_dim }
- { 2.5pt }
- \box_use:N \l_tmpa_box
- \rule[.75pt] { \dim_use:N \l_tmpa_dim }
- { 2.5pt }
- \par
- }
-}
-
-\ExplSyntaxOff
-
-
-% ::::::::::::::::::::::::::: %
-% :: INTERNAL ENVIRONMENTS :: %
-% ::::::::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : the text before the real output
-% #2 : the text after the real output
-% #3 : one color following the ''xcolor'' format.
-% This color is used to set the one for the decorated texts printed
-% corresponding to the two first arguments.
-%
-% :action: this environment just adds its content processed by \latex
-% between centered materials produced by the macro ''\tdocruler''
-% such as to stress the start and the end of the content.
-%%%
-\NewDocumentEnvironment{tdoc at showcase@basic}{m m m}{
- \tdocruler{#1}{\tdocdarkcolor{#3}}
- \nopagebreak\medskip\nopagebreak
-}{
- \nopagebreak\medskip\nopagebreak
- \tdocruler{#2}{\tdocdarkcolor{#3}}
-}
-
-
-%%%
-% prototype::
-% #1 : the text before the real output
-% #2 : the text after the real output
-% #3 : the color following the ''xcolor'' format.
-% This color is used to set the ones of the stripe and the decorated
-% texts printed (see the two first arguments).
-%
-% :action: this environment adds a page-width colored stripe in the
-% background of the environment content processed by \latex.
-% This stripe is preceded and followed by centered materials
-% produced by the macro ''\tdocruler'' such as to stress the
-% start and the end of the content.
-%%%
-
-\NewDocumentEnvironment{tdoc at showcase@colorstrip}{m m m}{
- \begin{colorstrip}{\tdoclightcolor{#3}}
- \begin{tdoc at showcase@basic}{#1}{#2}{#3}
-}{
- \end{tdoc at showcase@basic}
- \end{colorstrip}
-}
-
-
-\ExplSyntaxOn
-
-% ::::::::::::::::::::::: %
-% :: SETTING SOME KEYS :: %
-% ::::::::::::::::::::::: %
-
-\tl_new:N \l_tdoc_showcase_before_tl
-\tl_new:N \l_tdoc_showcase_after_tl
-\tl_new:N \l_tdoc_showcase_color_tl
-\bool_new:N \l_tdoc_showcase_nostripe_bool
-
-
-%%%
-% prototype::
-% :see: env.tdocshowcase
-%
-% We define the key-val options that will be exposed by the \env
-% ''tdocshowcase''.
-%%%
-\keys_define:nn { tdoc/showcase } {
-% Texts.
- before .tl_set:N = \l_tdoc_showcase_before_tl,
- before .initial:n = \tutodoc at trans@latex at show@start,
- after .tl_set:N = \l_tdoc_showcase_after_tl,
- after .initial:n = \tutodoc at trans@latex at show@end,
-% Decorations.
- color .tl_set:N = \l_tdoc_showcase_color_tl,
- color .initial:n = cyan,
- nostripe .bool_set:N = \l_tdoc_showcase_nostripe_bool,
- nostripe .initial:n = false,
-}
-
-
-% :::::::::::::::::::::::::::::: %
-% :: SHOWCASE FROM TYPED CODE :: %
-% :::::::::::::::::::::::::::::: %
-
-% prototype::
-% #1 : the key-value options.
-%
-% :action: this \env formats \latex code, given as an argument,
-% by framing it with texts decorated by ''\tdocruler'',
-% in order to clearly identify a rendering used as an
-% example.
-% It is also possible to have a coloured strip of the width
-% of the page in the background of the content.
-%
-% :see: env.tdoc at showcase@basic ,
-% env.tdoc at showcase@colorstrip
-%%%
-\NewDocumentEnvironment{tdocshowcase}{ O{} }{
- \group_begin:
- \keys_set:nn { tdoc/showcase } { #1 }
-
- \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
- \begin{tdoc at showcase@basic}%
- { \tl_use:N \l_tdoc_showcase_before_tl }%
- { \tl_use:N \l_tdoc_showcase_after_tl }%
- { \tl_use:N \l_tdoc_showcase_color_tl }
- }{
- \begin{tdoc at showcase@colorstrip}%
- { \tl_use:N \l_tdoc_showcase_before_tl }%
- { \tl_use:N \l_tdoc_showcase_after_tl }%
- { \tl_use:N \l_tdoc_showcase_color_tl }
- }
-}{
- \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
- \end{tdoc at showcase@basic}
- }{
- \end{tdoc at showcase@colorstrip}
- }
- \group_end:
-}
-
-
-% :::::::::::::::::::::::: %
-% :: SHOWCASE FROM FILE :: %
-% :::::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : the key-value options supported by the ''tdocshowcase'' \env.
-% #2 : the path of a file
-%
-% :see: env.tdocshowcase
-%%%
-\NewDocumentCommand{\tdocshowcaseinput}{O{} m}{
- \group_begin:
- \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl
-
- \exp_last_unbraced:NNV \tdocshowcase [\l_tmpa_tl]
- \input{#2}
- \endtdocshowcase
- \group_end:
-}
-
-\ExplSyntaxOff
-
-
-% -------------------- %
-% -- LATEX EXAMPLES -- %
-% -------------------- %
-
-% ::::::::::::::::::::::::::::: %
-% :: INLINE SHORT LATEX CODE :: %
-% ::::::::::::::::::::::::::::: %
-
-%%%
-% See the \doc of the macro ''\newmintinline'' from the package ''minted''
-% to have \infos about the macro ''tdocinlatex''.
-%%%
-\newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4}
-
-
-% ::::::::::::::::::::::::::::::::::::::::::::::: %
-% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: %
-% ::::::::::::::::::::::::::::::::::::::::::::::: %
-
-\ExplSyntaxOn
-
-%%%
-% prototype::
-% #1 : a style of formatting for a \latex listing and its output.
-%
-% :see: macro.tdoclatex , macro.tdoclatexinput
-%
-% In the following easy-to-understand macro, we use one fictive ''tcolorbox''
-% style such as to indicate an unknown ''tdoc'' style to the user.
-% For example, this can give one message similar to the following one.
-%
-% term::
-% Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option
-% "NOT-A-STYLE"' and I am going to ignore it. Perhaps you misspelled it.
-%
-% See the pgfkeys package documentation for explanation.
-%%%
-\NewExpandableDocumentCommand{\tutodoc at latex@listing at formating}{ m }{
- \str_case:nnF { #1 } {
- { sbs } { listing ~ side ~ text }
- { code } { listing ~ only }
- { std } { listing ~ and ~ text }
- } { tdoclatex ~ bad ~ option ~ "#1" }
-}
-
-\ExplSyntaxOff
-
-
-% ::::::::::::::::::::::::::::::::: %
-% :: THE TCOLORBOX LISTING STYLE :: %
-% ::::::::::::::::::::::::::::::::: %
-
-%%%
-% note::
-% The settings used come from the following sources.
-% * https://tex.stackexchange.com/a/604821/6880
-% * https://tex.stackexchange.com/a/327983/6880
-%%%
-\tcbset{
- tdoclatex_tcbstyle/.style = {
- minted language = latex,
- breakable,
- enhanced,
-% Code and output
- colback = yellow!5,
-% Frame
- colframe = darkgray,
- shadow = {.75mm}{-.75mm}{0mm}{black!30},
- arc = .75mm,
- left = 1mm, right = 1mm,
- bottom = 1mm, top = 1mm,
-% We can use ''sharp corners'' to obtain an "old school" style.
-%
-% Separating line
- segmentation style = {
- gray,
- dash pattern = {on 5pt off 2.5pt},
- line width = 1.25pt
- },
- #1
- },
-}
-
-
-% ::::::::::::::::::::::::::::::::::: %
-% :: TCOLORBOX LISTING ENVIRONMENT :: %
-% ::::::::::::::::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : the style to be used (code only, code and output side by side,
-% or the standard style corresponding to the code followed by
-% its output)
-% @ #1 in [code, sbs, std]
-%
-% note::
-% See the \doc of the macro ''\newtcblisting'' from the package
-% ''tcolorbox'' to have \infos about the environment ''tdoclatex''.
-%%%
-\newtcblisting{tdoclatex}[1][std]{%
- tdoclatex_tcbstyle = \tutodoc at latex@listing at formating{#1}
-}
-
-
-% :::::::::::::::::::::::::::::::::::::: %
-% :: TCOLORBOX IMPORTED LISTING MACRO :: %
-% :::::::::::::::::::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : :see: ''\newtcblisting{tdoclatex}'' just before.
-% #2 : the path of the file to input and format.
-%
-% note::
-% See the \doc of the macro ''\newtcbinputlisting'' from the package
-% ''tcolorbox'' to have more \infos about the macro ''\tdoclatexinput''.
-%%%
-\newtcbinputlisting{\tdoclatexinput}[2][std]{
- listing file = {#2},
- tdoclatex_tcbstyle = \tutodoc at latex@listing at formating{#1}
-}
-
-
-% -------------------------- %
-% -- LATEX REAL USE CASES -- %
-% -------------------------- %
-
-\ExplSyntaxOn
-
-% ::::::::::::::::::::::: %
-% :: SETTING SOME KEYS :: %
-% ::::::::::::::::::::::: %
-
-\tl_new:N \l_tdoc_listing_explain_tl
-
-%%%
-% prototype::
-% :see: macro.tdoclatexshow
-%
-% We define the key-val options that will be exposed by ''\tdoclatexshow''.
-%%%
-\keys_define:nn { tdoc/latexshow } {
- explain .tl_set:N = \l_tdoc_listing_explain_tl,
- explain .initial:n = { \tutodoc at trans@this at gives \tutodoc at colon },
-}
-
-
-% ::::::::::::::::::::: %
-% :: LATEXSHOW MACRO :: %
-% ::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : the key-value options supported by the ''tdocshowcase'' \env,
-% plus one allowing you to change the description of a line
-% printed between the code and its focused output.
-% #2 : the path of a file
-%
-% :see: env.tdocshowcase ,
-% macro.tdoclatexinput
-%%%
-\NewDocumentCommand{\tdoclatexshow}{O{} m}{
- \group_begin:
- \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl
-
- \tdoclatexinput[code]{#2}
-
- \tl_use:N \l_tdoc_listing_explain_tl
-
-% Source: https://tex.stackexchange.com/a/696700/6880
- \exp_last_unbraced:NNV \tdocshowcaseinput [\l_tmpa_tl] {#2}
- \group_end:
-}
-
-\ExplSyntaxOff
-
-
-% -- CHANGES - WHEN? --%
-
-\ExplSyntaxOn
-
-% :::::::::::::: %
-% :: MESSAGES :: %
-% :::::::::::::: %
-
-\msg_set:nnnn { tdoc } { date-bad-format }
- { Bad ~ format ~ for ~ a ~ date. }
- { Use ~ YYYY-MM-DD. }
-
-
-% ::::::::::::::::: %
-% :: MARGIN NOTE :: %
-% ::::::::::::::::: %
-
-\reversemarginpar{}
-
-%%%
-% prototype::
-% #1 : the color of the margin note
-% #2 : the first material (a version number or nothing)
-% #3 : the second material (a date or nothing)
-% #4 : the last negative vertical spacing for the 2nd rule
-%
-% :action: this macro factorizes the printing of the changes
-% in the left margin.
-%
-% :see: \__tdoc_translate_date:n
-%%%
-\NewDocumentCommand{\tutodoc at new@change at margin}{m m m m}{
- \marginnote{
- \color{#1}
- \scriptsize
- \centering
-
- \vspace{0pt}
- \rule{1.65cm}{.95pt}
- \vspace{-2.9pt}
-
- \IfBlankTF{#2}{}{
- \par
- #2\vphantom{Mp}
- \par
- }
-
- \IfBlankTF{#3}{}{
- \IfBlankTF{#2}{}{
- \vspace{1pt}
- }
-
- \par
- \__tdoc_translate_date:n { #3 }\vphantom{Mp}
- \par
- }
-
- \vspace{#4}
- \rule{1.65cm}{.95pt}
- }[-.345cm]
-}
-
-
-%%%
-% prototype::
-% :action: this function checks if we have something like
-% ''YYYY-MM-DD'' and then it calls the function
-% ''\__tdoc_translate_date_process:w'' to finish
-% the job.
-%
-% :see: \__tdoc_translate_date_process:w
-%%%
-\cs_new:Nn \__tdoc_translate_date:n {
- \regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{
- \__tdoc_translate_date_process:w #1 \q_stop
- }{
- \msg_error:nn { tdoc } { date-bad-format }
- }
-}
-
-
-%%%
-% prototype::
-% :action: this function extracts year, month and day in something
-% like ''YYYY-MM-DD'' and then it calls ''\tutodoc at trans@date''
-% to use the format expected for a "localised" date.
-%%%
-\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop {
- \tutodoc at trans@date{#1}
- {#2}
- {#3}
-}
-
-\ExplSyntaxOff
-
-
-% :::::::::::::::::::::: %
-% :: VERSION AND DATE :: %
-% :::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : the color of the margin note
-% #2 : a version number
-% #3 : a date ''YYYY-MM-DD''
-%
-% :action: this macro prints a margin note showing a version number
-% below a date, and the optional argument is used to colorize
-% all this text.
-%
-% warning::
-% The date must use an english formatting like ''2021-07-14''. This allows
-% to parse the date such as to display it following the standard convention
-% of the language chosen when loading the package.
-%%%
-\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{
- \tutodoc at new@change at margin{#1} % Color
- {#2} % Version
- {#3} % Date
- {-4.25pt} % Last negative vertical spacing
-}
-
-
-% :::::::::: %
-% :: DATE :: %
-% :::::::::: %
-
-%%%
-% prototype::
-% #1 : the color of the margin note
-% #2 : a date ''YYYY-MM-DD''
-%
-% :action: this macro is similar to ''\tdocversion'' except that it just
-% prints a date.
-%%%
-\NewDocumentCommand{\tdocdate}{O{blue} m}{
- \tutodoc at new@change at margin{#1} % Color
- {#2} % Date
- {} % Version
- {-5.35pt} % Last negative spacing
-}
-
-
-% --------------------- %
-% -- CHANGES - WHAT? -- %
-% --------------------- %
-
-\ExplSyntaxOn
-
-% :::::::::::::: %
-% :: MESSAGES :: %
-% :::::::::::::: %
-
-\msg_set:nnnn { tdoc } { changes-topic-missing-title }
- { Missing ~ title. }
- { One ~ single ~ title ~ must ~ be ~ indicated. }
-
-
-% ::::::::::::::::::::: %
-% :: CHANGES - TOPIC :: %
-% ::::::::::::::::::::: %
-
-%%%
-% prototype::
-% #1 : a title that will be followed by a colon.
-% #2 : one material that expects to be an icon command from the
-% ''fontawsome5'' \pack.
-%
-% :action: this environment prints some ¨infos about specific changes
-% achieved in a new version (no special formatting is applied).
-%%%
-\NewDocumentEnvironment{tdoctopic}{ m O{} }{
- \IfBlankT{#1}{
- \msg_fatal:nn { tdoc } { changes-topic-missing-title }
- }%
- \textbf{%
- \IfBlankF{#2}{\tdocicon{#2}}%
- \textsc{#1.}
- }
-
- \begin{itemize}
-}{
- \end{itemize}
-}
-
-
-% :::::::::::::::::::::::::: %
-% :: CHANGES - NEW THINGS :: %
-% :::::::::::::::::::::::::: %
-
-%%%
-% We use a ''prop'' variable to factorize the code just after.
-%%%
-\prop_new:N \__g_tutodoc_topic_change_prop
-\prop_set_from_keyval:Nn \__g_tutodoc_topic_change_prop {
- break = \faCodeBranch,
- fix = \faWrench,
- new = \faGem,
- prob = \faFire*,
- update = \faMagic,
-}
-
-
-%%%
-% prototype::
-% :see: env.tdoctopic
-%
-% :action: ''key/value'' iteration over ''\__g_tutodoc_topic_change_prop''
-% to build topic-like \envs using the \env ''tdoctopic''
-% (the title used is translated into the good language).
-%%%
-\prop_map_inline:Nn \__g_tutodoc_topic_change_prop {
- \NewDocumentEnvironment{ tdoc#1 } {} {
- \begin{tdoctopic}{ \use:c { tutodoc at trans@chges@#1 } } [ #2 ]
- }{
- \end{tdoctopic}
- }
-}
-
-
-%%%
-% prototype::
-% #1 : a short text expected t indicate the very first version of a project.
-%
-% :action: the short text printed will be preceded by a pretty anchor icon.
-%%%
-\NewDocumentCommand{ \tdocstartproj }{ m } {
- \tdocicon{\faAnchor}#1
-}
-
-\ExplSyntaxOff
-
-
-% ----------------- %
-% -- DECORATIONS -- %
-% ----------------- %
-
-% Source for \addvspace{\medskipamount} instead of \medskip.
-% * https://tex.stackexchange.com/a/705938/6880
-
-%%%
-% prototype::
-% :action: this macro draws a centered horizontal rule with a height
-% of qty::''0.75 pt'', and a width equal to half of the current
-% text width.
-% Extra vertical spaces are added above and below the rule.
-%%%
-\NewDocumentCommand{\tdocsep}{}{
- \par\addvspace{\medskipamount}
- \hfill\rule{0.5\textwidth}{0.75pt}\hfill\null
- \medskip
- \smallskip
-}
More information about the tex-live-commits
mailing list.