texlive[72405] Master/texmf-dist: tutodoc (29sep24)
commits+karl at tug.org
commits+karl at tug.org
Sun Sep 29 22:39:29 CEST 2024
Revision: 72405
https://tug.org/svn/texlive?view=revision&revision=72405
Author: karl
Date: 2024-09-29 22:39:29 +0200 (Sun, 29 Sep 2024)
Log Message:
-----------
tutodoc (29sep24)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2024-09-29 20:39:18 UTC (rev 72404)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2024-09-29 20:39:29 UTC (rev 72405)
@@ -35,7 +35,6 @@
\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
\begin{tdoctopic}{End of icons}
-% This is where the point needs to be put.
\item Info 1...
\item Info 2...
\end{tdoctopic}
@@ -66,6 +65,11 @@
\end{filecontents*}
+\begin{filecontents*}[overwrite]{examples-version-n-change-first.tex}
+\tdocstartproj{1st version of the project.}
+\end{filecontents*}
+
+
\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex}
\begin{tdocbreak}
\item Info 1...
@@ -101,7 +105,6 @@
\begin{filecontents*}[overwrite]{examples-focus-exa-leavevmode.tex}
\begin{tdocexa}
\leavevmode
-
\begin{enumerate}
\item Point 1.
@@ -134,13 +137,13 @@
\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
-\begin{tdoccaution}
+\begin{tdoccaut}
Caution, caution...
-\end{tdoccaution}
+\end{tdoccaut}
-\begin{tdoccaution}[Mini title]
+\begin{tdoccaut}[Mini title]
Useful?
-\end{tdoccaution}
+\end{tdoccaut}
\end{filecontents*}
@@ -167,23 +170,13 @@
\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
-Bla, bla, bla...
-
\begin{tdocexa}
- Ble, ble, ble...
+ An example...
\end{tdocexa}
-\begin{tdocexa}[Wonderful]
- Bli, bli, bli...
+\begin{tdocexa}[Mini title]
+ Useful?
\end{tdocexa}
-
-\begin{tdocexa}<nonb>
- Blo, blo, blo...
-\end{tdocexa}
-
-\begin{tdocexa}<nonb>[Superb]
- Blu, blu, blu...
-\end{tdocexa}
\end{filecontents*}
@@ -192,6 +185,10 @@
Just one remark...
\end{tdocrem}
+\begin{tdocrem}
+ Another?
+\end{tdocrem}
+
\begin{tdocrem}[Mini title]
Useful?
\end{tdocrem}
@@ -292,14 +289,17 @@
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
+
\usepackage[english]{babel, varioref}
-\usepackage{enumitem}
-\usepackage{multicol}
+
+
+\usepackage{enumitem}
\usepackage{fmtcount}
+\usepackage{multicol}
\setlength{\parindent}{0em}
\newcommand\thispack{\tdocpack{tutodoc}}
@@ -376,19 +376,19 @@
\title{The \texttt{tutodoc} package - Tutorial-style documentation}
\author{Christophe BAL}
-\date{Sep 25, 2024 - Version 1.3.0}
+\date{Sep 28, 2024 - Version 1.4.0}
\maketitle
\begin{abstract}
- The \thispack{} package
+ The \thispack{} package\,%
\footnote{
The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
}
- is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style
+ is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style,%
\footnote{
The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected of coding documentation.
- },
+ }
and with a sober rendering for reading on screen.
\medskip
@@ -540,20 +540,25 @@
\end{tdocnote}
+\subsection{Content in the reading flow}
-\subsection{Examples}
-Numbered or unnumbered examples can be indicated using the \tdocenv{tdocexa} environment, which offers two optional arguments.
+% ------------------ %
-\begin{enumerate}
- \item The \ordinalnum{1} argument between brackets \tdocinlatex#<...># can take the values \tdocinlatex#nb# to number, which is the default setting, and \tdocinlatex#nonb# to not number.
- \item The \ordinalnum{2} argument in square brackets \tdocinlatex#[...]# is used to add a mini-title..
-\end{enumerate}
+\begin{tdocimp}
+ All the environments presented in this section share the same counter.
+\end{tdocimp}
-Here are some possible uses.
+% ------------------ %
+
+\subsubsection{Examples}
+
+Numbered examples, if required, are indicated via \tdocenv{tdocexa}, which offers an optional argument for adding a mini-title.
+Here are two possible uses.
+
\tdoclatexinput[sbs]{examples-focus-exa.tex}
@@ -562,7 +567,7 @@
\begin{tdocimp}
- The numbering of the examples is reset to zero as soon as a section with a level at least equal to a \tdocinlatex|\subsubsection| is opened.
+ The numbering of the examples is reset to zero as soon as a section with a level at least equal to a \tdocinlatex|\section| is opened.
\end{tdocimp}
@@ -570,25 +575,40 @@
\begin{tdoctip}
- It can sometimes be useful to return to the line at the start of the content. Here's how to do it (this trick remains valid for the environments presented in the following sub-sections). Note in passing that the numbering follows that of the previous example as desired.
+ 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-focus-exa-leavevmode.tex}
-\end{tdoctip}
-\subsection{Some remarks}
+% \subsection{Content in the reading flow}
-Everything happens via the \tdocenv{tdocrem} environment, as in the following example.
+\subsubsection{Some remarks}
+Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocenv*{tdocexa} environment, as shown in the following example.
+
\tdoclatexinput[sbs]{examples-focus-rmk.tex}
-\subsection{A tip}
+\subsection{Flashy content} \label{tdoc-colorful-focus}
-The \tdocenv{tdoctip} environment is used to give tips. Here's how to use it.
+\begin{tdocnote}
+ Icons are obtained via the \tdocpack{fontawesome5} package, and text spacing is managed by the \tdocmacro{tdocicon} macro.
+ \footnote{
+ For example,
+ \tdocinlatex|\tdocicon{\faBed}{Tired}|
+ produces\,
+ \tdocicon{\faBed}{Tired}.
+ }
+\end{tdocnote}
+
+\subsubsection{A tip}
+
+The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it.
+
\tdoclatexinput[sbs]{examples-focus-tip.tex}
@@ -596,43 +616,47 @@
\smallskip
\begin{tdocnote}
- Colors are provided by the extensible macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor}, which have the following codes.
-
- \begin{tdoclatex}[code]
-\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
-\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
- \end{tdoclatex}
+ Colors are obtained via the expandable macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor}.
+ For further information, please refer to the end of the section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}.
\end{tdocnote}
-\subsection{Informative note}
+%\subsection{Flashy content}
-The \tdocenv{tdocnote} environment is used to highlight useful information. Here's how to use it.
+\subsubsection{Informative note}
+The \tdocenv*{tdocnote} environment is used to highlight useful information. Here's how to use it.
+
\tdoclatexinput[sbs]{examples-focus-note.tex}
-\subsection{Something important}
+%\subsection{Flashy content}
-The \tdocenv{tdocimp} environment is used to indicate something important but harmless.
+\subsubsection{Something important}
+The \tdocenv*{tdocimp} environment is used to indicate something important but harmless.
+
\tdoclatexinput[sbs]{examples-focus-important.tex}
-\subsection{Caution about a delicate point}
+%\subsection{Flashy content}
-The \tdocenv{tdoccaution} environment is used to indicate a delicate point to the user. Here's how to use it.
+\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{Warning of danger}
+%\subsection{Flashy content}
-The \tdocenv{tdocwarn} environment is used to warn the user of a trap to avoid. Here's how to use it.
+\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}
@@ -643,36 +667,28 @@
\begin{tdoclatex}[sbs]
-\tdoccls{myclass} is for...
-
-\tdocpack{mypackage} is for...
-
-\tdocmacro{onemacro} is for...
-
-\tdocenv{env} produces...
-
-We also have :
-
-\tdocenv[{[opt1]<opt2>}]{env}
+\tdoccls{myclass} is for... \\
+\tdocpack{mypackage} is for... \\
+\tdocmacro{onemacro} is for... \\
+\tdocenv{env} produces... \\
+\tdocenv[{[opt1]<opt2>}]{env} \\
+Just \tdocenv*{env}... \\
+Finally \tdocenv*[{[opt1]<opt2>}]{env}...
\end{tdoclatex}
\begin{tdocrem}
- The advantage of the previous macros over the use of \tdocmacro{tdocinlatex}, see the section \ref{tdoc-listing-inline} page \pageref{tdoc-listing-inline}, is the absence of colouring.
- Furthermore, the \tdocmacro{tdocenv} macro simply asks you to type the name of the environment
- \footnote{
- In addition, \tdocinlatex{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if necessary.
- }
- with any options by typing the correct delimiters
- \footnote{
- Remember that almost anything is possible from now on.
- }
- by hand.
+ Unlike \tdocmacro{tdocinlatex}, \tdocmacro{tdocenv} and \tdocmacro{tdocenv*} macros don't color the text they produce.
+ In addition, \tdocinlatex{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if required.
\end{tdocrem}
\begin{tdocwarn}
- The optional argument to the \tdocmacro{tdocenv} macro is copied and pasted during rendering. This can sometimes require the use of protective braces, as in the previous example.
+ The optional argument of the \tdocmacro{tdocenv} macro is copied and pasted
+ \footnote{
+ Remember that almost anything is possible from now on.
+ }
+ when rendering. This may sometimes require the use of protective braces, as in the example above.
\end{tdocwarn}
@@ -683,10 +699,8 @@
\begin{tdoclatex}[sbs]
-\tdocpre{sup} relates to...
-
-\tdocprewhy{sup.erbe} means...
-
+\tdocpre{sup} relates to... \\
+\tdocprewhy{sup.erbe} means... \\
\emph{\tdocprewhy{sup.er} for...}
\end{tdoclatex}
@@ -702,7 +716,7 @@
-\subsection{With a coloured stripe}
+\subsection{With a coloured stripe} \label{tdoc-color-macros}
\begin{tdocexa} [With default text]
It can be useful to show a real rendering directly in a document.
@@ -756,20 +770,27 @@
\begin{tdocnote}
You've probably noticed that red is used as a base to obtain the colors used.
-
+
\begin{itemize}
\item The background color is provided by \tdocmacro{tdocbackcolor}.
\item The color of titles and lines is provided by \tdocmacro{tdocdarkcolor}.
\end{itemize}
-
- These expandable macros have a single argument, the chosen color, and accept the following codes.
+ These expandable macros accept the following codes.
+
\begin{tdoclatex}[code]
-\NewExpandableDocumentCommand{tdocbackcolor}{m}{#1!5}
-\NewExpandableDocumentCommand{tdocdarkcolor}{m}{#1!50!black}
+% Argument 1 : optionally, the amount of color relative to black can be specified.
+% In general, there's no need to change this setting!
+% Argument 2 : a color in xcolor format.
+\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}
+
+% Argument 1 : optionally, the transparency rate can be specified.
+% In general, there's no need to change this setting!
+% Argument 2 : a color in xcolor format.
+\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
\end{tdoclatex}
-
+
You also have to know that behind the scene, the \tdocmacro{tdocruler} macro is used.
\begin{tdoclatex}[std]
@@ -840,7 +861,7 @@
To obtain renderings by importing the code from an external file, instead of typing it, simply use the \tdocmacro{tdocshowcaseinput} macro whose option uses the syntax of that of \tdocenv{tdocshowcase} and the mandatory argument corresponds to the path of the file.
-\begin{tdocexa}<nonb>
+\begin{tdocexa}
The following was obtained via \tdocinlatex+\tdocshowcaseinput{external.tex}+.
\medskip
@@ -867,6 +888,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.
+
+\end{tdoccaut}
+
+
\subsection{\tdocquote{Inline} codes} \label{tdoc-listing-inline}
The \tdocmacro{tdocinlatex} macro
@@ -957,7 +984,7 @@
\medskip
-The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same options as the \tdocenv{tdoclatex} environment.
+The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same options as the \tdocenv*{tdoclatex} environment.
% ------------------ %
@@ -1055,7 +1082,7 @@
\begin{tdocexa}[The options available]
- In addition to the explanatory text, it is also possible to use all the options of \tdocenv{tdocshowcase}, see \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
+ In addition to the explanatory text, it is also possible to use all the options of \tdocenv*{tdocshowcase} environment, see \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
Here is an example to illustrate this.
\medskip
@@ -1129,12 +1156,31 @@
\subsection{What's new?}
-\thispack{} offers different environments to indicate quickly and clearly what has been done during the latest changes.%
+\thispack{} offers the macro \tdocmacro{tdocstartproj} and different environments to indicate quickly and clearly what has been done during the latest changes.%
\footnote{
The user doesn't need all the technical details.
}
+\begin{tdocnote}
+ For icons, see the note at the beginning of the section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Just for the very first version]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-first.tex}
+
+\end{tdocexa}
+
+
+% ------------------ %
+
+
\begin{tdocexa}[For new features]
\leavevmode
@@ -1211,7 +1257,7 @@
\section{Ornaments}
-Let's finish this documentation with a few small formatting tools that can be very useful.
+Let's finish this documentation with a small formatting tool that is very useful.
\begin{tdoclatex}[sbs]
@@ -1223,30 +1269,67 @@
\begin{itemize}
\item Underline.
-
- \item Something else useful.
\end{itemize}
\tdocsep % Uniform behaviour.
Ble, ble, ble...
+\end{tdoclatex}
-Bli, bli, bli...
-\tdocxspace % Subtle space
- % but useful.
+\section{History}
-Blo, blo, blo...
+\small
-Blu, blu, blu...
+\tdocversion{1.4.0}[2024-09-28]
-\end{tdoclatex}
+\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.
-\section{History}
+ \item The unused macro \tdocmacro{tdocxspace} has been deleted.
+\end{tdocbreak}
-\small
+\begin{tdocnew}
+ \item Change log: the \tdocmacro{tdocstartproj} macro is used to manage the case of the first public version.
+
+ \item Code factorization: the \tdocmacro{tdocicon} macro is responsible for adding icons in front of text.
+\end{tdocnew}
+
+
+\begin{tdocupdate}
+ \item Colors: the \tdocmacro{tdocdarkcolor} and \tdocmacro{tdoclightcolor} macros offer an optional argument.
+ \begin{enumerate}
+ \item \tdocmacro{tdocdarkcolor} : the amount of color in relation to black can be optionally defined.
+
+ \item \tdocmacro{tdoclightcolor} : the transparency rate can be optionally defined.
+ \end{enumerate}
+
+ \item Content highlighting: reduced space around content in colored frames.
+
+ \item Versioning: better vertical spacing thanks to \tdocmacro{vphantom}.
+\end{tdocupdate}
+
+\tdocsep
+
+
+% ------------------ %
+
+
+\tdocversion{1.3.1}[2024-09-26]
+
+\begin{tdocnew}
+ \item Star version of \tdocmacro{tdocenv} to display only the environment name.
+\end{tdocnew}
+
+\tdocsep
+
+
+% ------------------ %
+
+
\tdocversion{1.3.0}[2024-09-25]
\begin{tdocprob}
@@ -1255,7 +1338,7 @@
\begin{tdocbreak}
- \item The \verb#tdocimportant# environment has been renamed \verb#tdocimp# for simplified input.
+ \item The \tdocenv*{tdocimportant} environment has been renamed \tdocenv*{tdocimp} for simplified input.
\end{tdocbreak}
@@ -1265,14 +1348,14 @@
\item Content highlighting: colored frames with icons are proposed for the following environments.
\bgroup
- \setlength{multicolsep}{3.0pt plus 1.0pt minus 0.75pt}
+ \setlength\multicolsep{5pt}
\begin{multicols}{3}
- \begin{enumerate}
- \item \verb#tdoccaution#
- \item \verb#tdocimp#
- \item \verb#tdocnote#
- \item \verb#tdoctip#
- \item \verb#tdocwarn#
+ \begin{enumerate}[topsep=0pt]
+ \item \tdocenv*{tdoccaution}
+ \item \tdocenv*{tdocimp}
+ \item \tdocenv*{tdocnote}
+ \item \tdocenv*{tdoctip}
+ \item \tdocenv*{tdocwarn}
\end{enumerate}
\end{multicols}
\egroup
@@ -1341,6 +1424,6 @@
\tdocversion{1.0.0}[2023-11-29]
-First public version of the project.
+\tdocstartproj{First public version of the project.}
\end{document}
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2024-09-29 20:39:18 UTC (rev 72404)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2024-09-29 20:39:29 UTC (rev 72405)
@@ -35,7 +35,6 @@
\begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex}
\begin{tdoctopic}{La fin des icônes}
-% Ici le point s'impose.
\item Info 1...
\item Info 2...
\end{tdoctopic}
@@ -66,6 +65,11 @@
\end{filecontents*}
+\begin{filecontents*}[overwrite]{examples-version-n-change-first.tex}
+\tdocstartproj{Première version du projet.}
+\end{filecontents*}
+
+
\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex}
\begin{tdocbreak}
\item Info 1...
@@ -101,7 +105,6 @@
\begin{filecontents*}[overwrite]{examples-focus-exa-leavevmode.tex}
\begin{tdocexa}
\leavevmode
-
\begin{enumerate}
\item Point 1.
@@ -134,13 +137,13 @@
\begin{filecontents*}[overwrite]{examples-focus-caution.tex}
-\begin{tdoccaution}
+\begin{tdoccaut}
Prudence, prudence...
-\end{tdoccaution}
+\end{tdoccaut}
-\begin{tdoccaution}[Mini titre]
+\begin{tdoccaut}[Mini titre]
Utile ?
-\end{tdoccaution}
+\end{tdoccaut}
\end{filecontents*}
@@ -167,23 +170,13 @@
\begin{filecontents*}[overwrite]{examples-focus-exa.tex}
-Bla, bla, bla...
-
\begin{tdocexa}
- Ble, ble, ble...
+ Un exemple...
\end{tdocexa}
-\begin{tdocexa}[Magnifique]
- Bli, bli, bli...
+\begin{tdocexa}[Mini titre]
+ Utile ?
\end{tdocexa}
-
-\begin{tdocexa}<nonb>
- Blo, blo, blo...
-\end{tdocexa}
-
-\begin{tdocexa}<nonb>[Superbe]
- Blu, blu, blu...
-\end{tdocexa}
\end{filecontents*}
@@ -353,19 +346,19 @@
\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
\author{Christophe BAL}
-\date{25 sept. 2024 - Version 1.3.0}
+\date{28 sept. 2024 - Version 1.4.0}
\maketitle
\begin{abstract}
- Le package \thispack{}
+ Le package \thispack{}\,%
\footnote{
Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} qui se traduit en \tdocquote{documentation de type tutoriel}.
}
- est utilisé par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel
+ est utilisé par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel,%
\footnote{
L'idée est de produire un fichier \texttt{PDF} efficace à parcourir pour des besoins ponctuels. C'est généralement ce que l'on attend d'une documentation liée au codage.
- },
+ }
et avec un rendu sobre pour une lecture sur écran.
\medskip
@@ -386,14 +379,14 @@
\textbf{Abstract.}
\end{center}
- The \thispack{} package
+ The \thispack{} package\,%
\footnote{
The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
}
- is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style
+ is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style,%
\footnote{
The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected of coding documentation.
- },
+ }
and with a sober rendering for reading on screen.
\medskip
@@ -547,19 +540,25 @@
-\subsection{Des exemples}
+\subsection{Du contenu dans le flot de la lecture}
-Des exemples numérotés, ou non, s'indiquent via l'environnement \tdocenv{tdocexa} qui propose deux arguments optionnels.
-\begin{enumerate}
- \item Le 1\ier{} argument entre chevrons \tdocinlatex#<...># peut prendre au choix les valeurs \tdocinlatex#nb# pour numéroter, réglage par défaut, et \tdocinlatex#nonb# pour ne pas numéroter.
+% ------------------ %
- \item Le 2\ieme{} argument entre crochets \tdocinlatex#[...]# sert à ajouter un mini-titre.
-\end{enumerate}
+\begin{tdocimp}
+ Tous les environnements présentés dans cette section partagent le même compteur.
+\end{tdocimp}
-Voici différents emplois possibles.
+% ------------------ %
+
+
+\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}
@@ -568,7 +567,7 @@
\begin{tdocimp}
- La numérotation des exemples est remise à zéro dès qu'une section de niveau au moins égale à une \tdocinlatex|\subsubsection| est ouverte.
+ 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}
@@ -576,25 +575,40 @@
\begin{tdoctip}
- Il peut parfois être utile de revenir à la ligne dès le début du contenu. Voici comment faire (ce tour de passe-passe reste valable pour les environnements présentés dans les sous-sections suivantes). Noter au passage que la numérotation suit celle de l'exemple précédent comme souhaité.
+ 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-focus-exa-leavevmode.tex}
-\end{tdoctip}
-\subsection{Des remarques}
+%\subsection{Du contenu dans le flot de la lecture}
-Tout se passe via l'environnement \tdocenv{tdocrem} comme dans l'exemple suivant.
+\subsubsection{Des remarques}
+Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'environnement \tdocenv*{tdocexa} comme le montre l'exemple suivant.
+
\tdoclatexinput[sbs]{examples-focus-rmk.tex}
-\subsection{Une astuce}
+\subsection{Du contenu tape-à-l'oeil} \label{tdoc-colorful-focus}
-L'environnement \tdocenv{tdoctip} sert à donner des astuces. Voici comment l'employer.
+\begin{tdocnote}
+ Les icônes sont obtenues via le package \tdocpack{fontawesome5}, et la gestion de l'espacement avec le texte est faite par la macro \tdocmacro{tdocicon}.
+ \footnote{
+ Par exemple,
+ \tdocinlatex|\tdocicon{\faBed}{Fatigué}|
+ produit\,
+ \tdocicon{\faBed}{Fatigué}.
+ }
+\end{tdocnote}
+
+\subsubsection{Une astuce}
+
+L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'employer.
+
\tdoclatexinput[sbs]{examples-focus-tip.tex}
@@ -602,43 +616,47 @@
\smallskip
\begin{tdocnote}
- Les couleurs sont fournies par les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor} qui admettent les codes suivants.
-
- \begin{tdoclatex}[code]
-\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
-\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
- \end{tdoclatex}
+ Les couleurs sont obtenues via les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor}.
+ Pour des informations complémentaires à ce sujet, se reporter à la fin de la section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}.
\end{tdocnote}
-\subsection{Note informative}
+%\subsection{Du contenu tape-à-l'oeil}
-L'environnement \tdocenv{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.
+\subsubsection{Note informative}
+L'environnement \tdocenv*{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.
+
\tdoclatexinput[sbs]{examples-focus-note.tex}
-\subsection{Un truc important}
+%\subsection{Du contenu tape-à-l'oeil}
-L'environnement \tdocenv{tdocimp} permet d'indiquer quelque chose d'important mais sans danger.
+\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{Avertir d'un point très délicat}
+%\subsection{Du contenu tape-à-l'oeil}
-L'environnement \tdocenv{tdoccaution} sert à indiquer un point délicat à l'utilisateur. Voici comment l'employer.
+\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{Avertir d'un danger}
+%\subsection{Du contenu tape-à-l'oeil}
-L'environnement \tdocenv{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.
+\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}
@@ -649,36 +667,28 @@
\begin{tdoclatex}[sbs]
-\tdoccls{maclasse} sert à...
-
-\tdocpack{monpackage} est pour...
-
-\tdocmacro{unemacro} permet de...
-
-\tdocenv{env} produit...
-
-On a aussi :
-
-\tdocenv[{[opt1]<opt2>}]{env}
+\tdoccls{maclasse} sert à... \\
+\tdocpack{monpackage} est pour... \\
+\tdocmacro{unemacro} permet de... \\
+\tdocenv{env} produit... \\
+\tdocenv[{[opt1]<opt2>}]{env} \\
+Juste \tdocenv*{env}... \\
+Enfin \tdocenv*[{[opt1]<opt2>}]{env}...
\end{tdoclatex}
\begin{tdocrem}
- L'intérêt des macros précédentes vis à vis de l'usage de \tdocmacro{tdocinlatex}, voir la section \ref{tdoc-listing-inline} page \pageref{tdoc-listing-inline}, est l'absence de coloration.
- De plus, la macro \tdocmacro{tdocenv} demande juste de taper le nom de l'environnement
- \footnote{
- De plus, \tdocinlatex{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin.
- }
- avec des éventuelles options en tapant les bons délimiteurs
- \footnote{
- Se souvenir que tout est possible ou presque dorénavant.
- }
- à la main.
+ Contrairement à \tdocmacro{tdocinlatex}, les macros \tdocmacro{tdocenv} et \tdocmacro{tdocenv*} ne colorent pas le texte produit.
+ De plus, \tdocinlatex{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin.
\end{tdocrem}
\begin{tdocwarn}
- L'argument optionnel de la macro \tdocmacro{tdocenv} est copié-collé lors du rendu. Ceci peut donc parfois nécessiter d'utiliser des accolades protectrices comme dans l'exemple précédent.
+ L'argument optionnel de la macro \tdocmacro{tdocenv} est copié-collé
+ \footnote{
+ Se souvenir que tout est possible ou presque dorénavant.
+ }
+ lors du rendu. Ceci peut donc parfois nécessiter d'utiliser des accolades protectrices comme dans l'exemple ci-dessus.
\end{tdocwarn}
@@ -689,10 +699,8 @@
\begin{tdoclatex}[sbs]
-\tdocpre{sup} est relatif à...
-
-\tdocprewhy{sup.erbe} signifie...
-
+\tdocpre{sup} est relatif à... \\
+\tdocprewhy{sup.erbe} signifie... \\
\emph{\tdocprewhy{sup.er} pour...}
\end{tdoclatex}
@@ -708,7 +716,7 @@
-\subsection{Avec une bande colorée}
+\subsection{Avec une bande colorée} \label{tdoc-color-macros}
\begin{tdocexa}[Avec les textes par défaut]
Il peut être utile de montrer un rendu réel directement dans un document.
@@ -762,22 +770,30 @@
\begin{tdocnote}
Vous avez sûrement remarqué que le rouge sert de base pour obtenir les couleurs utilisées.
-
+
\begin{itemize}
\item La couleur de fond est fournie par \tdocmacro{tdocbackcolor}.
\item La couleur des titres et des lignes est fournie par \tdocmacro{tdocdarkcolor}.
\end{itemize}
-
- Ces macros développables et à un seul argument, la couleur choisie, admettent les codes suivants.
+ Ces macros développables admettent les codes suivants.
+
\begin{tdoclatex}[code]
-\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
-\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
+% Argument 1 : de façon optionnelle, on peut indiquer la quantité de couleur
+% relativement au noir.
+% Il est en général inutile de modifier ce paramètre !
+% Argument 2 : une couleur au format xcolor.
+\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}
+
+% Argument 1 : de façon optionnelle, on peut indiquer le taux de transparence.
+% Il est en général inutile de modifier ce paramètre !
+% Argument 2 : une couleur au format xcolor.
+\NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1}
\end{tdoclatex}
- Il faut également savoir qu'en coulisses, la macro \tdocmacro{tdocruler} est utilisée.
-
+ Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est utilisée.
+
\begin{tdoclatex}[std]
\tdocruler{Un pseudo-titre décoré}{red}
\end{tdoclatex}
@@ -845,7 +861,7 @@
Pour obtenir des rendus en important le code depuis un fichier externe, au lieu de le taper, il suffit d'employer la macro \tdocmacro{tdocshowcaseinput} dont l'option reprend la syntaxe de celle de \tdocenv{tdocshowcase} et l'argument obligatoire correspond au chemin du fichier.
-\begin{tdocexa}<nonb>
+\begin{tdocexa}
Ce qui suit a été obtenu via \tdocinlatex+\tdocshowcaseinput{external.tex}+.
\medskip
@@ -872,9 +888,9 @@
}
-\begin{tdocwarn}
- Version 3 of \tdocpack{minted} cannot be used at the moment, as it contains bugs: see \url{https://github.com/gpoore/minted/issues/401}. We therefore force the use of version 2 of \tdocpack{minted}.
-\end{tdocwarn}
+\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}
@@ -966,7 +982,7 @@
\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}.
+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}.
% ------------------ %
@@ -1026,7 +1042,7 @@
\subsection{Codes importés et mis en situation} \label{tdoc-latexshow}
-\begin{tdocexa}[Showcase]
+\begin{tdocexa}[Mise en situation]
Ce qui suit s'obtient via \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+.
\medskip
@@ -1062,7 +1078,7 @@
\begin{tdocexa}[Les options disponibles]
- En plus du texte explicatif, il est aussi possible d'utiliser toutes les options de \tdocenv{tdocshowcase}, voir \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
+ En plus du texte explicatif, il est aussi possible d'utiliser toutes les options de l'environnement \tdocenv*{tdocshowcase}, voir \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
Voici un exemple illustrant ceci.
\medskip
@@ -1137,14 +1153,33 @@
\end{tdocwarn}
-\subsection{Quoi de neuf ?}
+\subsection{Quoi de neuf ?}
-\thispack{} propose différents environnements pour indiquer rapidement et clairement ce qui a été fait lors des derniers changements.%
+\thispack{} propose la macro \tdocmacro{tdocstartproj} et différents environnements pour indiquer rapidement et clairement ce qui a été fait lors des derniers changements.%
\footnote{
L'utilisateur n'a pas besoin de tous les détails techniques.
}
+\begin{tdocnote}
+ Concernant les icônes, voir la note au début de la section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Juste pour la toute première version]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-first.tex}
+
+\end{tdocexa}
+
+
+% ------------------ %
+
+
\begin{tdocexa}[Pour les nouveautés]
\leavevmode
@@ -1221,7 +1256,7 @@
\section{Décorations}
-Finissons cette documentation avec de petits outils de mise en forme pouvant rendre de grands services.
+Finissons cette documentation avec un petit outil de mise en forme qui rend de grands services.
\begin{tdoclatex}[sbs]
@@ -1233,30 +1268,67 @@
\begin{itemize}
\item Point souligné.
-
- \item Autre chose utile.
\end{itemize}
\tdocsep % Un comportement uniforme.
Ble, ble, ble...
+\end{tdoclatex}
-Bli, bli, bli...
-\tdocxspace % Espace subtile
- % mais utile.
+\section{Historique}
-Blo, blo, blo...
+\small
-Blu, blu, blu...
+\tdocversion{1.4.0}[2024-09-28]
-\end{tdoclatex}
+\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.
-\section{Historique}
+ \item La macro inutilisée \tdocmacro{tdocxspace} a été supprimée.
+\end{tdocbreak}
-\small
+\begin{tdocnew}
+ \item Journal des changements : la macro \tdocmacro{tdocstartproj} permet de gérer le cas de la première version publique.
+
+ \item Factorisation du code : la macro \tdocmacro{tdocicon} est en charge de l'ajout d'icônes devant du texte.
+\end{tdocnew}
+
+
+\begin{tdocupdate}
+ \item Couleurs : les macros \tdocmacro{tdocdarkcolor} et \tdocmacro{tdoclightcolor} proposent un argument facultatif.
+ \begin{enumerate}
+ \item \tdocmacro{tdocdarkcolor} : la quantité de couleur par rapport au noir peut être définie de manière facultative.
+
+ \item \tdocmacro{tdoclightcolor} : le taux de transparence peut être défini de manière facultative.
+ \end{enumerate}
+
+ \item Mise en avant de contenus : réduction de l'espace autour du contenu dans les cadres colorés.
+
+ \item Gestion des versions: un meilleur espacement verticalement via \tdocmacro{vphantom}.
+\end{tdocupdate}
+
+\tdocsep
+
+
+% ------------------ %
+
+
+\tdocversion{1.3.1}[2024-09-26]
+
+\begin{tdocnew}
+ \item Version étoilée de \tdocmacro{tdocenv} pour n'avoir que le nom de l'environnement.
+\end{tdocnew}
+
+\tdocsep
+
+
+% ------------------ %
+
+
\tdocversion{1.3.0}[2024-09-25]
\begin{tdocprob}
@@ -1265,7 +1337,7 @@
\begin{tdocbreak}
- \item L'environnement \verb#tdocimportant# a été renommé \verb#tdocimp# pour une saisie simplifiée.
+ \item L'environnement \tdocenv*{tdocimportant} a été renommé \tdocenv*{tdocimp} pour une saisie simplifiée.
\end{tdocbreak}
@@ -1275,14 +1347,14 @@
\item Mise en avant de contenus : des cadres colorés avec des icônes sont proposés pour les environnements suivants.
\bgroup
- \setlength{\multicolsep}{3.0pt plus 1.0pt minus 0.75pt}
+ \setlength\multicolsep{5pt}
\begin{multicols}{3}
\begin{enumerate}
- \item \verb#tdoccaution#
- \item \verb#tdocimp#
- \item \verb#tdocnote#
- \item \verb#tdoctip#
- \item \verb#tdocwarn#
+ \item \tdocenv*{tdoccaution}
+ \item \tdocenv*{tdocimp}
+ \item \tdocenv*{tdocnote}
+ \item \tdocenv*{tdoctip}
+ \item \tdocenv*{tdocwarn}
\end{enumerate}
\end{multicols}
\egroup
@@ -1351,6 +1423,6 @@
\tdocversion{1.0.0}[2023-11-29]
-Première version publique du projet.
+\tdocstartproj{Première version publique du projet.}
\end{document}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty 2024-09-29 20:39:18 UTC (rev 72404)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty 2024-09-29 20:39:29 UTC (rev 72405)
@@ -8,7 +8,7 @@
\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@caution at title}{}{Caution}
+\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}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty 2024-09-29 20:39:18 UTC (rev 72404)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty 2024-09-29 20:39:29 UTC (rev 72405)
@@ -8,7 +8,7 @@
\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@caution at title}{}{Mise ~ en ~ garde}
+\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}
Modified: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-09-29 20:39:18 UTC (rev 72404)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2024-09-29 20:39:29 UTC (rev 72405)
@@ -9,8 +9,8 @@
\ProvidesExplPackage
{tutodoc}
- {2024-09-25} % Creation: 2023-11-29
- {1.3.0}
+ {2024-09-28} % Creation: 2023-11-29
+ {1.4.0}
{This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
@@ -61,7 +61,8 @@
\RequirePackage{tcolorbox}%
[2024/07/10]
-\tcbuselibrary{breakable, skins}
+\tcbuselibrary{breakable,
+ skins}
\RequirePackage{clrstrip}%
@@ -68,8 +69,12 @@
[2021-08-28]
-\RequirePackage{minted2}% Temporary patch? minted3 seems very slow8
+%\RequirePackage[highlightmode = immediate]% Too slow!
+% {minted}%
+% [2024/09/22]
+\RequirePackage{minted2}% Temporary patch.
+
\RequirePackage{tcolorbox}%
[2024/07/10]
@@ -225,23 +230,37 @@
%%%
% prototype::
-% #1 : one color following the ''xcolor'' format.
+% #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}{m}{%
- #1!50!black%
-}
+\NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black}
%%%
% prototype::
-% #1 : one color following the ''xcolor'' format.
+% #1 : the transparency rate.
+% #2 : one color following the ''xcolor'' format.
%
% :return: a "transparent" version of the color `#1`.
%%%
-\NewExpandableDocumentCommand{\tdoclightcolor}{m}{%
- #1!5%
+\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%
}
@@ -295,77 +314,48 @@
% -- SOBER HIGHLIGHTING OF CONTENT -- %
% ----------------------------------- %
-% ::::::::::::::::::::::::::::::: %
-% :: EXAMPLE - HIDDEN VERSIONS :: %
-% ::::::::::::::::::::::::::::::: %
+% :::::::::::::::::::::: %
+% :: EXAMPLE - REMARK :: %
+% :::::::::::::::::::::: %
-%%%
-% See the \doc of the macro ''\newtheorem'' from the package ''amsthm''
-% to have \infos about the environment ''@@tdocexa at nb''.
-%%%
-\newtheorem{@@tdocexa at nb}{\tutodoc at trans@exa at title}%
- [subsubsection]
+\ExplSyntaxOn
%%%
-% We redefine the counter associated to the environment ''@@tdocexa at nb''
-% to obtain only one single arabic number.
+% We use a ''seq'' variable to factorize the code just after.
%%%
-\renewcommand{\the@@tdocexa at nb}{\arabic{@@tdocexa at nb}}
+\seq_new:N \__g_tutodoc_focus_sober_seq
+\seq_set_from_clist:Nn \__g_tutodoc_focus_sober_seq {
+ exa,
+ rem
+}
%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''@@tdocexa at no@nb''.
+% 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.
%%%
-\newtheorem*{@@tdocexa at no@nb}{\tutodoc at trans@exa at title}
+\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,
+ ]
+ }
-
-% :::::::::::::::::::::::::::::: %
-% :: EXAMPLE - PUBLIC VERSION :: %
-% :::::::::::::::::::::::::::::: %
-
-\ExplSyntaxOn
-
-\msg_set:nnnn { tdoc } { env-tdocexa-unknown-option }
- { Unknown ~ rafters ~ option. }
- { See ~ the ~ documentation ~ for ~ the ~ supported ~ options. }
-
-\NewDocumentEnvironment{ tdocexa } { D<>{nb} O{} } {
- \str_case:nnF { #1 } {
- { nb } {
- \begin{@@tdocexa at nb}[#2]
- }
- { nonb } {
- \begin{@@tdocexa at no@nb}[#2]
- }
- }{
- \msg_error:nn { tdoc } { env-tdocexa-unknown-option }
- }
-}{
- \str_case:nnF { #1 } {
- { nb } {
- \end{@@tdocexa at nb}
- }
- { nonb } {
- \end{@@tdocexa at no@nb}
- }
- }{}
+ \cs_set:cpn { the tdoc #1 } { \thesection\arabic{tdoc#1} }
}
\ExplSyntaxOff
-% :::::::::::: %
-% :: REMARK :: %
-% :::::::::::: %
-
-%%%
-% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
-% to have \infos about the environment ''tdocrem''.
-%%%
-\newtheorem*{tdocrem}{\tutodoc at trans@rem at title}
-
-
% -------------------------------------- %
% -- COLORFUL HIGHLIGHTING OF CONTENT -- %
% -------------------------------------- %
@@ -374,16 +364,18 @@
% :: ABSTRACTION :: %
% ::::::::::::::::: %
-% Sources used.
-% + https://tex.stackexchange.com/a/727022/6880
-% + https://tex.stackexchange.com/a/682332/6880
-
+%%%
+% 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,
-% fonttitle = \itshape,
-% halign title = center,
+ left = 3pt,
+ right = 3pt,
fontupper = \color{\tdocdarkcolor{#1}},
colback = \tdoclightcolor{#1},
colframe = #1!75!black!45,
@@ -400,22 +392,34 @@
\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,%lime,
- imp = orange,
- caution = violet,
- warn = red,
+ 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,
- caution = \faBiohazard,
- warn = \faSkullCrossbones,
+ 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,
@@ -422,7 +426,7 @@
% tcolorbox-no-titlebar can be used.
tcolorbox = {tutodoc-focus-color-style=#2},
name = {
- \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } \kern3.5pt
+ \tdocicon{ \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } }
\use:c { tutodoc at trans@#1 at title }
},
]
@@ -473,16 +477,32 @@
% #1 : hard typed options with the good delimiters
% #2 : the name of an environment
%
-% :action: ''\tdocenv{myenv}'' prints verb::''\begin{myenv} ... \end{myenv}''
-% or something like verb::''\begin{myenv}<opt1> ... \end{myenv}'',
-% the spaces being secable.
+% :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}{O{}m}{%
- \texttt{\string\begin\string{#2\string}#1 %
- \!\!...\@\!\!\! %
- \string\end\string{#2\string}}%
+\NewDocumentCommand{\tdocenv}{s O{} m}{%
+ \IfBooleanTF{#1}{%
+ \texttt{#3}%
+ }{%
+ \texttt{\string\begin\string{#3\string}#2 %
+ \!\!...\@\!\!\! %
+ \string\end\string{#3\string}}%
+ }%
}
@@ -771,6 +791,11 @@
\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.
@@ -854,7 +879,7 @@
%%%
% prototype::
-% #1 : :see: \newtcblisting{tdoclatex}.
+% #1 : :see: ''\newtcblisting{tdoclatex}'' just before.
% #2 : the path of the file to input and format.
%
% note::
@@ -964,7 +989,7 @@
\IfBlankTF{#2}{}{
\par
- #2
+ #2\vphantom{Mp}
\par
}
@@ -974,7 +999,7 @@
}
\par
- \__tdoc_translate_date:n { #3 }
+ \__tdoc_translate_date:n { #3 }\vphantom{Mp}
\par
}
@@ -1086,6 +1111,8 @@
%%%
% 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).
@@ -1093,10 +1120,9 @@
\NewDocumentEnvironment{tdoctopic}{ m O{} }{
\IfBlankT{#1}{
\msg_fatal:nn { tdoc } { changes-topic-missing-title }
- }
-
- \textbf{
- \IfBlankF{#2}{#2\kern3.5pt}%
+ }%
+ \textbf{%
+ \IfBlankF{#2}{\tdocicon{#2}}%
\textsc{#1.}
}
@@ -1110,6 +1136,10 @@
% :: 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,
@@ -1123,8 +1153,9 @@
% prototype::
% :see: env.tdoctopic
%
-% :action: similar to the \env ''tdoctopic'' with the title "New"
-% translated into the good language.
+% :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 } {} {
@@ -1134,6 +1165,17 @@
}
}
+
+%%%
+% 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
@@ -1157,12 +1199,3 @@
\medskip
\smallskip
}
-
-
-%%%
-% prototype::
-% :action: this macro adds a tiny vertical spacing.
-%%%
-\NewDocumentCommand{\tdocxspace}{}{
- \vspace{0.25em}
-}
More information about the tex-live-commits
mailing list.