diff options
author | Karl Berry <karl@freefriends.org> | 2024-12-19 20:43:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2024-12-19 20:43:00 +0000 |
commit | a47f291a6bc4c6be9842aba48b7b2977691e3647 (patch) | |
tree | 0d445b7e57b44d2d01a9c398400bfe5045c201d9 /Master | |
parent | 5b9a20a8dddd55bbdc88b0e1562a80a1b74ebae2 (diff) |
tutodoc (19dec24)
git-svn-id: svn://tug.org/texlive/trunk@73166 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r-- | Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf | bin | 1141519 -> 1156350 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex | 1688 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf | bin | 1178379 -> 1225193 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex | 1586 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/DEPENDS.yaml | 27 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/tutodoc-bw.css.cls | 155 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/tutodoc-color.css.cls | 163 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/tutodoc-dark.css.cls | 161 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/tutodoc-draft.css.cls | 151 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls | 841 |
10 files changed, 3100 insertions, 1672 deletions
diff --git a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf Binary files differindex 531e5711e4d..1c9eadd9317 100644 --- a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf +++ b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf diff --git a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex index de0b4f1732b..2f9cecbafd1 100644 --- a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex +++ b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex @@ -6,23 +6,34 @@ \begin{filecontents*}[overwrite]{gallery-showcase-bw.tex} \documentclass[theme = bw]{tutodoc} -% -- FORDOC -- % - \usepackage{multicol} +\usepackage{lastpage} + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{\thepage\kern1pt/\kern1pt\pageref*{LastPage}}% +} + \newcommand\thisstyle{bw} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] - In the flow of the text, it is always useful to be able to indicate examples and comments to supplement the main content. + In the flow of the text, it is always useful to be able to provide examples and comments to supplement the main content. } + \newcommand\myadmotext{ Depending on the context of use, it is sometimes necessary to be able to highlight content by indicating its degree of importance. } +\newcommand\myhighlightedtextnonote{ + What to say? + I don't know, but it's nice. No ? +} + \newcommand\myhighlightedtext{ - What to say + What to say\,% \footnote{ Let's not forget the footnotes... }? @@ -30,19 +41,48 @@ } +\newcommand\mychgestext{ + In a change log, it is important to visualise the types of changes clearly. This makes it easier for the user to read! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} -\textsf{\Huge\bfseries The theme \texttt{"\thisstyle"}} +\textsf{\Huge\bfseries The \texttt{"\thisstyle"} theme} + +\section{Liens} + +{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very big link}}, but at least we can see it. -\section{Links} -{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very large link}}, but at least you can see it. +\section{\LaTeX\ listings} +Typing inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is showing use cases such as the following one. + +\begin{tdoclatex} +Formatted \LaTeX\ code is great: $E = m c^2$ or $pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +There's also a less invasive side-by-side mode. Nice! No ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Formatted \LaTeX\ code is great: \\ +$E = m c^2$ or $\pi \neq \frac{3}{14}$. +\end{tdoclatex} -\section{Highlight, version and date} + +\section{Highlighting, versioning and dating} \subsection{tdocexa, tdocrem} @@ -58,7 +98,6 @@ \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -67,20 +106,28 @@ \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -88,47 +135,68 @@ \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{New demo section...} +\tdocstartproj{A new demonstration section...} -\medskip +\begin{tdoctodo} + \item A gallery would be welcome... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{LaTeX codes} - -Typing an inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is demonstrating use cases such as the following one. - -\begin{tdoclatex} -Seeing \LaTeX\ code formatted is nice: $E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -There's also a less intrusive side-by-side mode. Nice! No ? - -\begin{tdoclatex}[sbs] -Seeing \LaTeX\ code formatted is nice: \\ -$E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -136,23 +204,34 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \begin{filecontents*}[overwrite]{gallery-showcase-color.tex} \documentclass[theme = color]{tutodoc} -% -- FORDOC -- % - \usepackage{multicol} +\usepackage{lastpage} + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{\thepage\kern1pt/\kern1pt\pageref*{LastPage}}% +} + \newcommand\thisstyle{color} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] - In the flow of the text, it is always useful to be able to indicate examples and comments to supplement the main content. + In the flow of the text, it is always useful to be able to provide examples and comments to supplement the main content. } + \newcommand\myadmotext{ Depending on the context of use, it is sometimes necessary to be able to highlight content by indicating its degree of importance. } +\newcommand\myhighlightedtextnonote{ + What to say? + I don't know, but it's nice. No ? +} + \newcommand\myhighlightedtext{ - What to say + What to say\,% \footnote{ Let's not forget the footnotes... }? @@ -160,19 +239,48 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + In a change log, it is important to visualise the types of changes clearly. This makes it easier for the user to read! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} -\textsf{\Huge\bfseries The theme \texttt{"\thisstyle"}} +\textsf{\Huge\bfseries The \texttt{"\thisstyle"} theme} + +\section{Liens} + +{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very big link}}, but at least we can see it. -\section{Links} -{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very large link}}, but at least you can see it. +\section{\LaTeX\ listings} +Typing inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is showing use cases such as the following one. +\begin{tdoclatex} +Formatted \LaTeX\ code is great: $E = m c^2$ or $pi \neq \frac{3}{14}$. +\end{tdoclatex} -\section{Highlight, version and date} + +There's also a less invasive side-by-side mode. Nice! No ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Formatted \LaTeX\ code is great: \\ +$E = m c^2$ or $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + +\section{Highlighting, versioning and dating} \subsection{tdocexa, tdocrem} @@ -188,7 +296,6 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -197,20 +304,28 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -218,47 +333,68 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{New demo section...} +\tdocstartproj{A new demonstration section...} -\medskip +\begin{tdoctodo} + \item A gallery would be welcome... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{LaTeX codes} - -Typing an inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is demonstrating use cases such as the following one. - -\begin{tdoclatex} -Seeing \LaTeX\ code formatted is nice: $E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -There's also a less intrusive side-by-side mode. Nice! No ? - -\begin{tdoclatex}[sbs] -Seeing \LaTeX\ code formatted is nice: \\ -$E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -266,23 +402,34 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \begin{filecontents*}[overwrite]{gallery-showcase-dark.tex} \documentclass[theme = dark]{tutodoc} -% -- FORDOC -- % - \usepackage{multicol} +\usepackage{lastpage} + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{\thepage\kern1pt/\kern1pt\pageref*{LastPage}}% +} + \newcommand\thisstyle{dark} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] - In the flow of the text, it is always useful to be able to indicate examples and comments to supplement the main content. + In the flow of the text, it is always useful to be able to provide examples and comments to supplement the main content. } + \newcommand\myadmotext{ Depending on the context of use, it is sometimes necessary to be able to highlight content by indicating its degree of importance. } +\newcommand\myhighlightedtextnonote{ + What to say? + I don't know, but it's nice. No ? +} + \newcommand\myhighlightedtext{ - What to say + What to say\,% \footnote{ Let's not forget the footnotes... }? @@ -290,19 +437,48 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + In a change log, it is important to visualise the types of changes clearly. This makes it easier for the user to read! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} -\textsf{\Huge\bfseries The theme \texttt{"\thisstyle"}} +\textsf{\Huge\bfseries The \texttt{"\thisstyle"} theme} + +\section{Liens} + +{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very big link}}, but at least we can see it. + + +\section{\LaTeX\ listings} -\section{Links} +Typing inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is showing use cases such as the following one. -{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very large link}}, but at least you can see it. +\begin{tdoclatex} +Formatted \LaTeX\ code is great: $E = m c^2$ or $pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +There's also a less invasive side-by-side mode. Nice! No ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Formatted \LaTeX\ code is great: \\ +$E = m c^2$ or $\pi \neq \frac{3}{14}$. +\end{tdoclatex} -\section{Highlight, version and date} +\section{Highlighting, versioning and dating} \subsection{tdocexa, tdocrem} @@ -318,7 +494,6 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -327,20 +502,28 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -348,47 +531,68 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{New demo section...} +\tdocstartproj{A new demonstration section...} -\medskip +\begin{tdoctodo} + \item A gallery would be welcome... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{LaTeX codes} - -Typing an inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is demonstrating use cases such as the following one. - -\begin{tdoclatex} -Seeing \LaTeX\ code formatted is nice: $E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -There's also a less intrusive side-by-side mode. Nice! No ? - -\begin{tdoclatex}[sbs] -Seeing \LaTeX\ code formatted is nice: \\ -$E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -396,23 +600,34 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \begin{filecontents*}[overwrite]{gallery-showcase-draft.tex} \documentclass[theme = draft]{tutodoc} -% -- FORDOC -- % - \usepackage{multicol} +\usepackage{lastpage} + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{\thepage\kern1pt/\kern1pt\pageref*{LastPage}}% +} + \newcommand\thisstyle{draft} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] - In the flow of the text, it is always useful to be able to indicate examples and comments to supplement the main content. + In the flow of the text, it is always useful to be able to provide examples and comments to supplement the main content. } + \newcommand\myadmotext{ Depending on the context of use, it is sometimes necessary to be able to highlight content by indicating its degree of importance. } +\newcommand\myhighlightedtextnonote{ + What to say? + I don't know, but it's nice. No ? +} + \newcommand\myhighlightedtext{ - What to say + What to say\,% \footnote{ Let's not forget the footnotes... }? @@ -420,19 +635,48 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + In a change log, it is important to visualise the types of changes clearly. This makes it easier for the user to read! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} -\textsf{\Huge\bfseries The theme \texttt{"\thisstyle"}} +\textsf{\Huge\bfseries The \texttt{"\thisstyle"} theme} +\section{Liens} -\section{Links} +{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very big link}}, but at least we can see it. -{\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{A very large link}}, but at least you can see it. +\section{\LaTeX\ listings} -\section{Highlight, version and date} +Typing inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is showing use cases such as the following one. + +\begin{tdoclatex} +Formatted \LaTeX\ code is great: $E = m c^2$ or $pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +There's also a less invasive side-by-side mode. Nice! No ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Formatted \LaTeX\ code is great: \\ +$E = m c^2$ or $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + +\section{Highlighting, versioning and dating} \subsection{tdocexa, tdocrem} @@ -448,7 +692,6 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -457,20 +700,28 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -478,47 +729,68 @@ $E = m c^2$ or $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{New demo section...} +\tdocstartproj{A new demonstration section...} -\medskip +\begin{tdoctodo} + \item A gallery would be welcome... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{LaTeX codes} - -Typing an inline code such as \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} is useful, as is demonstrating use cases such as the following one. - -\begin{tdoclatex} -Seeing \LaTeX\ code formatted is nice: $E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -There's also a less intrusive side-by-side mode. Nice! No ? - -\begin{tdoclatex}[sbs] -Seeing \LaTeX\ code formatted is nice: \\ -$E = m c^2$ or $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -587,7 +859,7 @@ Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu... \tdocversion[red]{10.2.0-beta}[2023-12-01] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... -\bigskip % CAUTION! This prevents overlapping. +\smallskip\bigskip % CAUTION! This prevents overlapping. \tdocversion{10.2.0-alpha} Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, @@ -650,9 +922,9 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \begin{filecontents*}[overwrite]{examples-version-n-change-manual-setting.tex} -This is what it looks like without vertical movement. +This is what it looks like without vertical shift. -\paragraph{A home-made setting}% +\paragraph{A home-made setting.}% \tdocversion{1.2.3}[2024-10-29]<0pt> Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... @@ -710,7 +982,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... Important and harmless. \end{tdocimp} -\begin{tdocimp}[Mini title] +\begin{tdocimp}[Small title] Useful? \end{tdocimp} \end{filecontents*} @@ -721,7 +993,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... Something useful to tell you... \end{tdocnote} -\begin{tdocnote}[Mini title] +\begin{tdocnote}[Small title] Useful? \end{tdocnote} \end{filecontents*} @@ -732,7 +1004,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... Caution, caution... \end{tdoccaut} -\begin{tdoccaut}[Mini title] +\begin{tdoccaut}[Small title] Useful? \end{tdoccaut} \end{filecontents*} @@ -743,7 +1015,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... A tip. \end{tdoctip} -\begin{tdoctip}[Mini title] +\begin{tdoctip}[Small title] Useful? \end{tdoctip} \end{filecontents*} @@ -754,7 +1026,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... Avoid the dangers... \end{tdocwarn} -\begin{tdocwarn}[Mini title] +\begin{tdocwarn}[Small title] Useful? \end{tdocwarn} \end{filecontents*} @@ -765,7 +1037,7 @@ Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... An example... \end{tdocexa} -\begin{tdocexa}[Mini title] +\begin{tdocexa}[Small title] Useful? \end{tdocexa} \end{filecontents*} @@ -797,72 +1069,134 @@ VERSUS. Another? \end{tdocrem} -\begin{tdocrem}[Mini title] +\begin{tdocrem}[Small title] Useful? \end{tdocrem} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-latexshow-options.tex} -\tdoclatexshow[explain = What comes next is colorful..., - before = Rendering below., - after = Finished rendering., - col-stripe = orange, - col-text = blue!70!black] - {examples-listing-xyz.tex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you.tex} +\NewDocumentCommand{\helloyou}{m}{% + \IfBlankTF{#1}{% + Ah, not very chatty today! + }{% + Hello #1. + + Amazing! Actually, not at all...% + }% +} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-ABC.tex} -\begin{tdoclatex}[sbs] - $A = B + C$ -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-input-hello-you-hs.tex} +\tdoccodeinput{hs}{examples-listing-full-hello-you.hs} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-xyz.tex} -% Just one demo. -$x y z = 1$ +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you.hs} +main :: IO () + +main = do + putStr "Who are you? " + name <- getLine + + if name == "" + then putStrLn "Ah, not very chatty today!" + + else do + putStrLn ("Hello " ++ name ++ ".") + putStrLn "Amazing! Actually, not at all..." \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-strange.tex} -\begin{tdoclatex}[std] - [Strange... Or not!] -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you-lua.tex} +\begin{tdoccode}[style = solarized-light, linenos]% + <leftrule = 22pt, colback = orange!5, colframe = red!35>% + {lua} +io.write("Who are you?") +local name = io.read() + +if name == "" then + print("Ah, not very chatty today!") + +else + print("Hello “ .. name .. ”.") + print("Amazing! Actually, not at all...") +end +\end{tdoccode} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex} -\begin{tdoclatex} - \string[Strange... Or not!] -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you-perl.tex} +\begin{tdoccode}{pl} +print "Who are you? "; +my $name = <STDIN>; + +chomp($name); + +if ($name eq "") { + print "Ah, not very chatty today!"; + +} else { + print "Hello $name"; + print "Amazing! Actually, not at all..."; +} +\end{tdoccode} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-customized.tex} -\begin{tdocshowcase}[before = My beginning, - after = My end, - col-stripe = red, - col-text = orange!75!black] - Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... -\end{tdocshowcase} +\begin{filecontents*}[overwrite]{examples-listing-full-input-hello-you-tex.tex} +\tdoccodeinput[style = solarized-light, linenos]% + <leftrule = 22pt, colback = orange!5, colframe = red!35>% + {tex}{examples-listing-full-hello-you.tex} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-showcase-hook.tex} +\begin{tdocshowcase}[] + [This works...] +\end{tdocshowcase} + +OR. + \begin{tdocshowcase} - \string[This works...] + \string[This also works...] \end{tdocshowcase} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-nostripe-customized.tex} -\begin{tdocshowcase}[nostripe, - before = My beginning, - after = My end, +\begin{filecontents*}[overwrite]{examples-showcase-rule.tex} +\begin{tdocshowcase}[style = rule] + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... +\end{tdocshowcase} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-stripe-custom.tex} +\begin{tdocshowcase}[style = stripe, col-stripe = green, - col-text = purple] + col-text = purple, + before = Mon début, + after = Ma fin à moi] + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... +\end{tdocshowcase} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-input-stripe.tex} +\tdocshowcaseinput[style = stripe, + col-stripe = red, + col-text = LightCoral]% + {examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-rule-custom.tex} +\begin{tdocshowcase}[style = rule, + col-stripe = red, + col-text = orange!75!black, + before = My beginning, + after = My end] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} \end{filecontents*} @@ -884,13 +1218,106 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-nostripe.tex} -\begin{tdocshowcase}[nostripe] +\begin{filecontents*}[overwrite]{examples-showcase-stripe.tex} +\begin{tdocshowcase}[style = stripe] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-showcase-input-default.tex} +\tdocshowcaseinput{examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-input-rule.tex} +\tdocshowcaseinput[style = rule]{examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexshow-options.tex} +\tdoclatexshow[style = stripe, + col-stripe = orange, + col-text = blue!70!black, + before = Rendering hereafter., + explain = What comes next is coloured..., + after = Finished rendering.,] + {examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-ABC.tex} +\begin{tdoclatex}<\tdoctcb{sbs}> +$A = B + C$ +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-xyz.tex} +% Just one demo. +$x y z = 1$ +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-std.tex} +\tdoclatexinput{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-strange.tex} +\begin{tdoclatex}[] +[Strange... Or not!] +\end{tdoclatex} +OR. +\begin{tdoclatex}<> +<Strange... Or not!> +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-ABC-custom.tex} +\begin{tdoclatex}% + [linenos, style = igor, showspaces]% + <\tdoctcb{sbs}, + attach boxed title to top left = {yshift = -9pt}, + fonttitle = \bfseries, + title = Local modifications, + top = 10pt> +% Sometimes useful, but don't overuse it! +$A = B + C$ +% End of this demonstration. +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-sbs.tex} +\tdoclatexinput<\tdoctcb{sbs}>{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-code.tex} +\tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-perso.tex} +\tdoclatexinput[style = igor, showspaces]% + <colframe = purple, colback = red!5>% + {examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-strange-bis.tex} +\begin{tdoclatex} +\string[Strange... Or not!] +\end{tdoclatex} +OR. +\begin{tdoclatex} +\string<Strange... Or not!> +\end{tdoclatex} +\end{filecontents*} + + % ======================== % % == SOURCE FOR THE DOC == % % ======================== % @@ -909,6 +1336,10 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \usepackage{tasks} \usepackage{pdfpages} +\includepdfset{ + pages=-, + fitpaper=true +} \setlength{\parindent}{0em} @@ -923,72 +1354,14 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \newcommand\git{\trademark{git}} \newcommand\pdf{\trademark{PDF}} +\newcommand\brainfuck{\trademark{Brainfuck}} +\newcommand\lua{\trademark{Lua}} +\newcommand\perl{\trademark{Perl}} +\newcommand\python{\trademark{Python}} -% --------------- % -% -- IMPORTANT -- % -% --------------- % -% -% See the French version of this file for the text to be used -% for languages other than English. - - -% --------------- % -% -- IMPORTANT -- % -% --------------- % -% -% See the French version of this file for the text to be used -% for languages other than English. +\newcommand\pygmentsREF{\href{https://pygments.org/}{\trademark{Pygments}}} -% == FORDOC == % - -% Source. -% * https://tex.stackexchange.com/a/604698/6880 - -\NewDocumentCommand{ \tdocbasicinputDOC }{ m }{% - Consider the following code. - - \tdoclatexinput[code]{#1} - - This will produce the following. - - \input{#1} -} - - -% == FORDOC == % - -% Source. -% * https://tex.stackexchange.com/a/604698/6880 - -\NewDocumentCommand{ \tdocextrarulerDOC }{ m }{% - \par - { - \centering - \color{green!50!black}% - \leavevmode - \kern.075\linewidth - \leaders\hrule height3.25pt\hfill\kern0pt - \footnotesize\itshape\bfseries\space\ignorespaces#1\unskip\space - \leaders\hrule height3.25pt\hfill\kern0pt - \kern.075\linewidth - \par - } -} - -\NewDocumentEnvironment{ tdocshowcaseDOC } - { O{ Start of the rendering in this doc. } - O{ End of rendering in this doc. } }{ - \tdocextrarulerDOC{#1} - \nopagebreak\smallskip\nopagebreak -}{ - \nopagebreak\smallskip\nopagebreak - \tdocextrarulerDOC{#2} -} - - -% == FORDOC == % - \NewDocumentCommand{\mailsubject}{m}% <-- Translate me! {subject \tdocquote{\texttt{tutodoc - CONTRIB - #1}}} @@ -1059,7 +1432,7 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \title{The \texttt{tutodoc} class \\ Tutorial-style documentation} \author{Christophe, BAL} -\date{Dec 4, 2024 - Version 1.7.0} +\date{Dec 18, 2024 - Version 1.7.1} \maketitle @@ -1070,9 +1443,9 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... } 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. + The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected for a coding documentation. } - using a sober rendering for reading on screen. + with a sober rendering for reading on screen. \smallskip @@ -1092,66 +1465,52 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \small -\begin{tdocbreak} - \item Format: the \tdoccls{scrartcl} class replaces the venerable \tdoccls{article}. This implies better placement of the margin notes with the options retained for loading \tdoccls{scrartcl}. - - \item \LaTeX\ code: the macro \tdocmacro{tdocinlatex} has been renamed \tdocmacro{tdoclatexin}. +\begin{tdocfix} + \item Documentation: references to tools to indicate changes have been incorrectly written as characteristics of highlighted colored content. +\end{tdocfix} - \item Color key names will be hyphenated where necessary: this implies the following changes. - % - \begin{enumerate} - \item Admonitions: the \tdoclatexin{colchges} option of the environments has been renamed \tdoclatexin{col-chges}. - \item Showcases: for the environment \tdocenv*{tdocshowcase} and the macro \tdocmacro{tdocshowcaseinput}, the \tdoclatexin{colstripe} and \tdoclatexin{coltext} options have been renamed \tdoclatexin{col-stripe} and \tdoclatexin{col-text}\,. - \end{enumerate} +\begin{tdocbreak} + \item The \tdocmacro{tdocenv} macro and its starred version no longer offer an option. + + \item \LaTeX\ showcases: the default layout is more sober, and there are options for having just the rulers, or the colored stripe. See just after. \end{tdocbreak} -\begin{tdocfix} - \item Admonitions: for the \tdocmacro{newkeytheorem} used with the \tdoclatexin{draft} theme, \tdoclatexin{postheadhook = \leavevmode} has been added (this is necessary because the content can naturally be of the list type). -\end{tdocfix} - - \begin{tdocnew} - \item Documentation: addition of a section listing dependencies. - - \item Class options. + \item Formatting of computer codes in addition to those specifically in \LaTeX. % \begin{enumerate} - \item Options not specific to \thisproj\ are passed on to the class in charge of general formatting. - - \item The \tdoccls{scrartcl} options \tdoclatexin{fontsize} and \tdoclatexin{DIV} can't be used because their values are fixed by \thisproj. - \end{enumerate} + \item Creation of \tdocenv{tdoccode} and \tdocmacro{tdoccodein}. - \item The macro \tdocmacro{tdocinEN} respects the English linguistic rules. + \item For macros for inline code, and environments for blocks of code, \tdocpack{minted} options are indicated inside square brackets in the traditional way: \tdoclatexin{[minted options]}\,. - \item Admonitions. - % - \begin{enumerate} - \item A new environment \tdocenv{tdoctodo} has been added. + \item For code block environments, \tdocpack{tcolorbox} options are indicated inside rafters: \tdoclatexin{<tcolorbox options>}\,. - \item Each environment has a new option \tdoclatexin{col} for the color of the content indicating changes. + \item The new macro \tdocmacro{tdoctcb} allows to use shortcuts for regularly used \tdocpack{tcolorbox} styles. \end{enumerate} + + \item Documentation: a new section presents tools for formatting computer codes other than those in \LaTeX. \end{tdocnew} \begin{tdocupdate} - \item \tdoclatexin{draft} theme and changes: the environments for the kind of changes stop to use icons. + \item Sub-sub-sections are numbered in lower case. - \item Documentation: the theme gallery uses a better fake example. -\end{tdocupdate} + \item Themes. + % + \begin{enumerate} + \item Less space consumed. + \item Shadows have better coloring. + \item For all themes except the \tdoclatexin{draft} one, the radius of the arcs of the corners of the frames has changed from \tdoclatexin{.75mm} to \tdoclatexin{.2pt},. -\begin{tdoctech} - \item Simplified organisation of configuration files in the final project. - % - \begin{enumerate} - \item \texttt{CSS}-like: use of one file per theme with a name like \texttt{tutodoc-bw.css.cls}\,. + \item Use case in \LaTeX: with the theme \tdoclatexin{color}, the background color changes from \tdoclatexin[bgcolor = yellow!4]{yellow!4} to \tdoclatexin{gray!5}. - \item Locale: use of names like \texttt{tutodoc-en.loc.cls}\,. + \item Latest changes: with the \tdoclatexin{dark} theme, the \tdoclatexin{[Init]} text produced by the \tdocmacro{tdocstartproj} macro uses the same font as the environment titles to indicate changes. \end{enumerate} -\end{tdoctech} +\end{tdocupdate} } @@ -1200,7 +1559,7 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{tasks} -\section{General formatting imposed} +\section{General settings} \subsection{Font size and page geometry} @@ -1208,7 +1567,7 @@ The \tdoccls{scrartcl} class is loaded via the \tdoclatexin{fontsize = 10pt} opt \begin{tdocwarn} - The macros for dating and versioning presented in the \ref{tutodoc-changes} section require fixed settings for page geometry and font size. + The macros for dating and versioning presented in the section \ref{tutodoc-changes} on page \pageref{tutodoc-changes} require fixed settings for page geometry and font size. \end{tdocwarn} @@ -1219,7 +1578,7 @@ The selected settings are directly visible in this documentation. \subsection{Dynamic links} -The \tdocpack{hyperref} package is imported, if it hasn't already been, and the settings chosen are just for the colors of links relating to citations, files, internal links, and finally \verb#url# (this color will depend on the theme chosen). +The \tdocpack{hyperref} package is imported, if it hasn't already been, and the settings chosen are just for the colors of links relating to citations, files, internal links, and finally \verb#url# (this colors will depend on the theme chosen). \section{What language is used by the \thisproj\ class?} @@ -1230,13 +1589,11 @@ On the other hand, the \thisproj\ class identifies \tdoclatexin|en| as the main Technically, we use \tdoclatexin|\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{tasks}[label=\small\textbullet](3) \task \tdoclatexin|en| : English. \task \tdoclatexin|es| : Spanish. \task \tdoclatexin|fr| : French. \end{tasks} - \begin{tdocnote} @@ -1264,7 +1621,7 @@ Cool and top stand for \tdocinEN*{cool} and \tdocinEN{top}. \end{tdoclatex} -The macro \tdocmacro{tdocinEN} and its starred version are based on \tdocmacro{tdocquote} : for example, \tdocquote{semantic} is obtained via \tdoclatexin|tdocquote{semantic}| . +The macro \tdocmacro{tdocinEN} and its starred version are based on \tdocmacro{tdocquote} : for example, \tdocquote{semantic} is obtained via \tdoclatexin|tdocquote{semantic}|\,. \begin{tdocnote} @@ -1281,7 +1638,7 @@ To modify the general layout, there is the \thisproj\ class option \tdoclatexin{ a black-and-white theme with some shades of grey. \task \tdoclatexin{color}: - a coloured theme : this is the default value. + a colored theme, this is the default value. \task \tdoclatexin{dark}: a dark theme ideal for resting the eyes. @@ -1318,10 +1675,10 @@ To modify the general layout, there is the \thisproj\ class option \tdoclatexin{ \addcontentsline{toc}{section}{Appendix -- Theme gallery}% \egroup -\bigskip +\bigskip\bigskip \begin{tdocnote} - Each example is exactly a two pages long \pdf\ and has been inserted directly into this document (so don't be surprised by the page numbers). + Each example is a \pdf\ directly inserted into this document (so don't be surprised by the page numbers). \end{tdocnote} \newpage @@ -1336,25 +1693,13 @@ To modify the general layout, there is the \thisproj\ class option \tdoclatexin{ \immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-draft} % The gallery starts here... -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-bw} +\includepdf{gallery-showcase-bw} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-color} +\includepdf{gallery-showcase-color} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-dark} +\includepdf{gallery-showcase-dark} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-draft} +\includepdf{gallery-showcase-draft} } @@ -1365,7 +1710,7 @@ To modify the general layout, there is the \thisproj\ class option \tdoclatexin{ \section{Highlighting content} \begin{tdocnote} - The environments presented in this section + The environments presented in this section\,% \footnote{ The formatting comes from the \tdocpack{keytheorems} package. } @@ -1377,35 +1722,24 @@ To modify the general layout, there is the \thisproj\ class option \tdoclatexin{ \subsection{Content in the reading flow} -% ------------------ % - - \begin{tdocimp} - All the environments presented in this section share the same counter, which will be reset to zero as soon as a section with a level at least equal to a \tdoclatexin|\section| is opened. + All the environments presented in this section share the same counter, which will be reset to zero as soon \tdoclatexin|\section| is used. \end{tdocimp} -% ------------------ % - - \subsubsection{Examples} -Numbered examples, if required, are indicated via \tdocenv{tdocexa}, which offers an optional argument for adding a mini-title. +Numbered examples are indicated via \tdocenv{tdocexa}, which offers an optional argument for adding a small title. Here are two possible uses. -\tdoclatexinput[sbs]{examples-admonitions-exa.tex} - - - -% ------------------ % +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-exa.tex} \begin{tdoctip} It can sometimes be useful to return to the line at the start of the content. The code below shows how to proceed (this trick also applies to the \verb#tdocrem# environment presented next). Note in passing that the numbering follows that of the previous example as desired. \end{tdoctip} -\tdoclatexinput[sbs]{examples-admonitions-exa-leavevmode.tex} - +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-exa-leavevmode.tex} % \subsection{Content in the reading flow} @@ -1414,8 +1748,7 @@ Here are two possible uses. Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocenv*{tdocexa} environment, as shown in the following example. -\tdoclatexinput[sbs]{examples-admonitions-rmk.tex} - +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-rmk.tex} \subsection{Flashy content} @@ -1423,7 +1756,7 @@ Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocen \begin{tdocnote} The formatting proposed here is the default one, but others are possible by changing the theme: see the gallery of use cases in the appendix page \pageref{tutodoc-theme-gallery}. - As for the icons, they are obtained via the \tdocpack{fontawesome5} package, and the \tdocmacro{tdocicon} macro manages the spacing in relation to the text. + As for the icons, they are obtained via the \tdocpack{fontawesome5} package, and the \tdocmacro{tdocicon} macro which manages the spacing relatively to the text.% \footnote{ For example, \tdoclatexin|\fbox{tdocicon{faBed}{Fatigued}}| @@ -1437,18 +1770,16 @@ Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocen The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it. -\tdoclatexinput[sbs]{examples-admonitions-tip.tex} - +\tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-tip.tex} \smallskip \begin{tdoctip} - Sometimes, highlighted content can be reduced to a list. In this case, the formatting can be improved as follows where we use the \tdoclatexin{wide} option from the \tdocpack{enumitem} package. - - \tdoclatexinput[sbs]{examples-admonitions-leavevmode-items.tex} + Sometimes, highlighted content can be reduced to a list. In this case, the formatting can be improved as follows where we use the \tdoclatexin{wide} option from the \tdocpack{enumitem} package imported by this documentation. + \tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-leavevmode-items.tex} \end{tdoctip} @@ -1473,8 +1804,7 @@ The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it. \desc - \tdoclatexinput[sbs]{examples-admonitions-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-\filename.tex} } @@ -1483,40 +1813,27 @@ The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it. Here's what you can type semantically. -\begin{tdoclatex}[sbs] -\tdoccls{myclass} is for... \\ -\tdocpack{mypackage} is for... \\ -\tdocmacro{onemacro} is for... \\ -\tdocenv{env} produces... \\ -\tdocenv[{[opt1]<opt2>}]{env} \\ -Just \tdocenv*{env}... \\ -Finally \tdocenv*[{[opt1]<opt2>}]{env}... - % For copy and paste. +\begin{tdoclatex}<\tdoctcb{sbs}> +\tdoccls{myclass} is for... \\ +\tdocpack{mypackage} is for... \\ +\tdocmacro{onemacro} is for... \\ +\tdocenv{env} produces... \\ +Just \tdocenv*{env}... \end{tdoclatex} \begin{tdocrem} - Unlike \tdocmacro{tdoclatexin}, \tdocmacro{tdocenv} and \tdocmacro{tdocenv*} macros don't color the text they produce. - In addition, \tdoclatexin{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if required. + Unlike \tdocmacro{tdoclatexin}, the \tdocmacro{tdocmacro}, \tdocmacro{tdocenv} and \tdocmacro{tdocenv*} macros don't color the text they produce. + In addition, \tdoclatexin{\tdocenv{monenv}} produces \tdocenv{monenv} with breakable spaces to allow line breaks if required. \end{tdocrem} -\begin{tdocwarn} - The optional argument of the \tdocmacro{tdocenv} macro is copied and pasted - \footnote{ - Remember that almost anything is possible from now on. - } - when rendering. This may sometimes require the use of protective braces, as in the example above. -\end{tdocwarn} - - - \section{Origin of a prefix or suffix} To explain the names chosen, there is nothing like indicating and explaining the short prefixes and suffixes used. This is easily done as follows. -\begin{tdoclatex}[sbs] +\begin{tdoclatex}<\tdoctcb{sbs}> \tdocpre{sup} relates to... \\ \tdocprewhy{sup.erbe} means... \\ \emph{\tdocprewhy{sup.er} for...} @@ -1531,250 +1848,237 @@ To explain the names chosen, there is nothing like indicating and explaining the \section{A real-life rendering} \label{tutodoc-showcase} -It is sometimes useful to render code directly in the documentation. This type of rendering must be dissociable from the explanatory text. +It is sometimes useful to render code directly in the documentation. This requires the rendering to be dissociable from the explanatory text. -\subsection{With a colored stripe} +\subsection{A minimalist rendering by default} -\begin{tdocexa} [With default text] - It can be useful to show a real rendering directly in a document. +\begin{tdocexa} + It can be useful to show a real rendering directly in a document.% \footnote{ Typically when making a demo. } - This is done via \tdocenv{tdocshowcase} as follows. - - \tdoclatexinput[code]{examples-showcase-default.tex} - + This is typed via the environment \tdocenv*{tdocshowcase} as follows. - The result is the following rendering. - \footnote{ - Behind the scenes, the strip is created effortlessly using the \tdocpack{clrstrip} package. - } + \tdoclatexshow[explain = {This results in the following rendering, which is a combination of low vertical spacing and simple import.}]{examples-showcase-default.tex} \end{tdocexa} -\input{examples-showcase-default.tex} - - - -\smallskip \begin{tdocrem} - See the section \ref{tutodoc-latexshow} on page \pageref{tutodoc-latexshow} to easily obtain code followed by its actual rendering as in the previous example. + The section \ref{tutodoc-listing-latexshow} on page \pageref{tutodoc-listing-latexshow} explains how to obtain, via the macro \tdocmacro{tdoclatexshow}, a code followed by its actual rendering as in the previous example. \end{tdocrem} -\begin{tdocnote} - The explanatory texts adapt to the language detected by \thisproj. -\end{tdocnote} +\begin{tdocwarn} + With the default settings, if the code to be formatted begins with an opening bracket, we must use one of the following tricks. + \tdoclatexshow[explain = {This will produce the following.}]{examples-showcase-hook.tex} +\end{tdocwarn} -% ------------------ % +\subsection{With framing lines} -\begin{tdocexa}[Change the colors and/or the texts] - \leavevmode +To make the formatted \LaTeX\ code more visible, you can use the \tdoclatexin{rule} style, as in the following examples. - \tdoclatexinput[code]{examples-showcase-customized.tex} +\begin{tdocexa} + The option \tdoclatexin{style = rule} provides the following where the automatically added texts will adapt to the language found by \thisproj. - This will produce the following. + \input{examples-showcase-rule.tex} +\end{tdocexa} - \medskip - \input{examples-showcase-customized.tex} +\begin{tdocexa}[Editable text and colours] + You can easily obtain the following horror. + + \input{examples-showcase-rule-custom.tex} + Here's the code that was used.% + \footnote{ + The next section will justify the a priori strange choice of \tdoclatexin{col-stripe} instead of \tdoclatexin{col-rule}\,. + } + + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-rule-custom.tex} \end{tdocexa} \begin{tdocnote} - In the previous example, the text uses the proposed darkened orange. On the other hand, red is used as a base to obtain the colors used for the strip: the transformations used depend on the theme chosen.% + In the previous example, the text uses the proposed darkened orange. However, the red is used as a base to obtain the colors used for the framing lines: the transformations used depend on the theme chosen.% \footnote{ For example, the themes \tdoclatexin{bw} and \tdoclatexin{draft} ignore the key \tdoclatexin{col-stripe}! } - % - You should also be aware that behind the scenes, the macro \tdocmacro{tdocruler} is used. + You should also be aware that behind the scenes, the macro \tdocmacro{tdocruler} is used, it works as follows. - \begin{tdoclatex}[std] - \tdocruler[red]{A decorated pseudo-title} + \begin{tdoclatex}<\tdoctcb{std}> +\tdocruler[red]{A decorated pseudo-title} \end{tdoclatex} \end{tdocnote} -% ------------------ % - - -\begin{tdocwarn} - With the default settings, if the code to be formatted begins with an opening bracket, use \tdocmacro{string} as in the following example. - - \tdoclatexinput[code]{examples-showcase-hook.tex} - +\subsection{With colored stripe} - This will produce the following. -\end{tdocwarn} - - -\input{examples-showcase-hook.tex} - - - -\subsection{Without a coloured strip} - -The rendering of \tdocenv{tdocshowcase} with a coloured strip may not be suitable, or sometimes may not be acceptable despite the work done by \tdocpack{clrstrip}. -It is possible not to use a coloured strip, as we will see straight away. +There are situations where you need to be able to clearly identify an example of formatted \LaTeX\ code. This can be done, as the following examples show.% +\footnote{ + Behind the scenes, the strips are created effortlessly using the \tdocpack{clrstrip} package. +} \begin{tdocexa} - The use of \tdocenv[{[nostripe]}]{tdocshowcase} indicate to not use \tdocpack{clrstrip}. - Here is an example. - - \tdoclatexinput[code]{examples-showcase-nostripe.tex} - - - This will produce the following. - - \medskip - - \input{examples-showcase-nostripe.tex} + The \tdoclatexin{style = stripe} option provides the following. + \input{examples-showcase-stripe.tex} \end{tdocexa} -% ------------------ % - - -\begin{tdocexa}[Change the colors and/or the texts] - \leavevmode - - \tdoclatexinput[code]{examples-showcase-nostripe-customized.tex} - - - This will produce the following horror. - - \medskip +\begin{tdocexa}[Editable text and colors] + You can easily produce a beautiful horror like the one below. - \input{examples-showcase-nostripe-customized.tex} + \input{examples-showcase-stripe-custom.tex} + + Here's the code that was used.% + \footnote{ + Now we understand why we chose \tdoclatexin{col-stripe} instead of \tdoclatexin{col-rule}\,. + } + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-stripe-custom.tex} \end{tdocexa} \subsection{By importing the \LaTeX\ code} -To obtain renderings by importing the code from an external file, simply use the \tdocmacro{tdocshowcaseinput} macro whose option uses the syntax of that of \tdocenv{tdocshowcase} and the mandatory argument corresponds to the path of the file. - - -\begin{tdocexa} - The following was obtained via \tdoclatexin+\tdocshowcaseinput{external.tex}+. - - \medskip +To obtain renderings by importing the code from an external file, instead of typing it, simply use the macro \tdocmacro{tdocshowcaseinput} whose option uses the same syntax as that of the environment \tdocenv*{tdocshowcase}, and the mandatory argument corresponds to the path of the file. Here are some examples of use. - \tdocshowcaseinput{examples-showcase-external.tex} +\foreach \exatitle/\style in { + {Standard use}/% <-- Translate me! + {default}, + {With framing lines}/% <-- Translate me! + {rule}, + {A colored stripe}/% <-- Translate me! + {stripe}% +}{ + \begin{tdocexa}[\exatitle] + \leavevmode + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-input-\style.tex} - \medskip - - As for \tdoclatexin+\tdocshowcaseinput[col-stripe = red, col-text = orange!75!black]{external.tex}+\,, this will produce the color change shown below. - - \medskip + This gives: - \tdocshowcaseinput[col-stripe = red, col-text = orange!75!black]{examples-showcase-external.tex} + \smallskip -\end{tdocexa} + \input{examples-showcase-input-\style.tex} + \end{tdocexa} +} \section{Use cases in \LaTeX} +\label{tutodoc-listing-latex} -Documenting a package or class is best done through use cases showing both the code and the corresponding result. +Documenting a package, or class, is best done through use cases showing both the code and the corresponding result.% \footnote{ - Code is formatted using the \tdocpack{minted} package. + Code is formatted using the \tdocpack{minted} and \tdocpack{tcolorbox} packages. } -%\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{tutodoc-listing-latex-inline} +\begin{tdocexa}[Standard use] + The \tdocmacro{tdoclatexin} macro\,% + \footnote{ + The name of the macro \tdocmacro{tdoclatexin} comes from \tdocquote{\tdocprewhy{in.line} \LaTeX}\,. + } + can be used to type code in line in a similar way to \tdocmacro{verb}, or as a standard macro (see the handling of braces in the latter case below). + Here are some examples of use.% + \footnote{ + A background color is deliberately used to subtly highlight the \tdoclatexin{\LaTeX} codes. + } -\subsection{\tdocquote{Inline} codes} -\label{tutodoc-listing-inline} + \begin{tdoclatex}<\tdoctcb{sbs}> +1: \tdoclatexin|$a^b = c$| \\ +2: \tdoclatexin+\tdoclatexin|$a^b = c$|+ \\ +3: \tdoclatexin{\tdoclatexin{$a^b = c$}} + \end{tdoclatex} +\end{tdocexa} -The \tdocmacro{tdoclatexin} macro -\footnote{ - The name of the macro \tdocmacro{tdoclatexin} comes from \tdocquote{\tdocprewhy{in.line} \LaTeX}. -} -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{tdocexa}[Possible options] + As the \tdocmacro{tdoclatexin} macro is based on \tdocpack{minted}, you can use all the options taken into account by \tdocpack{minted}. + Here are some examples. -\begin{tdoclatex}[sbs] - 1: \tdoclatexin|$a^b = c$| \\ - 2: \tdoclatexin+\tdoclatexin|$a^b = c$|+ \\ - 3: \tdoclatexin{\tdoclatexin{$a^b = c$}} -\end{tdoclatex} + \begin{tdoclatex}<\tdoctcb{sbs}> +1: \tdoclatexin[style = bw]{$a^b = c$} \\ +2: \tdoclatexin[style = igor, + showspaces]{$a^b = c$} + \end{tdoclatex} +\end{tdocexa} \begin{tdocnote} - The \tdocmacro{tdoclatexin} macro can be used in a footnote: see below. + The \tdocmacro{tdoclatexin} macro can be used in a footnote as shown below.% \footnote{ - \tdoclatexin+$minted = TOP$+ has been typed \tdoclatexin|\tdoclatexin+$minted = TOP$+| in this footnote... + \tdoclatexin+$minted = TOP$+ has been typed \tdoclatexin|\tdoclatexin+$minted = TOP$+| in this footnote. } - In addition, a background color is deliberately used to subtly highlight the codes \tdoclatexin#\LaTeX#\,. \end{tdocnote} -% ------------------ % - - \subsection{Directly typed codes} \begin{tdocexa}[Side by side] - Using \tdocenv[{[sbs]}]{tdoclatex}, we can display a code and its rendering side by side. - \tdocbasicinputDOC{examples-listing-ABC.tex} + Displaying a code and its rendering side by side is done as follows where the macro \tdocmacro{tdoctcb} allows you to just type \tdoclatexin{tdoctcb{sbs}} instead of \tdoclatexin{listing side text} (\tdoclatexin#sbs# is for \tdocquote{\tdocprewhy{s.ide} \tdocprewhy{b.y} \tdocprewhy{s.ide}}, while \tdoclatexin#tcb# is the standard abbreviation for \texttt{tcolorbox}). Note the use of rafters, not square brackets (more on this later). + \tdoclatexshow{examples-listing-latex-ABC.tex} \end{tdocexa} -% ------------------ % - - \begin{tdocexa}[Following] - \tdocenv{tdoclatex} produces the following result, which corresponds to the default option \tdoclatexin#std#\,. + \tdocenv{tdoclatex} produces the following result (this default setting is also obtained by using \tdoclatexin#\tdoctcb{std}#).% \footnote{ \tdoclatexin{std} refers to the \tdocquote{standard} behaviour of \tdocpack{tcolorbox} in relation to the \tdocpack{minted} library. } \begin{tdoclatex} - $A = B + C$ +$A = B + C$ \end{tdoclatex} \end{tdocexa} -% ------------------ % - - \begin{tdocexa}[Just the code] - Via \tdocenv[{[code]}]{tdoclatex}, we'll just get the code as shown below. + Via \tdoclatexin#\tdoctcb{code}#, we'll just get the code as below. - \begin{tdoclatex}[code] - $A = B + C$ + \begin{tdoclatex}<\tdoctcb{code}> +$A = B + C$ \end{tdoclatex} \end{tdocexa} -% ------------------ % +\begin{tdocexa}[Customise] + The \tdocenv*{tdoclatex} environment accepts two types of optional argument. + % + \begin{enumerate} + \item Between classic square brackets, you can use any option taken into account by \tdocpack{minted}. + \item Between rafters, you can use any option managed by the environments obtained via \tdocpack{tcolorbox}. + \end{enumerate} -\begin{tdocwarn} - With default formatting, if the code begins with an opening bracket, the default option must be explicitly indicated. - \tdocbasicinputDOC{examples-listing-strange.tex} + For example, the following modifications can be made if required.% + \footnote{ + This documentation uses the options between rafters to obtain correct rendering of code producing shaded frames: see the section \ref{tutodoc-admonitions} on page \pageref{tutodoc-admonitions}. + } + + \tdoclatexshow{examples-listing-latex-ABC-custom.tex} +\end{tdocexa} +\medskip - \smallskip +\begin{tdocwarn} + To obtain the default formatting for a code beginning with a bracket or a rafter, you'll need to do a bit of fiddling, as shown below. + \tdoclatexshow{examples-listing-latex-strange.tex} - Another method is to use the \tdocmacro{string} primitive. - \tdocbasicinputDOC{examples-listing-strange-bis.tex} + \smallskip + Another method is to use the \tdocmacro{string} primitive, as shown below. + \tdoclatexshow{examples-listing-latex-strange-bis.tex} \end{tdocwarn} @@ -1782,129 +2086,167 @@ Here are some examples. For the following codes, consider a file with the relative path \verb+examples-listing-xyz.tex+, and with the following contents. -\tdoclatexinput[code]{examples-listing-xyz.tex} - +\tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-xyz.tex} \medskip -The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same options as the \tdocenv*{tdoclatex} environment. - +The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same system of options between square brackets, or rafters, as the environment \tdocenv*{tdoclatex}. + +\foreach \title/\extra/\fname in {% + {Side by side}/% + {}/% + sbs, + {Following}/% + {, which also corresponds to the option \tdoclatexin{\tdoctcb{std}}\,}/% + std,% + {Only the code}/% + {}/% + code,% + {Customise}/% + {}/% + perso% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexshow[explain=This produces the following formatting\extra.]{examples-listing-latex-latexinput-option-\fname.tex} + \end{tdocexa} +} -% ------------------ % -\begin{tdocexa}[Side by side] - \leavevmode +\subsection{Imported codes put into practice} +\label{tutodoc-listing-latexshow} - \begin{tdoclatex}[code] -\tdoclatexinput[sbs]{examples-listing-xyz.tex} +\begin{tdocnote} + The default texts take into account the language detected by \thisproj. +\end{tdocnote} - \end{tdoclatex} - This produces the following layout. +\begin{tdocexa}[Showcase] + The following comes from \tdoclatexin+\tdoclatexshow{examples-listing-xyz.tex}+. - \tdoclatexinput[sbs]{examples-listing-xyz.tex} + \smallskip + \tdoclatexshow{examples-listing-latex-xyz.tex} \end{tdocexa} -% ------------------ % - - -\begin{tdocexa}[Following] - \leavevmode - - \begin{tdoclatex}[code] -\tdoclatexinput{examples-listing-xyz.tex} - - \end{tdoclatex} - - This produces the following formatting where the default option is \tdoclatexin#std#. +\begin{tdocexa}[Changing the explanatory text] + Using the key \tdoclatexin|explain|, you can use a custom text. Thus, \tdoclatexin|\tdoclatexshow[explain = Here is the rendering.]{examples-listing-xyz.tex}| will give the following. - \tdoclatexinput{examples-listing-xyz.tex} + \smallskip + \tdoclatexshow[explain = Here is the rendering.]{examples-listing-latex-xyz.tex} \end{tdocexa} -% ------------------ % - +\begin{tdocexa}[The options available] + In addition to the explanatory text, it is also possible to use all the options of \tdocenv*{tdocshowcase} environment, see \ref{tutodoc-showcase} on page \pageref{tutodoc-showcase}. + Here is an example to illustrate this. -\begin{tdocexa}[Just the code] - \leavevmode + \medskip - \begin{tdoclatex}[code] -\tdoclatexinput[code]{examples-listing-xyz.tex} + \tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-latexshow-options.tex} - \end{tdoclatex} + \smallskip - This produces the following layout. + This will produce the following. - \tdoclatexinput[code]{examples-listing-xyz.tex} + \smallskip + \input{examples-listing-latex-latexshow-options.tex} \end{tdocexa} -% ------------------ % - +\section{Presenting computer code} -\subsection{Imported codes put into practice} -\label{tutodoc-latexshow} - -\begin{tdocexa}[Showcase] - The following comes from \tdoclatexin+\tdoclatexshow{examples-listing-xyz.tex}+. - - \medskip - - \begin{tdocshowcaseDOC} - \tdoclatexshow{examples-listing-xyz.tex} +Some packages offer functions that require to code a little in \lua.%. +\footnote{ + For mathematics, these include \tdocpack{luacas} and \tdocpack{tkz-elements}. +} +For these projects, the documentation must be able to present lines of code; this is why \thisproj\ makes it easy to do this, and much more.% +\footnote{ + As code formatting is done via the packages \tdocpack{minted} and \tdocpack{tcolorbox}, the macros and environments presented in this section allow code to be formatted in all the languages supported by \pygmentsREF, a \python\ project used behind the scenes by \tdocpack{minted}. +} - \end{tdocshowcaseDOC} -\end{tdocexa} +\begin{tdocimp} + The tools in this section can also be used to present \LaTeX code, but they should not be used for simple use cases, as the macros and environments presented next are for studying code, not just for using it: see the section \ref{tutodoc-listing-latex} on page \pageref{tutodoc-listing-latex} to use the right tools for formatting \LaTeX\ use cases. +\end{tdocimp} -\begin{tdocnote} - The default texts take into account the language detected by \thisproj. -\end{tdocnote} -% ------------------ % +\subsection{\tdocquote{Inline} codes} +The \tdocmacro{tdoccodein}\,% +\footnote{ + The name of the macro \tdocmacro{tdoccodein} comes from \tdocquote{\tdocprewhy{in.line} \tdocpre{code}}\,. +} +macro expects two arguments: the \ordinalnum{1} indicates the programming language, and the \ordinalnum{2} gives the code to be formatted. +It is possible to use an option identical to that proposed by \tdocmacro{tdoclatexin}: see the section \ref{tutodoc-listing-latex-inline} on page \pageref{tutodoc-listing-latex-inline}. +Here are some possible use cases.% +\footnote{ + A background color is used to subtly highlight the formatted codes. For example, typing \tdoclatexin{\tdoccodein{py}{funny = "ah"*3}} will produce \tdoccodein{py}{funny = "ah"*3}\,. +} -\begin{tdocexa}[Changing the explanatory text] - Using the key \tdoclatexin|explain|, you can use custom text. Thus, \tdoclatexin|tdoclatexshow[explain = Here is the rendering.]{examples-listing-xyz.tex}| will give the following. +\begin{tdoclatex} +1: \tdoccodein{py}{print("OK" if i = 0 else "KO")} \\ +2: \tdoccodein[style = bw]{py}{print("OK" if i = 0 else "KO")} \\ +3: \tdoccodein[style = igor, showspaces]% + {py}{print("OK" if i = 0 else "KO")} +\end{tdoclatex} - \medskip +\medskip - \begin{tdocshowcaseDOC} - \tdoclatexshow[explain = Here is the rendering.]{examples-listing-xyz.tex} +\begin{tdocnote} + The page \url{https://pygments.org/languages} contains a complete list of supported languages with their short names. For example, it is possible to format \brainfuck\ code like this obscure sequence \tdoccodein{bf}{++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.} which displays \tdoccodein{text}{Hello}\,. +\end{tdocnote} - \end{tdocshowcaseDOC} -\end{tdocexa} -% ------------------ % +\subsection{Codes typed directly} +Code can be typed directly into a document via \tdocenv{tdoccode} which expects an argument indicating the programming language, and any options between parenthesis and/or square brackets identical to those proposed by \tdocenv{tdoclatex}: see the section \ref{tutodoc-listing-latex} on page \pageref{tutodoc-listing-latex}.% +\footnote{ + Note that the coloring of the \LaTeX\ codes is lexically correct, but semantically wrong. +} -\begin{tdocexa}[The options available] - In addition to the explanatory text, it is also possible to use all the options of \tdocenv*{tdocshowcase} environment, see \ref{tutodoc-showcase} page \pageref{tutodoc-showcase}. - Here is an example to illustrate this. - \medskip +% Strings "..." in the source codes must also be translated. +\foreach \title/\lang in {% + {Standard feature}/% + perl,% + {One-off rendering customization}/% + lua% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexshow{examples-listing-full-hello-you-\lang} + \end{tdocexa} +} - \tdoclatexinput[code]{examples-listing-latexshow-options.tex} +\subsection{Imported codes} - \medskip +The \tdoclatexin{tdoccodeinput} macro expects the language and path of a file to be formatted, and possibly options similar to those offered by the \tdocenv*{tdoccode} environment. - This will produce the following. - \medskip +% Strings "..." in the source codes must also be translated. +\foreach \title/\lang in {% + {Standard features}/% + hs,% + {Customize rendering on occasion}/% + tex% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexinput<\tdoctcb{code}>{examples-listing-full-input-hello-you-\lang} - \begin{tdocshowcaseDOC} - \input{examples-listing-latexshow-options.tex} + This gives: - \end{tdocshowcaseDOC} -\end{tdocexa} + \input{examples-listing-full-input-hello-you-\lang} + \end{tdocexa} +} \section{Indicate changes} @@ -1917,28 +2259,20 @@ To make it easier to monitor a project, it is essential to provide a history ind \subsection{When?} \label{tutodoc-changes-when} -You can either date something, or version it, in which case the version number can be dated. +You can date and/or version something. -% ------------------ % - - -\begin{tdocexa}[Dating new products] +\begin{tdocexa}[Dating new features] The \tdocmacro{tdocdate} macro is used to indicate a date in the margin, as in the following example. \tdoclatexshow{examples-version-n-change-dating.tex} - \end{tdocexa} -% ------------------ % - - \begin{tdocexa}[Versioning new features, possibly with a date] - Associating a version number with a new feature is done using the \tdocmacro{tdocversion} macro, with the colour and date being optional arguments. + Associating a version number with a new feature is done using the \tdocmacro{tdocversion} macro, with the color and date being optional arguments. \tdoclatexshow{examples-version-n-change-versioning.tex} - \end{tdocexa} @@ -1946,15 +2280,13 @@ You can either date something, or version it, in which case the version number c The following example shows that a date and/or version must be placed just after a paragraph title, and not before it. \tdoclatexshow{examples-version-n-change-para-title.tex} - \end{tdocexa} -\begin{tdocexa}[Adjust vertical positioning] +\begin{tdocexa}[Adjust vertical shift] If required, you can modify the vertical offset used to place dates and versions in the margin, the default value being $(-8\,\mathit{pt})$. \tdoclatexshow{examples-version-n-change-manual-setting.tex} - \end{tdocexa} @@ -1968,7 +2300,7 @@ You can either date something, or version it, in which case the version number c \begin{tdoccaut} - Only the use of the digital format \tdoclatexin+YYYY-MM-DD+ is verified, + Only the use of the digital format \tdoclatexin+YYYY-MM-DD+ is verified,% \footnote{ Technically, checking the validity of a date using \LaTeX3 presents no difficulty. } @@ -1985,13 +2317,14 @@ You can either date something, or version it, in which case the version number c \begin{tdocnote} - For icons, see the note at the beginning of the section \ref{tutodoc-admonitions} page \pageref{tutodoc-admonitions}. + For icons, see the note at the beginning of the section \ref{tutodoc-admonitions} on page \pageref{tutodoc-admonitions}. \end{tdocnote} \subsubsection{Sobriety first} \foreach \exatitle/\filename in { +% Standard. {Just for the very first version}/%<-- Translate me! first, {For new features}/% <-- Translate me! @@ -2008,6 +2341,7 @@ You can either date something, or version it, in which case the version number c todo, {Technical information}/% <-- Translate me! tech, +% Customized. {Selectable themes with an icon}/% <-- Translate me! user-choice-icon, {Selectable themes without icons}/%<-- Translate me! @@ -2016,17 +2350,14 @@ You can either date something, or version it, in which case the version number c \begin{tdocexa}[\exatitle] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-chges-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}>{examples-version-n-change-chges-\filename.tex} \end{tdocexa} } -\subsubsection{De la couleur si besoin} - \subsubsection{Color if necessary} -It may be useful to highlight certain changes: this can only be done by modifying the content color. +It may be useful to highlight some changes: this can only be done by modifying the content color. \foreach \exatitle/\filename in { {A flashy first version}/%<-- Translate me! @@ -2037,27 +2368,25 @@ It may be useful to highlight certain changes: this can only be done by modifyin \begin{tdocexa}[\exatitle] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-color-chges-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}>{examples-version-n-change-color-chges-\filename.tex} \end{tdocexa} } \subsection{The what and the when} -The optional keys \tdoclatexin{col}\,, \tdoclatexin{date} and \tdoclatexin{version} allow to date and version a change of a particular type. +The optional keys \tdoclatexin{col-chges}\,, \tdoclatexin{date} and \tdoclatexin{version} allow to date and/or version a change of a particular type. Here are some examples of use. \tdoclatexshow{examples-version-n-change-what-n-when.tex} - \section{Ornament} -Let's finish this documentation with a small formatting tool that is very useful. +Let's finish this documentation with a small formatting tool that can be very useful. -\begin{tdoclatex}[sbs] +\begin{tdoclatex}<\tdoctcb{sbs}> Bla, bla, bla... \tdocsep % Practical for demarcation. @@ -2065,7 +2394,7 @@ Bla, bla, bla... This works with enumerations. \begin{itemize} - \item Underline. + \item Focus. \end{itemize} \tdocsep % Uniform behaviour. @@ -2106,9 +2435,9 @@ Ble, ble, ble... \end{figure} -The translations are roughly organized as in figure \ref{tutodoc-contrib-translate-dir} where only the folders important for the translations have been \tdocquote{opened}\,.%}. +The translations are roughly organized as in figure \ref{tutodoc-contrib-translate-dir} where just the important folders for the translations have been \tdocquote{opened}\,.% \footnote{ - This was the organization on October 5, 2024, but it's still relevant today. + This was the organization on October 5, 2024. } \textbf{A little further down, the section \ref{tutodoc-contrib-translate} explains how to add new translations}. @@ -2138,8 +2467,8 @@ The \texttt{LICENSE.txt} file is aptly named, while the \texttt{README.md} file \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. + Here you'll find \verb#TXT# files for editing with a text or code editor, but not with a document 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} @@ -2156,7 +2485,7 @@ The \texttt{LICENSE.txt} file is aptly named, while the \texttt{README.md} file \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. + The \verb#doc# folder is reserved for documentation. It contains \verb#TEX# files that can be compiled directly for real-time validation of translations. \end{tdocnote} @@ -2170,22 +2499,22 @@ The \texttt{LICENSE.txt} file is aptly named, while the \texttt{README.md} file \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. + As mentioned above, there is no real need for the \texttt{doc} folder. } -\paragraph{Method 1 : \git.} +\paragraph{Method 1 : use of \git.} \begin{enumerate} - \item Obtain the entire project folder via \thisrepo\,. + \item Recover 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,. - \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 + \item In the \verb#tutodoc/contrib/translate# folder, create an \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}. - \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#\,. + \item Once the translation is complete in the \verb#it# folder, share it via \thisrepo\ using a classic \verb#git push#\,. \end{enumerate} @@ -2207,15 +2536,15 @@ The \texttt{LICENSE.txt} file is aptly named, while the \texttt{README.md} file \subsection{Improving the source code} \begin{tdocimp} - If you want to participate in \thisproj\, you'll need to use the \LaTeX3 programming paradigm. + If you want to participate to \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. +Participation as a coder is made via the repository \thisrepo\ corresponding to the \verb#tutodoc# development branch. \begin{tdoccaut} -Do not use the \verb#main# branch, which is used to freeze the latest stable versions of projects in the single \thismonorepo\ repository. +Do not use the \verb#main# branch, which is used to freeze the latest stable versions of projects in the mono repository \thismonorepo. \end{tdoccaut} @@ -2223,6 +2552,59 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \small +\begin{tdocfix}[version = 1.7.1, date = 2024-12-18] + \item Documentation: references to tools to indicate changes have been incorrectly written as characteristics of highlighted colored content. +\end{tdocfix} + + +\begin{tdocbreak} + \item The \tdocmacro{tdocenv} macro and its starred version no longer offer an option. + + \item \LaTeX\ showcases: the default layout is more sober, and there are options for having just the rulers, or the colored stripe. See just after. +\end{tdocbreak} + + +\begin{tdocnew} + \item Formatting of computer codes in addition to those specifically in \LaTeX. + % + \begin{enumerate} + \item Creation of \tdocenv{tdoccode} and \tdocmacro{tdoccodein}. + + \item For macros for inline code, and environments for blocks of code, \tdocpack{minted} options are indicated inside square brackets in the traditional way: \tdoclatexin{[minted options]}\,. + + \item For code block environments, \tdocpack{tcolorbox} options are indicated inside rafters: \tdoclatexin{<tcolorbox options>}\,. + + \item The new macro \tdocmacro{tdoctcb} allows to use shortcuts for regularly used \tdocpack{tcolorbox} styles. + \end{enumerate} + + \item Documentation: a new section presents tools for formatting computer codes other than those in \LaTeX. +\end{tdocnew} + + +\begin{tdocupdate} + \item Sub-sub-sections are numbered in lower case. + + \item Themes. + % + \begin{enumerate} + \item Less space consumed. + + \item Shadows have better coloring. + + \item For all themes except the \tdoclatexin{draft} one, the radius of the arcs of the corners of the frames has changed from \tdoclatexin{.75mm} to \tdoclatexin{.2pt},. + + \item Use case in \LaTeX: with the theme \tdoclatexin{color}, the background color changes from \tdoclatexin[bgcolor = yellow!4]{yellow!4} to \tdoclatexin{gray!5}. + + \item Latest changes: with the \tdoclatexin{dark} theme, the \tdoclatexin{[Init]} text produced by the \tdocmacro{tdocstartproj} macro uses the same font as the environment titles to indicate changes. + \end{enumerate} +\end{tdocupdate} + +\tdocsep + + +% ------------------ % + + \begin{tdocbreak}[version = 1.7.0, date = 2024-12-04] \item Format: the \tdoccls{scrartcl} class replaces the venerable \tdoccls{article}. This implies better placement of the margin notes with the options retained for loading \tdoccls{scrartcl}. @@ -2231,7 +2613,7 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \item Color key names will be hyphenated where necessary: this implies the following changes. % \begin{enumerate} - \item Admonitions: the \tdoclatexin{colchges} option of the environments has been renamed \tdoclatexin{col-chges}. + \item Indicate the latest changes: the \tdoclatexin{colchges} option of the environments has been renamed \tdoclatexin{col-chges}. \item Showcases: for the environment \tdocenv*{tdocshowcase} and the macro \tdocmacro{tdocshowcaseinput}, the \tdoclatexin{colstripe} and \tdoclatexin{coltext} options have been renamed \tdoclatexin{col-stripe} and \tdoclatexin{col-text}\,. \end{enumerate} @@ -2256,10 +2638,10 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \item The macro \tdocmacro{tdocinEN} respects the English linguistic rules. - \item Admonitions. + \item Indicate the latest changes. % \begin{enumerate} - \item A new environment \tdocenv{tdoctodo} has been added. + \item Add the environment \tdocenv{tdoctodo}\,. \item Each environment has a new option \tdoclatexin{col} for the color of the content indicating changes. \end{enumerate} @@ -2267,7 +2649,7 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \begin{tdocupdate} - \item \tdoclatexin{draft} theme and changes: the environments for the kind of changes stop to use icons. + \item \tdoclatexin{draft} theme and changes: the environments for the latest changes stop to use icons. \item Documentation: the theme gallery uses a better fake example. \end{tdocupdate} @@ -2278,9 +2660,9 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \item Simplified organisation of configuration files in the final project. % \begin{enumerate} - \item \texttt{CSS}-like: use of one file per theme with a name like \texttt{tutodoc-bw.css.cls}\,. + \item Use of one file per theme with a name like \texttt{tutodoc-*.css.cls}\,. - \item Locale: use of names like \texttt{tutodoc-en.loc.cls}\,. + \item Locale: use of names like \texttt{tutodoc-*.loc.cls}\,. \end{enumerate} \end{tdoctech} @@ -2325,9 +2707,9 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \begin{tdocbreak}[version = 1.6.0, date = 2024-10-27] - \item The \tdocenv*{showcase} environment and its descendants: the \tdoclatexin{color} key has been renamed \tdoclatexin{col-stripe}. + \item The \tdocenv*{showcase} environment and its descendants: the \tdoclatexin{color} key has been renamed \tdoclatexin{colstripe}. - \item The macro \tdocmacro{tdoclinkcolor} has been renamed \tdoclatexin{tutodoc@link@color} for internal use. + \item The macro \tdocmacro{tdoclinkcolor} becomes the color \tdoclatexin{tutodoc@link@color} for internal use. \end{tdocbreak} @@ -2336,7 +2718,7 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \item Change log: addition of the \tdocenv*{tdoctech} environment for technical information. - \item The \tdocenv*{showcase} environment and its descendants: the \tdoclatexin{col-text} key can also be used to change the text color. + \item The \tdocenv*{showcase} environment and its descendants: the \tdoclatexin{coltext} key can also be used to change the text color. \item The new functionalities have been documented. \end{tdocnew} @@ -2351,7 +2733,7 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \begin{tdocfix} - \item The Spanish translations were not included in the previous version! Don't laugh too hard... + \item The Spanish translations were not included in the previous version! Don't laugh too loud... \end{tdocfix} \tdocsep @@ -2394,7 +2776,7 @@ Do not use the \verb#main# branch, which is used to freeze the latest stable ver \begin{tdocbreak}[version = 1.4.0, date = 2024-09-28] \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 using a common counter. + \item Content highlighting: examples and remarks, indicated via the \tdocenv*{tdocexa} and \tdocenv*{tdocrem} environments, are numbered using a common counter. \item The unused macro \tdocmacro{tdocxspace} has been deleted. \end{tdocbreak} diff --git a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf Binary files differindex 47cee60d377..d524b60cded 100644 --- a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf +++ b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf diff --git a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex index 0c55d7bfcf4..6b0a09385ad 100644 --- a/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex +++ b/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex @@ -12,18 +12,37 @@ \frenchsetup{StandardItemLabels=true} \usepackage{multicol} +\usepackage{lastpage} + +\makeatletter + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{% + \thepage\kern1pt/\kern1pt\pageref*{LastPage}% + }% +} + +\makeatother + \newcommand\thisstyle{bw} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal. } + \newcommand\myadmotext{ Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance. } +\newcommand\myhighlightedtextnonote{ + Que dire ? + Je ne sais pas, mais c'est sympathique. Non ? +} + \newcommand\myhighlightedtext{ Que dire\,% \footnote{ @@ -33,16 +52,46 @@ } +\newcommand\mychgestext{ + Dans un journal de bord, il est important de bien visualiser les types de changements. Ceci rend plus efficace la lecture côté utilisateur ! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} \textsf{\Huge\bfseries Le thème \texttt{"\thisstyle"}} - \section{Liens} {\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{Un lien très gros}}, mais au moins on le voit. + +\section{Des codes \LaTeX} + +Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. + +\begin{tdoclatex} +Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Du code \LaTeX\ mis en forme, c'est top: \\ +$E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + \section{Mettre en avant, versionner et dater} \subsection{tdocexa, tdocrem} @@ -59,7 +108,6 @@ \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -68,20 +116,28 @@ \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -89,47 +145,68 @@ \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{Nouvelle section démonstrative...} +\tdocstartproj{Une nouvelle section démonstrative...} -\medskip +\begin{tdoctodo} + \item Une galerie serait bienvenue... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{Des codes \LaTeX} - -Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. - -\begin{tdoclatex} -Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? - -\begin{tdoclatex}[sbs] -Du code \LaTeX\ mis en forme, c'est top : \\ -$E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -143,18 +220,37 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \frenchsetup{StandardItemLabels=true} \usepackage{multicol} +\usepackage{lastpage} + +\makeatletter + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{% + \thepage\kern1pt/\kern1pt\pageref*{LastPage}% + }% +} + +\makeatother + \newcommand\thisstyle{color} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal. } + \newcommand\myadmotext{ Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance. } +\newcommand\myhighlightedtextnonote{ + Que dire ? + Je ne sais pas, mais c'est sympathique. Non ? +} + \newcommand\myhighlightedtext{ Que dire\,% \footnote{ @@ -164,16 +260,46 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + Dans un journal de bord, il est important de bien visualiser les types de changements. Ceci rend plus efficace la lecture côté utilisateur ! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} \textsf{\Huge\bfseries Le thème \texttt{"\thisstyle"}} - \section{Liens} {\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{Un lien très gros}}, mais au moins on le voit. + +\section{Des codes \LaTeX} + +Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. + +\begin{tdoclatex} +Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Du code \LaTeX\ mis en forme, c'est top: \\ +$E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + \section{Mettre en avant, versionner et dater} \subsection{tdocexa, tdocrem} @@ -190,7 +316,6 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -199,20 +324,28 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -220,47 +353,68 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{Nouvelle section démonstrative...} +\tdocstartproj{Une nouvelle section démonstrative...} -\medskip +\begin{tdoctodo} + \item Une galerie serait bienvenue... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{Des codes \LaTeX} - -Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. - -\begin{tdoclatex} -Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? - -\begin{tdoclatex}[sbs] -Du code \LaTeX\ mis en forme, c'est top : \\ -$E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -274,18 +428,37 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \frenchsetup{StandardItemLabels=true} \usepackage{multicol} +\usepackage{lastpage} + +\makeatletter + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{% + \thepage\kern1pt/\kern1pt\pageref*{LastPage}% + }% +} + +\makeatother + \newcommand\thisstyle{dark} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal. } + \newcommand\myadmotext{ Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance. } +\newcommand\myhighlightedtextnonote{ + Que dire ? + Je ne sais pas, mais c'est sympathique. Non ? +} + \newcommand\myhighlightedtext{ Que dire\,% \footnote{ @@ -295,16 +468,46 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + Dans un journal de bord, il est important de bien visualiser les types de changements. Ceci rend plus efficace la lecture côté utilisateur ! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} \textsf{\Huge\bfseries Le thème \texttt{"\thisstyle"}} - \section{Liens} {\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{Un lien très gros}}, mais au moins on le voit. + +\section{Des codes \LaTeX} + +Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. + +\begin{tdoclatex} +Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Du code \LaTeX\ mis en forme, c'est top: \\ +$E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + \section{Mettre en avant, versionner et dater} \subsection{tdocexa, tdocrem} @@ -321,7 +524,6 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -330,20 +532,28 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -351,47 +561,68 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{Nouvelle section démonstrative...} +\tdocstartproj{Une nouvelle section démonstrative...} -\medskip +\begin{tdoctodo} + \item Une galerie serait bienvenue... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{Des codes \LaTeX} - -Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. - -\begin{tdoclatex} -Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? - -\begin{tdoclatex}[sbs] -Du code \LaTeX\ mis en forme, c'est top : \\ -$E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -405,18 +636,37 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \frenchsetup{StandardItemLabels=true} \usepackage{multicol} +\usepackage{lastpage} + +\makeatletter + +\renewcommand*\pagemark{% + \usekomafont{pagenumber}{% + \thepage\kern1pt/\kern1pt\pageref*{LastPage}% + }% +} + +\makeatother + \newcommand\thisstyle{draft} + \newcommand\myexrmktext{ \tdocversion{1.7.0}[2024-12-04] Dans le flot du texte, il est toujours utile de pouvoir indiquer des exemples et des remarques qui viennent compléter le contenu principal. } + \newcommand\myadmotext{ Suivant le contexte d'utilisation, il est parfois nécessaire de pouvoir mettre en avant des contenus en indiquant leur degré d'importance. } +\newcommand\myhighlightedtextnonote{ + Que dire ? + Je ne sais pas, mais c'est sympathique. Non ? +} + \newcommand\myhighlightedtext{ Que dire\,% \footnote{ @@ -426,16 +676,46 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. } +\newcommand\mychgestext{ + Dans un journal de bord, il est important de bien visualiser les types de changements. Ceci rend plus efficace la lecture côté utilisateur ! +} + + +\ExplSyntaxOn + +\int_new:N \g__tutodoc_for_doc_int + +\ExplSyntaxOff + + \begin{document} \textsf{\Huge\bfseries Le thème \texttt{"\thisstyle"}} - \section{Liens} {\Large\bfseries \href{https://github.com/bc-tools/for-latex/tree/main/tutodoc}{Un lien très gros}}, mais au moins on le voit. + +\section{Des codes \LaTeX} + +Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. + +\begin{tdoclatex} +Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + +On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? + +\begin{tdoclatex}<\tdoctcb{sbs}> +Du code \LaTeX\ mis en forme, c'est top: \\ +$E = m c^2$ ou $\pi \neq \frac{3}{14}$. +\end{tdoclatex} + + + \section{Mettre en avant, versionner et dater} \subsection{tdocexa, tdocrem} @@ -452,7 +732,6 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff -\myexrmktext \subsection{tdocnote, tdoctip...} @@ -461,20 +740,28 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOn +\int_set:Nn \g__tutodoc_for_doc_int { 0 } + \ifcsundef{g__tutodoc_focus_color_seq}{ \prop_map_inline:Nn \g__tutodoc_focus_color_prop { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } { \seq_map_inline:Nn \g__tutodoc_focus_color_seq { - \medskip + \int_gincr:N \g__tutodoc_for_doc_int \begin{tdoc#1} - \myhighlightedtext + \int_compare:nTF + {\g__tutodoc_for_doc_int = 1 } + { \myhighlightedtext } + { \myhighlightedtextnonote } \end{tdoc#1} } } @@ -482,47 +769,68 @@ $E = m c^2$ ou $\pi \neq \frac{3}{14}$. \ExplSyntaxOff + \subsection{tdocbreak, tdocfix...} -\tdocstartproj{Nouvelle section démonstrative...} +\tdocstartproj{Une nouvelle section démonstrative...} -\medskip +\begin{tdoctodo} + \item Une galerie serait bienvenue... +\end{tdoctodo} -\myexrmktext +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\ExplSyntaxOn +\mychgestext -\begin{multicols}{2} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \medskip +}{} -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \begin{tdoc#1} - \item Infos... - \end{tdoc#1} -} +\ExplSyntaxOn -\vfill\null +\int_set:Nn \g__tutodoc_for_doc_int { 0 } -\end{multicols} +\begin{tabular}{% + @{\hskip 0pt}p{.26\linewidth}% + *{3}{@{\hskip 7pt}p{.23\linewidth}}@{\hskip 0pt}% +} + \ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-12pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + }{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \int_gincr:N \g__tutodoc_for_doc_int + + \vspace{-5pt} + + \begin{tdoc#1} + \item Infos... + \end{tdoc#1} + + \int_compare:nTF + {\g__tutodoc_for_doc_int = 4 } + { \\ } + { & } + } + } +\end{tabular} \ExplSyntaxOff - -\section{Des codes \LaTeX} - -Taper du code \LaTeX\ en ligne comme \tdoclatexin{E = m c^2 \neq \pi \neq \frac{3}{14}} est utile, tout comme montrer des cas d'utilisation comme le suivant. - -\begin{tdoclatex} -Du code \LaTeX\ mis en forme, c'est top : $E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - - -On dispose aussi d'un mode côte-à-côte moins envahissant. Sympa ! Non ? - -\begin{tdoclatex}[sbs] -Du code \LaTeX\ mis en forme, c'est top : \\ -$E = m c^2$ ou $\pi \neq \frac{3}{14}$. -\end{tdoclatex} - \end{document} \end{filecontents*} @@ -591,7 +899,7 @@ Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu... \tdocversion[red]{10.2.0-beta}[2023-12-01] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... -\bigskip % ATTENTION ! Ceci évite le chevauchement. +\smallskip\bigskip % ATTENTION ! Ceci évite le chevauchement. \tdocversion{10.2.0-alpha} Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, @@ -656,7 +964,7 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \begin{filecontents*}[overwrite]{examples-version-n-change-manual-setting.tex} Voilà ce que cela donne sans déplacement vertical. -\paragraph{Un réglage maison}% +\paragraph{Un réglage maison.}% \tdocversion{1.2.3}[2024-10-29]<0pt> Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo... @@ -803,66 +1111,126 @@ VERSUS. \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-latexshow-options.tex} -\tdoclatexshow[explain = Ce qui vient est coloré..., - before = Rendu ci-après., - after = Rendu fini., - col-stripe = orange, - col-text = blue!70!black] - {examples-listing-xyz.tex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you.tex} +\NewDocumentCommand{\helloyou}{m}{% + \IfBlankTF{#1}{% + Ah, pas très bavard aujourd'hui !% + }{% + Bonjour #1. + + Épatant ! En fait, pas du tout...% + }% +} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-ABC.tex} -\begin{tdoclatex}[sbs] - $A = B + C$ -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-input-hello-you-hs.tex} +\tdoccodeinput{hs}{examples-listing-full-hello-you.hs} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-xyz.tex} -% Juste une démo. -$x y z = 1$ +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you.hs} +main :: IO () +main = do + putStr "Qui êtes-vous ? " + name <- getLine + + if name == "" + then putStrLn "Ah, pas très bavard aujourd'hui !" + else do + putStrLn ("Bonjour " ++ name ++ ".") + putStrLn "Épatant ! En fait, pas du tout..." \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-strange.tex} -\begin{tdoclatex}[std] - [Étrange... Ou pas !] -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you-lua.tex} +\begin{tdoccode}[style = solarized-light, linenos]% + <leftrule = 22pt, colback = orange!5, colframe = red!35>% + {lua} +io.write("Qui êtes-vous ? ") +local name = io.read() + +if name == "" then + print("Ah, pas très bavard aujourd'hui !") + +else + print("Bonjour " .. name .. ".") + print("Épatant ! En fait, pas du tout...") +end +\end{tdoccode} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex} -\begin{tdoclatex} - \string[Étrange... Ou pas !] -\end{tdoclatex} +\begin{filecontents*}[overwrite]{examples-listing-full-hello-you-perl.tex} +\begin{tdoccode}{pl} +print "Qui êtes-vous ? "; +my $name = <STDIN>; + +chomp($name); + +if ($name eq "") { + print "Ah, pas très bavard aujourd'hui !\n"; + +} else { + print "Bonjour $name.\n"; + print "Épatant ! En fait, pas du tout...\n"; +} +\end{tdoccode} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-customized.tex} -\begin{tdocshowcase}[before = Mon début, - after = Ma fin à moi, - col-stripe = red, - col-text = orange!75!black] - Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... -\end{tdocshowcase} +\begin{filecontents*}[overwrite]{examples-listing-full-input-hello-you-tex.tex} +\tdoccodeinput[style = solarized-light, linenos]% + <leftrule = 22pt, colback = orange!5, colframe = red!35>% + {tex}{examples-listing-full-hello-you.tex} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-showcase-hook.tex} +\begin{tdocshowcase}[] + [Cela fonctionne...] +\end{tdocshowcase} + +OU. + \begin{tdocshowcase} - \string[Cela fonctionne...] + \string[Cela fonctionne aussi...] \end{tdocshowcase} \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-nostripe-customized.tex} -\begin{tdocshowcase}[nostripe, - before = Mon début, - after = Ma fin à moi, +\begin{filecontents*}[overwrite]{examples-showcase-rule.tex} +\begin{tdocshowcase}[style = rule] + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... +\end{tdocshowcase} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-stripe-custom.tex} +\begin{tdocshowcase}[style = stripe, col-stripe = green, - col-text = purple] + col-text = purple, + before = Mon début, + after = Ma fin à moi] + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... +\end{tdocshowcase} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-input-stripe.tex} +\tdocshowcaseinput[style = stripe, + col-stripe = red, + col-text = LightCoral]% + {examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-rule-custom.tex} +\begin{tdocshowcase}[style = rule, + col-stripe = red, + col-text = orange!75!black, + before = Mon début, + after = Ma fin à moi] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} \end{filecontents*} @@ -884,13 +1252,106 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-showcase-nostripe.tex} -\begin{tdocshowcase}[nostripe] +\begin{filecontents*}[overwrite]{examples-showcase-stripe.tex} +\begin{tdocshowcase}[style = stripe] Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-showcase-input-default.tex} +\tdocshowcaseinput{examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-showcase-input-rule.tex} +\tdocshowcaseinput[style = rule]{examples-showcase-external.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexshow-options.tex} +\tdoclatexshow[style = stripe, + col-stripe = orange, + col-text = blue!70!black, + before = Rendu ci-après., + explain = Ce qui vient est coloré..., + after = Rendu fini.,] + {examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-ABC.tex} +\begin{tdoclatex}<\tdoctcb{sbs}> +$A = B + C$ +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-xyz.tex} +% Juste une démo. +$x y z = 1$ +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-std.tex} +\tdoclatexinput{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-strange.tex} +\begin{tdoclatex}[] +[Étrange... Ou pas !] +\end{tdoclatex} +OU. +\begin{tdoclatex}<> +<Étrange... Ou pas !> +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-ABC-custom.tex} +\begin{tdoclatex}% + [linenos, style = igor, showspaces]% + <\tdoctcb{sbs}, + attach boxed title to top left = {yshift = -9pt}, + fonttitle = \bfseries, + title = Modifications locales, + top = 10pt> +% Parfois utile, mais ne pas en abuser ! +$A = B + C$ +% Fin de cette démonstration. +\end{tdoclatex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-sbs.tex} +\tdoclatexinput<\tdoctcb{sbs}>{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-code.tex} +\tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-latexinput-option-perso.tex} +\tdoclatexinput[style = igor, showspaces]% + <colframe = purple, colback = red!5>% + {examples-listing-latex-xyz.tex} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-listing-latex-strange-bis.tex} +\begin{tdoclatex} +\string[Étrange... Ou pas !] +\end{tdoclatex} +OU. +\begin{tdoclatex} +\string<Étrange... Ou pas !> +\end{tdoclatex} +\end{filecontents*} + + % ======================== % % == SOURCE FOR THE DOC == % % ======================== % @@ -909,6 +1370,10 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \usepackage{tasks} \usepackage{pdfpages} +\includepdfset{ + pages=-, + fitpaper=true +} % Some useful commands. \newcommand\thisproj{\tdoccls{tutodoc}} @@ -921,48 +1386,12 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \newcommand\git{\trademark{git}} \newcommand\pdf{\trademark{PDF}} +\newcommand\brainfuck{\trademark{Brainfuck}} +\newcommand\lua{\trademark{Lua}} +\newcommand\perl{\trademark{Perl}} +\newcommand\python{\trademark{Python}} -% Source. -% * https://tex.stackexchange.com/a/604698/6880 - -\NewDocumentCommand{ \tdocbasicinputDOC }{ m }{% - Considérons le code suivant. - - \tdoclatexinput[code]{#1} - - Ceci produira ce qui suit. - - \input{#1} -} - - -% Source. -% * https://tex.stackexchange.com/a/604698/6880 - -\NewDocumentCommand{ \tdocextrarulerDOC }{ m }{% - \par - { - \centering - \color{green!50!black}% - \leavevmode - \kern.075\linewidth - \leaders\hrule height3.25pt\hfill\kern0pt - \footnotesize\itshape\bfseries\space\ignorespaces#1\unskip\space - \leaders\hrule height3.25pt\hfill\kern0pt - \kern.075\linewidth - \par - } -} - -\NewDocumentEnvironment{ tdocshowcaseDOC } - { O{ Début du rendu dans cette doc. } - O{ Fin du rendu dans cette doc. } }{ - \tdocextrarulerDOC{#1} - \nopagebreak\smallskip\nopagebreak -}{ - \nopagebreak\smallskip\nopagebreak - \tdocextrarulerDOC{#2} -} +\newcommand\pygmentsREF{\href{https://pygments.org/}{\trademark{Pygments}}} \NewDocumentCommand{\mailsubject}{m}% <-- Translate me! @@ -1035,7 +1464,7 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \title{La classe \texttt{tutodoc} \\ Documentation de type tutoriel} \author{Christophe, BAL} -\date{4 déc. 2024 - Version 1.7.0} +\date{18 déc. 2024 - Version 1.7.1} \maketitle @@ -1048,7 +1477,7 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \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. } - via un rendu sobre pour une lecture sur écran. + avec un rendu sobre pour une lecture sur écran. \smallskip @@ -1070,9 +1499,9 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... } 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. + The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected for a coding documentation. } - using a sober rendering for reading on screen. + with a sober rendering for reading on screen. \smallskip @@ -1090,67 +1519,52 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \subsection*{Derniers changements} \egroup -\begin{tdocbreak} - \item Mise en forme : la classe \tdoccls{scrartcl} remplace la vénérable \tdoccls{article}. Cela implique un meilleur positionnement des notes de marge avec les options retenues pour charger \tdoccls{scrartcl}. +\begin{tdocfix} + \item Documentation: les références aux outils pour indiquer des changements ont été incorrectement écrites comme caractéristiques des contenus colorés mis en avant. +\end{tdocfix} - \item Code \LaTeX\ : la macro \tdocmacro{tdocinlatex} a été renommée \tdocmacro{tdoclatexin}. - \item Les noms des clés pour les couleurs utiliseront des traits d'union lorsque cela sera nécessaire : cela implique les changements suivants. - % - \begin{enumerate} - \item Mise en avant colorée de contenus : l'option \tdoclatexin{colchges} des environnements a été renommée \tdoclatexin{col-chges}. +\begin{tdocbreak} + \item La macro \tdocmacro{tdocenv} et sa version étoilée ne proposent plus d'option. - \item Démonstration de codes \LaTeX\ : pour l'environnement \tdocenv*{tdocshowcase} et la macro \tdocmacro{tdocshowcaseinput}, les options \tdoclatexin{colstripe} et \tdoclatexin{coltext} ont été renommées \tdoclatexin{col-stripe} et \tdoclatexin{col-text}\,. - \end{enumerate} + \item Cas d'utilisation \LaTeX: la présentation par défaut est plus sobre, et des options permettent d'ajouter les lignes cadrantes, ou la bande colorée. Voir juste après. \end{tdocbreak} -\begin{tdocfix} - \item Mise en avant colorée de contenus : pour les \tdocmacro{newkeytheorem} utilisés avec le thème \tdoclatexin{draft}, il a fallu ajouter \tdoclatexin{postheadhook = \leavevmode} (ceci est nécessaire car le contenu peut juste être de type liste). -\end{tdocfix} - - \begin{tdocnew} - \item Documentation : ajout d'une section listant les dépendances. - - \item Options de classe. + \item Mise en forme de codes informatiques en plus de ceux spécifiquement en \LaTeX. % \begin{enumerate} - \item Les options qui ne sont pas spécifiques à \thisproj\ sont transmises à la classe chargée de la mise en forme générale. + \item Création de \tdocenv{tdoccode} et de \tdocmacro{tdoccodein}. - \item Les options \tdoclatexin{fontsize} et \tdoclatexin{DIV} de la classe \tdoccls{scrartcl} ne peuvent pas être utilisées, car leurs valeurs sont fixées par \thisproj. - \end{enumerate} + \item Pour les macros pour du code en ligne, et les environnements pour des blocs de code, des options de type \tdocpack{minted} s'indiquent à l'intérieur de crochet de manière traditionnelle: \tdoclatexin{[options minted]}\,. - \item La macro \tdocmacro{tdocinEN} respecte les règles linguistiques anglaises. + \item Pour les environnements pour des blocs de code, des options de type \tdocpack{tcolorbox} s'indiquent à l'intérieur de chevrons: \tdoclatexin{<options tcolorbox>}\,. - \item Mise en avant colorée de contenus. - % - \begin{enumerate} - \item Un nouvel environnement \tdocenv{tdoctodo} a été ajouté. - - \item Chaque environnement dispose d'une nouvelle option \tdoclatexin{col} pour la couleur du contenu indiquant les changements. + \item La nouvelle macro \tdocmacro{tdoctcb} permet d'utiliser des raccourcis pour les styles \tdocpack{tcolorbox} régulièrement utilisés. \end{enumerate} + + \item Documentation: une nouvelle section présente les outils de mise en forme de codes informatiques autres que les cas d'utilisation de \LaTeX. \end{tdocnew} \begin{tdocupdate} - \item Le thème \tdoclatexin{draft} et les changements : les environnements pour les types de changements n'mploient plus d'icones. - - \item Documentation : la galerie des thèmes utilise un meilleur exemple factice. -\end{tdocupdate} - + \item Les sous-sous-sections sont numérotées en lettres minuscules. - -\begin{tdoctech} - \item Organisation simplifiée des fichiers de configuration dans le projet final. + \item Thèmes. % \begin{enumerate} - \item Comme du \texttt{CSS} : emploi d'un fichier par thème avec des noms du type \texttt{tutodoc-bw.css.cls}\,. + \item Moins d'espace consommé. + + \item Les ombres ont une meilleure coloration. + + \item Pour tous les thèmes sauf le \tdoclatexin{draft}, le rayon des arcs des coins des cadres passe de \tdoclatexin{.75mm} à \tdoclatexin{.2pt}\,. + \item Cas d'utilisation de \LaTeX: avec le thème \tdoclatexin{color}, la couleur du fond passe de \tdoclatexin[bgcolor = yellow!4]{yellow!4} à \tdoclatexin{gray!5}. - \item Locale : utilisation de noms comme \texttt{tutodoc-fr.loc.cls}\,. + \item Dernières modifications: avec le thème \tdoclatexin{dark}, le texte \tdoclatexin{[Init]} produit par la macro \tdocmacro{tdocstartproj} utilise la même police que celle des titres des environnements pour indiquer des changements. \end{enumerate} -\end{tdoctech} +\end{tdocupdate} } @@ -1199,7 +1613,7 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{tasks} -\section{Mises en forme générales imposées} +\section{Réglages généraux} \subsection{Taille de la police et géométrie de la page} @@ -1207,7 +1621,7 @@ La classe \tdoccls{scrartcl} est chargée via l'option \tdoclatexin{fontsize = 1 \begin{tdocwarn} - Les macros pour dater et versionner présentées dans la section \ref{tutodoc-changes} ont besoin de réglages fixes pour la géométrie des pages et la taille de la police. + Les macros pour dater et versionner présentées dans la section \ref{tutodoc-changes} page \pageref{tutodoc-changes} ont besoin de réglages fixes pour la géométrie des pages et la taille de la police. \end{tdocwarn} @@ -1218,24 +1632,22 @@ Les réglages choisis sont directement visibles dans cette documentation. \subsection{Liens dynamiques} -Le package \tdocpack{hyperref} est importé, si ce n'est pas fait, et les réglages choisis portent juste sur les couleurs des liens relatifs aux citations, aux fichiers, aux liens internes, et enfin aux \verb#url# (cette couleur dépendra du thème choisi). +Le package \tdocpack{hyperref} est importé, si ce n'est pas fait, et les réglages choisis portent juste sur les couleurs des liens relatifs aux citations, aux fichiers, aux liens internes, et enfin aux \verb#url# (ces couleurs dépendent du thème choisi). \section{Quelle langue est utilisée par la classe \thisproj\ ?} -Cette documentation charge le package \tdocpack{babel} via \tdoclatexin|\usepackage[english]{babel}|\, un package que \thisproj\ ne charge pas. -En revanche, la classe \thisproj\ identifie \tdoclatexin|fr| comme la langue principale utilisée par \tdocpack{babel}.%. +Cette documentation charge le package \tdocpack{babel} via \tdoclatexin|\usepackage[french]{babel}|\, un package que \thisproj\ ne charge pas. +En revanche, la classe \thisproj\ identifie \tdoclatexin|fr| comme la langue principale utilisée par \tdocpack{babel}.% \footnote{ Techniquement, on utilise \tdoclatexin|\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{tasks}[label=\small\textbullet](3) \task \tdoclatexin|en| : anglais. \task \tdoclatexin|es| : espagnol. \task \tdoclatexin|fr| : français. \end{tasks} - \begin{tdocnote} @@ -1262,7 +1674,7 @@ Cool et top signifient \tdocinEN*{cool} et \tdocinEN{top}. \end{tdoclatex} -La macro \tdocmacro{tdocinEN} et sa version étoilée s'appuient sur \tdocmacro{tdocquote} : par exemple, \tdocquote{sémantique} s'obtient via \tdoclatexin|\tdocquote{sémantique}| . +La macro \tdocmacro{tdocinEN} et sa version étoilée s'appuient sur \tdocmacro{tdocquote} : par exemple, \tdocquote{sémantique} s'obtient via \tdoclatexin|\tdocquote{sémantique}|\,. \begin{tdocnote} @@ -1272,9 +1684,8 @@ La macro \tdocmacro{tdocinEN} et sa version étoilée s'appuient sur \tdocmacro{ Dans le contenu entre guillemets, les règles linguistiques anglaises sont respectées comme le montre l'exemple suivant. -\begin{tdoclatex} -Test: \tdocquote{OK?} - +\begin{tdoclatex}<\tdoctcb{sbs}> + Test: \tdocquote{OK?} \\ \tdocinEN{Test: \tdocquote{OK?}} \end{tdoclatex} @@ -1299,7 +1710,7 @@ Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \begin{tdocnote} - A la fin de ce document, après l'historique des changements, vous trouverez une galerie de cas d'utilisation de ces différents thèmes : se rendre à l'annexe page \pageref{tutodoc-theme-gallery}. + À la fin de ce document, après l'historique des changements, vous trouverez une galerie de cas d'utilisation de ces différents thèmes : se rendre à l'annexe page \pageref{tutodoc-theme-gallery}. \end{tdocnote} @@ -1323,10 +1734,10 @@ Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \addcontentsline{toc}{section}{Annexe -- Galerie des thèmes}% \egroup -\bigskip +\bigskip\bigskip \begin{tdocnote} - Chaque exemple est un \pdf\ de deux pages exactement qui a été directement inséré dans ce document (ne soyez donc pas surpris par les numéros de page). + Chaque exemple est un \pdf\ directement inséré dans ce document (ne soyez donc pas surpris par la numérotation des pages). \end{tdocnote} \newpage @@ -1341,25 +1752,13 @@ Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \immediate\write18{SOURCE_DATE_EPOCH=0 FORCE_SOURCE_DATE=1 latexmk -shell-escape -pdflatex gallery-showcase-draft} % The gallery starts here... -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-bw} +\includepdf{gallery-showcase-bw} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-color} +\includepdf{gallery-showcase-color} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-dark} +\includepdf{gallery-showcase-dark} -\includepdf[ - pages=1-2, - fitpaper=true -]{gallery-showcase-draft} +\includepdf{gallery-showcase-draft} } @@ -1370,7 +1769,7 @@ Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \section{Mettre en avant du contenu} \begin{tdocnote} - Les environnements présentés dans cette section + Les environnements présentés dans cette section\,% \footnote{ La mise en forme provient du package \tdocpack{keytheorems}. } @@ -1383,26 +1782,24 @@ Pour modifier la mise en forme générale, la classe \thisproj\ propose l'option \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 qui sera remis à zéro dès qu'une section de niveau au moins égale à une \tdoclatexin|\section| sera ouverte. + Tous les environnements présentés dans cette section partagent le même compteur qui sera remis à zéro dès que \tdoclatexin|\section| est employée. \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. +Des exemples numérotés s'indiquent via \tdocenv{tdocexa} qui propose un argument optionnel pour ajouter un mini-titre. Voici deux usages possibles. -\tdoclatexinput[sbs]{examples-admonitions-exa.tex} - +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-exa.tex} \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-admonitions-exa-leavevmode.tex} - +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-exa-leavevmode.tex} %\subsection{Du contenu dans le flot de la lecture} @@ -1412,8 +1809,7 @@ Voici deux usages possibles. Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'environnement \tdocenv*{tdocexa} comme le montre l'exemple suivant. -\tdoclatexinput[sbs]{examples-admonitions-rmk.tex} - +\tdoclatexinput<\tdoctcb{sbs}>{examples-admonitions-rmk.tex} \subsection{Du contenu tape-à-l'oeil} @@ -1421,7 +1817,7 @@ Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'enviro \begin{tdocnote} La mise en forme proposée ici est celle par défaut, mais d'autres sont possible en changeant de thème : voir la galerie de cas d'utilisation dans l'annexe page \pageref{tutodoc-theme-gallery}. - Quant aux icônes, elles sont obtenues via le package \tdocpack{fontawesome5}, et la macro \tdocmacro{tdocicon} gère l'espacement vis-à-vis du texte. + Quant aux icônes, elles sont obtenues via le package \tdocpack{fontawesome5} et la macro \tdocmacro{tdocicon} qui gère l'espacement vis-à-vis du texte.% \footnote{ Par exemple, \tdoclatexin|\fbox{\tdocicon{\faBed}{Fatigué}}| @@ -1436,18 +1832,16 @@ Tout se passe via \tdocenv{tdocrem} avec un fonctionnement identique à l'enviro L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'employer. -\tdoclatexinput[sbs]{examples-admonitions-tip.tex} - +\tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-tip.tex} \smallskip \begin{tdoctip} - Quelque fois, un contenu mis en avant peut se réduire à une liste. Dans ce cas, la mise en forme peut être améliorée comme suit où nous utilisons l'option \tdoclatexin{wide} du package \tdocpack{enumitem}. - - \tdoclatexinput[sbs]{examples-admonitions-leavevmode-items.tex} + Quelque fois, un contenu mis en avant peut se réduire à une liste. Dans ce cas, la mise en forme peut être améliorée comme suit où nous utilisons l'option \tdoclatexin{wide} du package \tdocpack{enumitem} qui est importé par cette documentation. + \tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-leavevmode-items.tex} \end{tdoctip} @@ -1461,19 +1855,18 @@ L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'e 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! + {L'environnement \tdocenv*{tdoccaut} sert à pointer quelque chose de délicat. 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! + {L'environnement \tdocenv*{tdocwarn} permet d'avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.}/% <-- Translate me! warn% } { \subsubsection{\sectitle} \desc - \tdoclatexinput[sbs]{examples-admonitions-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}, bottom = 3pt, top = 3pt>{examples-admonitions-\filename.tex} } @@ -1482,42 +1875,30 @@ L'environnement \tdocenv*{tdoctip} sert à donner des astuces. Voici comment l'e Voici ce qu'il est possible de taper de façon sémantique. -\begin{tdoclatex}[sbs] -\tdoccls{maclasse} sert à... \\ -\tdocpack{monpackage} est pour... \\ -\tdocmacro{unemacro} permet de... \\ -\tdocenv{env} produit... \\ -\tdocenv[{[opt1]<opt2>}]{env} \\ -Juste \tdocenv*{env}... \\ -Enfin \tdocenv*[{[opt1]<opt2>}]{env}... - % Pour les copier-coller. +\begin{tdoclatex}<\tdoctcb{sbs}> +\tdoccls{maclasse} sert à... \\ +\tdocpack{monpackage} est pour... \\ +\tdocmacro{unemacro} permet de... \\ +\tdocenv{env} produit... \\ +Juste \tdocenv*{env}... \end{tdoclatex} \begin{tdocrem} - Contrairement à \tdocmacro{tdoclatexin}, les macros \tdocmacro{tdocenv} et \tdocmacro{tdocenv*} ne colorent pas le texte produit. - De plus, \tdoclatexin{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin. + Contrairement à \tdocmacro{tdoclatexin}, les macros \tdocmacro{tdocmacro}, \tdocmacro{tdocenv} et \tdocmacro{tdocenv*} ne colorent pas le texte produit. + De plus, \tdoclatexin{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces sécables afin d'autoriser des retours à la ligne si besoin. \end{tdocrem} -\begin{tdocwarn} - 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} - - \section{Origine d'un préfixe ou d'un suffixe} Pour expliquer les noms retenus, rien de tel que d'indiquer et expliciter les courts préfixes et suffixes employés. Ceci se fait facilement comme suit. -\begin{tdoclatex}[sbs] -\tdocpre{sup} est relatif à... \\ -\tdocprewhy{sup.erbe} signifie... \\ +\begin{tdoclatex}<\tdoctcb{sbs}> +\tdocpre{sup} est relatif à... \\ +\tdocprewhy{sup.erbe} signifie... \\ \emph{\tdocprewhy{sup.er} pour...} \end{tdoclatex} @@ -1534,226 +1915,237 @@ Il est parfois utile d'obtenir directement le rendu d'un code dans la documentat -\subsection{Avec une bande colorée} +\subsection{Un rendu minimaliste par défaut} -\begin{tdocexa}[Avec les textes par défaut] - Il peut être utile de montrer un rendu réel directement dans un document. +\begin{tdocexa} + Il peut être utile de montrer un rendu réel directement dans un document.% \footnote{ Typiquement lorsque l'on fait une démo. } - Ceci se tape via \tdocenv{tdocshowcase} comme suit. + Ceci se tape via l'environnement \tdocenv*{tdocshowcase} comme suit. - \tdoclatexinput[code]{examples-showcase-default.tex} + \tdoclatexshow[explain = {On obtient alors le rendu suivant qui est la combinaison d'un faible espacement vertical et d'une simple importation.}]{examples-showcase-default.tex} +\end{tdocexa} - On obtient alors le rendu suivant. - \footnote{ - En coulisse, la bande est créée sans effort grâce au package \tdocpack{clrstrip}. - } - - \medskip +\begin{tdocrem} + La section \ref{tutodoc-listing-latexshow} page \pageref{tutodoc-listing-latexshow} explique comment obtenir, via la macro \tdocmacro{tdoclatexshow}, un code suivi de son rendu réel comme dans l'exemple précédent. +\end{tdocrem} - \input{examples-showcase-default.tex} -\end{tdocexa} +\begin{tdocwarn} + Avec les paramètres par défaut, si le code à formater commence par un crochet ouvrant, il faut utiliser l'une des astuces suivantes. + \tdoclatexshow[explain = {Ceci produira ce qui suit.}]{examples-showcase-hook.tex} +\end{tdocwarn} -\begin{tdocrem} - Voir la section \ref{tutodoc-latexshow} page \pageref{tutodoc-latexshow} pour obtenir facilement un code suivi de son rendu réel comme dans l'exemple précédent. -\end{tdocrem} +\subsection{Avec des lignes cadrantes} -\begin{tdocnote} - Les textes explicatifs s'adaptent à la langue détectée par \thisproj. -\end{tdocnote} +Pour rendre plus visible le code \LaTeX\ mis en forme, on peut faire appel au style \tdoclatexin{rule} comme dans les exemple suivants. -\begin{tdocexa}[Changer les couleurs et/ou les textes par défaut] - \leavevmode +\begin{tdocexa} + L'option \tdoclatexin{style = rule} permet d'obtenir ce qui suit ce qui suit où les textes ajoutés automatiquement s'adapteront à la langue repéré par \thisproj. - \tdoclatexinput[code]{examples-showcase-customized.tex} + \input{examples-showcase-rule.tex} +\end{tdocexa} - Ceci produira ce qui suit. +\begin{tdocexa}[Du texte et des couleurs modifiables] + On peut obtenir facilement l'horreur suivante. - \medskip + \input{examples-showcase-rule-custom.tex} - \input{examples-showcase-customized.tex} + Voici le code qui a été employé.% + \footnote{ + La section suivante va justifier le choix, a priori étrange, de \tdoclatexin{col-stripe} au lieu de \tdoclatexin{col-rule}\,. + } + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-rule-custom.tex} \end{tdocexa} \begin{tdocnote} - Dans l'exemple précédent, le texte utilise bien l'orange assombri proposé. Par contre, le rouge sert de base pour obtenir les couleurs utilisées pour la bande : les transformations utilisées dépendent du thème choisi.% + Dans l'exemple précédent, le texte utilise bien l'orange assombri proposé. Par contre, le rouge sert de base pour obtenir les couleurs utilisées pour les lignes cadrantes: les transformations utilisées dépendent du thème choisi.% \footnote{ Par exemple, les thèmes \tdoclatexin{bw} et \tdoclatexin{draft} ne tiennent pas compte de la clé \tdoclatexin{col-stripe} ! } % - Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est employée. + Il faut également savoir qu'en coulisse, la macro \tdocmacro{tdocruler} est employée, elle fonctionne comme suit. - \begin{tdoclatex}[std] - \tdocruler[red]{Un pseudo-titre décoré} + \begin{tdoclatex}<\tdoctcb{std}> +\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. - - \tdoclatexinput[code]{examples-showcase-hook.tex} - - - Ceci produira ce qui suit. -\end{tdocwarn} - -\input{examples-showcase-hook.tex} - - - -\subsection{Sans bande colorée} +\subsection{Avec une bande colorée} -Le rendu de \tdocenv{tdocshowcase} avec une bande colorée peut ne pas convenir, ou parfois ne pas être acceptable malgré le travail fait par \tdocpack{clrstrip}. -Il est possible de ne pas utiliser une bande colorée comme nous allons le voir tout de suite. +Il est des situations où l'on doit pouvoir clairement identifier un exemple de code \LaTeX\ mis en forme. Ceci est faisable comme le montrent les exemples suivants.% +\footnote{ + En coulisse, les bandes sont créées sans effort grâce au package \tdocpack{clrstrip}. +} \begin{tdocexa} - L'emploi de \tdocenv[{[nostripe]}]{tdocshowcase} demande de ne pas faire appel à \tdocpack{clrstrip}. - Voici un exemple d'utilisation. - - \tdoclatexinput[code]{examples-showcase-nostripe.tex} - - - Ceci produira ce qui suit. - - \medskip - - \input{examples-showcase-nostripe.tex} + L'option \tdoclatexin{style = stripe} fournit ce qui suit. + \input{examples-showcase-stripe.tex} \end{tdocexa} -\begin{tdocexa}[Changer les couleurs et/ou les textes par défaut] - \leavevmode - - \tdoclatexinput[code]{examples-showcase-nostripe-customized.tex} +\begin{tdocexa}[Du texte et des couleurs modifiables] + On peut produire facilement une belle horreur comme celle qui arrive. + \input{examples-showcase-stripe-custom.tex} - Ceci produira l'horreur suivante. - - \medskip - - \input{examples-showcase-nostripe-customized.tex} + Voici le code qui a été employé.% + \footnote{ + On comprend maintenant le choix de \tdoclatexin{col-stripe} au lieu de \tdoclatexin{col-rule}\,. + } + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-stripe-custom.tex} \end{tdocexa} \subsection{En important le code \LaTeX} -Pour obtenir des rendus en important le code depuis un fichier externe, au lieu de le taper, il suffit d'employer la macro \tdocmacro{tdocshowcaseinput} dont l'option reprend la syntaxe de celle de \tdocenv{tdocshowcase} et l'argument obligatoire correspond au chemin du fichier. - - -\begin{tdocexa} - Ce qui suit a été obtenu via \tdoclatexin+\tdocshowcaseinput{external.tex}+. - - \medskip - - \tdocshowcaseinput{examples-showcase-external.tex} +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 l'environnement \tdocenv*{tdocshowcase}, et l'argument obligatoire correspond au chemin du fichier. Voici des exemples d'utilisation. - \medskip - - Via \tdoclatexin+\tdocshowcaseinput[col-stripe = red, col-text = orange!75!black]{external.tex}+\,, on obtient le changement de couleur observable ci-après. +\foreach \exatitle/\style in { + {Usage standard}/% <-- Translate me! + {default}, + {Avec des lignes cadrantes}/% <-- Translate me! + {rule}, + {Une bande colorée}/% <-- Translate me! + {stripe}% +}{ + \begin{tdocexa}[\exatitle] + \leavevmode + \tdoclatexinput<\tdoctcb{code}>{examples-showcase-input-\style.tex} - \medskip + Ceci donne: - \tdocshowcaseinput[col-stripe = red, col-text = orange!75!black]{examples-showcase-external.tex} + \smallskip -\end{tdocexa} + \input{examples-showcase-input-\style.tex} + \end{tdocexa} +} \section{Cas d'utilisation en \LaTeX} +\label{tutodoc-listing-latex} -Documenter un package ou une classe se fait efficacement via des cas d'utilisation montrant à la fois du code et le résultat correspondant.% +Documenter un package, ou une classe, se fait efficacement via des cas d'utilisation montrant à la fois du code et le résultat correspondant.% \footnote{ - La mise en forme des codes se fait via le package \tdocpack{minted}. + La mise en forme des codes se fait via les packages \tdocpack{minted} et \tdocpack{tcolorbox}. } -%\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{tutodoc-listing-latex-inline} +\begin{tdocexa}[Usage standard] + La macro \tdocmacro{tdoclatexin}\,% + \footnote{ + Le nom de la macro \tdocmacro{tdoclatexin} 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}, ou bien comme une macro standard (voir la gestion des accolades dans le dernier cas ci-dessous). + Voici des exemples d'utilisation.% + \footnote{ + Une couleur de fond est volontairement utilisée pour subtilement faire ressortir les codes \tdoclatexin{\LaTeX}\,. + } -\subsection{Codes \tdocquote{en ligne}} -\label{tutodoc-listing-inline} + \begin{tdoclatex}<\tdoctcb{sbs}> +1: \tdoclatexin|$a^b = c$| \\ +2: \tdoclatexin+\tdoclatexin|$a^b = c$|+ \\ +3: \tdoclatexin{\tdoclatexin{$a^b = c$}} + \end{tdoclatex} +\end{tdocexa} -La macro \tdocmacro{tdoclatexin} -\footnote{ - Le nom de la macro \tdocmacro{tdoclatexin} 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} ou bien comme une macro standard (voir la gestion des accolades dans le dernier cas ci-dessous). -Voici des exemples d'utilisation. +\begin{tdocexa}[Des options possibles] + Comme la macro \tdocmacro{tdoclatexin} s'appuie sur \tdocpack{minted}, on peut utiliser toutes les options prises en compte par \tdocpack{minted}. + Voici des exemples d'utilisation. -\begin{tdoclatex}[sbs] - 1: \tdoclatexin|$a^b = c$| \\ - 2: \tdoclatexin+\tdoclatexin|$a^b = c$|+ \\ - 3: \tdoclatexin{\tdoclatexin{$a^b = c$}} -\end{tdoclatex} + \begin{tdoclatex}<\tdoctcb{sbs}> +1: \tdoclatexin[style = bw]{$a^b = c$} \\ +2: \tdoclatexin[style = igor, + showspaces]{$a^b = c$} + \end{tdoclatex} +\end{tdocexa} \begin{tdocnote} - La macro \tdocmacro{tdoclatexin} est utilisable dans une note de pied de page : voir ci-dessous. + La macro \tdocmacro{tdoclatexin} est utilisable dans une note de pied de page comme ci-dessous.% \footnote{ - \tdoclatexin+$minted = TOP$+ a été tapé \tdoclatexin|\tdoclatexin+$minted = TOP$+| dans cette note de bas de page.. + \tdoclatexin+$minted = TOP$+ a été tapé \tdoclatexin|\tdoclatexin+$minted = TOP$+| dans cette note de bas de page. } - De plus, une couleur de fond est volontairement utilisée pour subtilement faire ressortir les codes \tdoclatexin#\LaTeX#\,. \end{tdocnote} \subsection{Codes tapés directement} +\label{tutodoc-listing-latex-direct} \begin{tdocexa}[Face à face] - Via \tdocenv[{[sbs]}]{tdoclatex}, on affichera un code et son rendu côte à côte. - Indiquons que \tdoclatexin#sbs# est pour \tdocquote{\tdocprewhy{s.ide} \tdocprewhy{b.y} \tdocprewhy{s.ide}} soit \tdocinEN{côte à côte}. - \tdocbasicinputDOC{examples-listing-ABC.tex} + Afficher un code et son rendu côte à côte se fait comme suit où la macro \tdocmacro{tdoctcb} permet de juste taper \tdoclatexin{\tdoctcb{sbs}} au lieu de \tdoclatexin{listing side text} (\tdoclatexin#sbs# est pour \tdocquote{\tdocprewhy{s.ide} \tdocprewhy{b.y} \tdocprewhy{s.ide}}\,, soit \tdocinEN{côte à côte}, tandis que \tdoclatexin#tcb# est l'abréviation standard de \texttt{tcolorbox}). Bien noter l'emploi de chevrons, et non de crochets (nous revenons sur ceci un plus bas). + \tdoclatexshow{examples-listing-latex-ABC.tex} \end{tdocexa} \begin{tdocexa}[À la suite] - \tdocenv{tdoclatex} produit le résultat suivant qui correspond à l'option par défaut \tdoclatexin#std#\,. + \tdocenv{tdoclatex} produit le résultat suivant (ce réglage par défaut s'obtient aussi via l'emploi de \tdoclatexin#\tdoctcb{std}#).% \footnote{ \tdoclatexin{std} fait référence au comportement \tdocquote{standard} de \tdocpack{tcolorbox} vis à vis de la librairie \tdocpack{minted}. } \begin{tdoclatex} - $A = B + C$ +$A = B + C$ \end{tdoclatex} \end{tdocexa} \begin{tdocexa}[Juste le code] - Via \tdocenv[{[code]}]{tdoclatex}, on aura juste le code comme ci-après. + Via \tdoclatexin#\tdoctcb{code}#, on aura juste le code comme ci-après. - \begin{tdoclatex}[code] - $A = B + C$ + \begin{tdoclatex}<\tdoctcb{code}> +$A = B + C$ \end{tdoclatex} \end{tdocexa} -\begin{tdocwarn} - Avec la mise en forme par défaut, si le code commence par un crochet ouvrant, il faudra indiquer explicitement l'option par défaut. - \tdocbasicinputDOC{examples-listing-strange.tex} +\begin{tdocexa}[Personnaliser] + L'environnement \tdocenv*{tdoclatex} accepte deux types d'argument optionnel. + % + \begin{enumerate} + \item Entre de classiques crochets, on peut employer toute option prise en compte par \tdocpack{minted}. + \item Entre des chevrons, on peut employer toute option prise en compte par les environnements obtenus via \tdocpack{tcolorbox}. + \end{enumerate} - \smallskip + Par exemple, on peut faire les modifications suivantes si besoin.% + \footnote{ + Cette documentation utilise les options entre chevrons pour obtenir des rendus corrects de codes \LaTeX\ produisant des cadres ombrés : voir la section \ref{tutodoc-admonitions} page \pageref{tutodoc-admonitions}. + } - Une autre méthode consiste à utiliser la primitive \tdocmacro{string}. - \tdocbasicinputDOC{examples-listing-strange-bis.tex} + \tdoclatexshow{examples-listing-latex-ABC-custom.tex} +\end{tdocexa} + +\medskip + +\begin{tdocwarn} + Pour obtenir la mise en forme par défaut d'un code commençant par un crochet, ou un chevron, il faudra bidouiller un peu comme ci-dessous. + \tdoclatexshow{examples-listing-latex-strange.tex} + \smallskip + + Une autre méthode consiste à utiliser la primitive \tdocmacro{string} comme ci-après. + \tdoclatexshow{examples-listing-latex-strange-bis.tex} \end{tdocwarn} @@ -1762,114 +2154,172 @@ Voici des exemples d'utilisation. 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} - +\tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-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}. +La macro \tdocmacro{tdoclatexinput}, présentée ci-dessous, attend le chemin d'un fichier et propose le même système d'options entre crochets, ou entre chevrons, que l'environnement \tdocenv*{tdoclatex}. -\begin{tdocexa}[Face à face] - \leavevmode +\foreach \title/\extra/\fname in {% + {Face à face}/% + {}/% + sbs, + {À la suite}/% + { qui correspond aussi à l'option \tdoclatexin{\tdoctcb{std}}\,}/% + std,% + {Juste le code}/% + {}/% + code,% + {Personnaliser}/% + {}/% + perso% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexshow[explain=Ceci produit la mise en forme suivante\extra.]{examples-listing-latex-latexinput-option-\fname.tex} + \end{tdocexa} +} - \begin{tdoclatex}[code] -\tdoclatexinput[sbs]{examples-listing-xyz.tex} - \end{tdoclatex} - Ceci produit la mise en forme suivante. +\subsection{Codes importés et mis en situation} +\label{tutodoc-listing-latexshow} - \tdoclatexinput[sbs]{examples-listing-xyz.tex} +\begin{tdocnote} + Les textes par défaut de la macro \tdocmacro{tdoclatexshow} tiennent compte de la langue détectée par \thisproj. +\end{tdocnote} -\end{tdocexa} +\begin{tdocexa}[Mise en situation] + \tdoclatexin+\tdoclatexshow{examples-listing-xyz.tex}+ produit ce qui suit. -\begin{tdocexa}[À la suite] - \leavevmode + \smallskip - \begin{tdoclatex}[code] -\tdoclatexinput{examples-listing-xyz.tex} + \tdoclatexshow{examples-listing-latex-xyz.tex} +\end{tdocexa} - \end{tdoclatex} - Ceci produit la mise en forme suivante où l'option employée par défaut est \tdoclatexin#std#. +\begin{tdocexa}[Changer le texte explicatif] + Via la clé \tdoclatexin|explain|, on peut utiliser un texte personnalisé. Ainsi, \tdoclatexin|\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}| produira ce qui suit. - \tdoclatexinput{examples-listing-xyz.tex} + \smallskip + \tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-latex-xyz.tex} \end{tdocexa} -\begin{tdocexa}[Juste le code] - \leavevmode +\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 la section \ref{tutodoc-showcase} page \pageref{tutodoc-showcase}. + Voici un exemple illustrant ceci. - \begin{tdoclatex}[code] -\tdoclatexinput[code]{examples-listing-xyz.tex} + \medskip - \end{tdoclatex} + \tdoclatexinput<\tdoctcb{code}>{examples-listing-latex-latexshow-options.tex} - Ceci produit la mise en forme suivante. + \smallskip - \tdoclatexinput[code]{examples-listing-xyz.tex} + Ceci va produire ce qui suit. + + \smallskip + \input{examples-listing-latex-latexshow-options.tex} \end{tdocexa} +\section{Présenter du code informatique} -\subsection{Codes importés et mis en situation} -\label{tutodoc-latexshow} +Certains packages proposent des fonctionnalités nécessitant de coder un peu en \lua.% +\footnote{ + Pour les mathématiques, on peut citer \tdocpack{luacas} et \tdocpack{tkz-elements}. +} +Pour ces projets, la documentation doit pouvoir présenter des lignes de code \lua\,; c'est pour cette raison que \thisproj\ permet de faire cela aisément, et bien plus.% +\footnote{ + La mise en forme des codes étant faite via les packages \tdocpack{minted} et \tdocpack{tcolorbox}, les macros et les environnements présentés dans cette section permettent la mise en forme de codes dans tous les langages supportés par \pygmentsREF, un projet \python\ utilisé en coulisse par \tdocpack{minted}. +} -\begin{tdocexa}[Mise en situation] - \tdoclatexin+\tdoclatexshow{examples-listing-xyz.tex}+ produit ce qui suit. - \medskip +\begin{tdocimp} + Les outils de cette section permettent aussi de présenter du code \LaTeX, mais il ne faut pas les utiliser pour de simples cas d'utilisation, car les macros et les environnements présentées juste après servent à étudier du code, et non juste à l'employer : se reporter à la section \ref{tutodoc-listing-latex} page \pageref{tutodoc-listing-latex} pour faire appel aux bons outils pour la mise en forme de cas d'utilisation \LaTeX. +\end{tdocimp} - \begin{tdocshowcaseDOC} - \tdoclatexshow{examples-listing-xyz.tex} - \end{tdocshowcaseDOC} -\end{tdocexa} +\subsection{Codes \tdocquote{en ligne}} -\begin{tdocnote} - Les textes par défaut tiennent compte de la langue détectée par \thisproj. -\end{tdocnote} +La macro \tdocmacro{tdoccodein}\,% +\footnote{ + Le nom de la macro \tdocmacro{tdoccodein} vient de \tdocquote{\tdocprewhy{in.line} \tdocpre{code}} soit \tdocinEN{code en ligne}. +} +attend deux arguments : le 1\ier\ indique le langage de programmation, et le 2\ieme\ donne le code à mettre en forme. +Il est possible d'utiliser une option de fonctionnement identique à ce que propose \tdocmacro{tdoclatexin} : voir la section \ref{tutodoc-listing-latex-inline} page \pageref{tutodoc-listing-latex-inline}. +Voici des cas d'utilisation possibles.% +\footnote{ + Une couleur de fond est volontairement utilisée pour subtilement faire ressortir les codes mis en forme. + Par exemple, taper \tdoclatexin{\tdoccodein{py}{funny = "ah"*3}} produira \tdoccodein{py}{funny = "ah"*3}\,. +} +\begin{tdoclatex} +1: \tdoccodein{py}{print("OK" if i = 0 else "KO")} \\ +2: \tdoccodein[style = bw]{py}{print("OK" if i = 0 else "KO")} \\ +3: \tdoccodein[style = igor, showspaces]% + {py}{print("OK" if i = 0 else "KO")} +\end{tdoclatex} -\begin{tdocexa}[Changer le texte explicatif] - Via la clé \tdoclatexin|explain|, on peut utiliser un texte personnalisé. Ainsi, \tdoclatexin|\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}| produira ce qui suit. +\medskip - \medskip +\begin{tdocnote} + Sur la page \url{https://pygments.org/languages/} se trouve la liste complète des langages supportés avec leur nom court. + Par exemple, il est possible de mettre en forme du code \brainfuck\ comme cette séquence \tdoccodein{bf}{++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.} qui sert à afficher \tdoccodein{text}{Hello}\,. +\end{tdocnote} - \begin{tdocshowcaseDOC} - \tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex} - \end{tdocshowcaseDOC} -\end{tdocexa} +\subsection{Codes tapés directement} -\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{tutodoc-showcase} page \pageref{tutodoc-showcase}. - Voici un exemple illustrant ceci. +On peut taper directement du code dans un document \LaTeX\ via \tdocenv{tdoccode} qui attend un argument indiquant le langage de programmation, et d'éventuelles options entre crochets et/ou entre chevrons de fonctionnements identiques à ce que propose \tdocenv{tdoclatex} : voir la section \ref{tutodoc-listing-latex-direct} page \pageref{tutodoc-listing-latex-direct}.% +\footnote{ + Noter que la coloration des codes \LaTeX\ est correcte du point de vue lexical, mais fausse sémantiquement parlant. +} - \medskip - \tdoclatexinput[code]{examples-listing-latexshow-options.tex} +% Strings "..." in the source codes must also be translated. +\foreach \title/\lang in {% + {Fonctionnement standard}/% + perl,% + {Personnalisation ponctuelle du rendu}/% + lua% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexshow{examples-listing-full-hello-you-\lang} + \end{tdocexa} +} - \medskip +\subsection{Codes importés} - Ceci va produire ce qui suit. +La macro \tdocmacro{tdoccodeinput} attend le langage et le chemin d'un fichier à mettre en forme, et éventuellement d'options similaires à ce que propose l'environnement \tdocenv*{tdoccode}\,. - \medskip - \begin{tdocshowcaseDOC} - \input{examples-listing-latexshow-options.tex} +% Strings "..." in the source codes must also be translated. +\foreach \title/\lang in {% + {Fonctionnement standard}/% + hs,% + {Personnalisation ponctuelle du rendu}/% + tex% +}{ + \begin{tdocexa}[\title] + \leavevmode + \tdoclatexinput<\tdoctcb{code}>{examples-listing-full-input-hello-you-\lang} + + Ceci donne: - \end{tdocshowcaseDOC} -\end{tdocexa} + \input{examples-listing-full-input-hello-you-\lang} + \end{tdocexa} +} \section{Indiquer les changements} @@ -1882,22 +2332,20 @@ Afin de faciliter le suivi d'un projet, il est indispensable de fournir un histo \subsection{À quel moment ?} \label{tutodoc-changes-when} -On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas le numéro de version pourra éventuellement être daté. +On peut dater et/ou versionner quelque chose. \begin{tdocexa}[Dater des nouveautés] La macro \tdocmacro{tdocdate} permet d'indiquer une date dans la marge comme dans l'exemple suivant. \tdoclatexshow{examples-version-n-change-dating.tex} - \end{tdocexa} -\begin{tdocexa}[Versionner des nouveautés en les datant événtuellement] +\begin{tdocexa}[Versionner des nouveautés en les datant éventuellement] Associer un numéro de version à une nouveauté se fait via la macro \tdocmacro{tdocversion}, la couleur et la date étant des arguments optionnels. \tdoclatexshow{examples-version-n-change-versioning.tex} - \end{tdocexa} @@ -1905,7 +2353,6 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas L'exemple suivant montre qu'il faut placer une dates et/ou une version juste après un titre de paragraphe, et non avant. \tdoclatexshow{examples-version-n-change-para-title.tex} - \end{tdocexa} @@ -1913,7 +2360,6 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas Si besoin, on peut modifier le décalage vertical utilisé pour bien placer les dates et les versions dans la marge, la valeur par défaut étant $(-8\,\mathit{pt})$. \tdoclatexshow{examples-version-n-change-manual-setting.tex} - \end{tdocexa} @@ -1927,14 +2373,11 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas \begin{tdoccaut} - Seul l'emploi du format numérique \tdoclatexin+YYYY-MM-DD+ est vérifié, + Seul l'emploi du format numérique \tdoclatexin+YYYY-MM-DD+ est vérifié,% \footnote{ Techniquement, vérifier la validité d'une date, via \LaTeX3, ne présente pas de difficulté. } et ceci est un choix ! Pourquoi cela ? Tout simplement car dater et versionner des explications devrait se faire de façon semi-automatisée afin d'éviter tout bug humain. -% \footnote{ -% L'auteur de \thispack{} est entrain de mettre en place un ensemble d'outils permettant une telle semi-automatisation. -% }. \end{tdoccaut} @@ -1947,17 +2390,14 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas \begin{tdocnote} -\begin{tdocnew} - \item Info 1... - \item Info 2... -\end{tdocnew} -% Concernant les icônes, voir la note au début de la section \ref{tutodoc-admonitions} page \pageref{tutodoc-admonitions}. + Concernant les icônes, voir la note au début de la section \ref{tutodoc-admonitions} page \pageref{tutodoc-admonitions}. \end{tdocnote} \subsubsection{La sobriété avant tout} \foreach \exatitle/\filename in { +% Standard. {Juste pour la toute première version}/%<-- Translate me! first, {Pour les nouveautés}/% <-- Translate me! @@ -1974,7 +2414,7 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas todo, {Informations techniques}/% <-- Translate me! tech, - % +% Customized. {Thématiques aux choix avec une icône}/%<-- Translate me! user-choice-icon, {Thématiques aux choix sans icône}/% <-- Translate me! @@ -1983,8 +2423,7 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas \begin{tdocexa}[\exatitle] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-chges-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}>{examples-version-n-change-chges-\filename.tex} \end{tdocexa} } @@ -2002,26 +2441,24 @@ Il peut être utile de mettre en avant certains changements : ceci n'est faisabl \begin{tdocexa}[\exatitle] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-color-chges-\filename.tex} - + \tdoclatexinput<\tdoctcb{sbs}>{examples-version-n-change-color-chges-\filename.tex} \end{tdocexa} } \subsection{Le quoi et le quand} -Les clés optionnelles \tdoclatexin{col-chges}\,, \tdoclatexin{date} et \tdoclatexin{version} permettent de dater et versionner directement un changement d'un type particulier. Voici des exemples d'utilisation. +Les clés optionnelles \tdoclatexin{col-chges}\,, \tdoclatexin{date} et \tdoclatexin{version} permettent de dater et/ou versionner directement un changement d'un type particulier. Voici des exemples d'utilisation. \tdoclatexshow{examples-version-n-change-what-n-when.tex} - \section{Décoration} -Finissons cette documentation avec un petit outil de mise en forme qui rend de grands services. +Finissons cette documentation avec un petit outil de mise en forme qui peut rendre de grands services. -\begin{tdoclatex}[sbs] +\begin{tdoclatex}<\tdoctcb{sbs}> Bla, bla, bla... \tdocsep % Pratique pour délimiter. @@ -2071,7 +2508,7 @@ Ble, ble, ble... Les traductions sont organisées grosso-modo comme dans la figure \ref{tutodoc-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é. + Cette organisation était celle du 5 octobre 2024. } \textbf{Un peu plus bas, la section \ref{tutodoc-contrib-translate} donne les démarches à suivre pour ajouter de nouvelles traductions.} @@ -2095,7 +2532,7 @@ Ce dossier permet de savoir où en sont les traductions du point de vue du proje \subsubsection{Les fichiers \texttt{README.md} et \texttt{LICENSE.txt}} -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. +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 à propos des nouvelles traductions. @@ -2122,7 +2559,7 @@ Le fichier \texttt{LICENSE.txt} est bien nommé, tandis que le fichier \texttt{R \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. + Le dossier \verb#doc# est réservé aux documentations. Il contient des fichiers \verb#TEX# compilables directement pour une validation en temps réel des traductions faites. \end{tdocnote} @@ -2136,14 +2573,14 @@ Le fichier \texttt{LICENSE.txt} est bien nommé, tandis que le fichier \texttt{R \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. + Comme indiqué plus haut, il n'y a pas de besoin réel du côté du dossier \texttt{doc}. } -\paragraph{Méthode 1 : \git.} +\paragraph{Méthode 1 : utilisation de \git.} \begin{enumerate} - \item Obtenir tout le dossier du projet via \thisrepo\,. + \item Récupérer 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 @@ -2151,7 +2588,7 @@ Le fichier \texttt{LICENSE.txt} est bien nommé, tandis que le fichier \texttt{R {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#\,. + \item Une fois la traduction achevée dans le dossier \verb#it#, partager la via \thisrepo\ en usant d'un classique \verb#git push#\,. \end{enumerate} @@ -2189,6 +2626,59 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \small +\begin{tdocfix}[version = 1.7.1, date = 2024-12-18] + \item Documentation: les références aux outils pour indiquer des changements ont été incorrectement écrites comme caractéristiques des contenus colorés mis en avant. +\end{tdocfix} + + +\begin{tdocbreak} + \item La macro \tdocmacro{tdocenv} et sa version étoilée ne proposent plus d'option. + + \item Cas d'utilisation \LaTeX: la présentation par défaut est plus sobre, et des options permettent d'ajouter les lignes cadrantes, ou la bande colorée. Voir juste après. +\end{tdocbreak} + + +\begin{tdocnew} + \item Mise en forme de codes informatiques en plus de ceux spécifiquement en \LaTeX. + % + \begin{enumerate} + \item Création de \tdocenv{tdoccode} et de \tdocmacro{tdoccodein}. + + \item Pour les macros pour du code en ligne, et les environnements pour des blocs de code, des options de type \tdocpack{minted} s'indiquent à l'intérieur de crochet de manière traditionnelle: \tdoclatexin{[options minted]}\,. + + \item Pour les environnements pour des blocs de code, des options de type \tdocpack{tcolorbox} s'indiquent à l'intérieur de chevrons: \tdoclatexin{<options tcolorbox>}\,. + + \item La nouvelle macro \tdocmacro{tdoctcb} permet d'utiliser des raccourcis pour les styles \tdocpack{tcolorbox} régulièrement utilisés. + \end{enumerate} + + \item Documentation: une nouvelle section présente les outils de mise en forme de codes informatiques autres que les cas d'utilisation de \LaTeX. +\end{tdocnew} + + +\begin{tdocupdate} + \item Les sous-sous-sections sont numérotées en lettres minuscules. + + \item Thèmes. + % + \begin{enumerate} + \item Moins d'espace consommé. + + \item Les ombres ont une meilleure coloration. + + \item Pour tous les thèmes sauf le \tdoclatexin{draft}, le rayon des arcs des coins des cadres passe de \tdoclatexin{.75mm} à \tdoclatexin{.2pt}\,. + + \item Cas d'utilisation de \LaTeX: avec le thème \tdoclatexin{color}, la couleur du fond passe de \tdoclatexin[bgcolor = yellow!4]{yellow!4} à \tdoclatexin{gray!5}. + + \item Dernières modifications: avec le thème \tdoclatexin{dark}, le texte \tdoclatexin{[Init]} produit par la macro \tdocmacro{tdocstartproj} utilise la même police que celle des titres des environnements pour indiquer des changements. + \end{enumerate} +\end{tdocupdate} + +\tdocsep + + +% ------------------ % + + \begin{tdocbreak}[version = 1.7.0, date = 2024-12-04] \item Mise en forme : la classe \tdoccls{scrartcl} remplace la vénérable \tdoccls{article}. Cela implique un meilleur positionnement des notes de marge avec les options retenues pour charger \tdoccls{scrartcl}. @@ -2197,7 +2687,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \item Les noms des clés pour les couleurs utiliseront des traits d'union lorsque cela sera nécessaire : cela implique les changements suivants. % \begin{enumerate} - \item Mise en avant colorée de contenus : l'option \tdoclatexin{colchges} des environnements a été renommée \tdoclatexin{col-chges}. + \item Indiquer les derniers changements : l'option \tdoclatexin{colchges} des environnements a été renommée \tdoclatexin{col-chges}. \item Démonstration de codes \LaTeX\ : pour l'environnement \tdocenv*{tdocshowcase} et la macro \tdocmacro{tdocshowcaseinput}, les options \tdoclatexin{colstripe} et \tdoclatexin{coltext} ont été renommées \tdoclatexin{col-stripe} et \tdoclatexin{col-text}\,. \end{enumerate} @@ -2222,10 +2712,10 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \item La macro \tdocmacro{tdocinEN} respecte les règles linguistiques anglaises. - \item Mise en avant colorée de contenus. + \item Indiquer les derniers changements. % \begin{enumerate} - \item Un nouvel environnement \tdocenv{tdoctodo} a été ajouté. + \item Ajout de l'environnement \tdocenv{tdoctodo}\,. \item Chaque environnement dispose d'une nouvelle option \tdoclatexin{col} pour la couleur du contenu indiquant les changements. \end{enumerate} @@ -2233,7 +2723,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \begin{tdocupdate} - \item Le thème \tdoclatexin{draft} et les changements : les environnements pour les types de changements n'mploient plus d'icones. + \item Le thème \tdoclatexin{draft} et les changements : les environnements pour les derniers changements n'emploient plus d'icone. \item Documentation : la galerie des thèmes utilise un meilleur exemple factice. \end{tdocupdate} @@ -2244,10 +2734,10 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \item Organisation simplifiée des fichiers de configuration dans le projet final. % \begin{enumerate} - \item Comme du \texttt{CSS} : emploi d'un fichier par thème avec des noms du type \texttt{tutodoc-bw.css.cls}\,. + \item Emploi d'un fichier par thème avec des noms du type \texttt{tutodoc-*.css.cls}\,. - \item Locale : utilisation de noms comme \texttt{tutodoc-fr.loc.cls}\,. + \item Localisation : utilisation de noms comme \texttt{tutodoc-*.loc.cls}\,. \end{enumerate} \end{tdoctech} @@ -2258,7 +2748,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \begin{tdocnew}[version = 1.6.2, date = 2024-10-30] - \item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} ont un nouvel argument final facultatif \tdoclatexin{<voffset>} pour choisir un décalage vertical spécifique. + \item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} ont un nouvel argument final facultatif \tdoclatexin{<voffset>} pour modifier le décalage vertical. \item De meilleurs environnements pour indiquer les modifications apportées. \begin{enumerate} @@ -2292,7 +2782,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \begin{tdocbreak}[version = 1.6.0, date = 2024-10-27] - \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdoclatexin{color} a été renommée \tdoclatexin{col-stripe}. + \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdoclatexin{color} a été renommée \tdoclatexin{colstripe}. \item La macro \tdocmacro{tdoclinkcolor} devient la couleur \tdoclatexin{tutodoc@link@color} destinée à un usage interne. \end{tdocbreak} @@ -2303,7 +2793,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \item Journal des modifications : ajout de l'environnement \tdocenv*{tdoctech} pour les informations techniques. - \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdoclatexin{col-text} permet de changer aussi la couleur du texte. + \item L'environnement \tdocenv*{showcase} et ses descendants : la clé \tdoclatexin{coltext} permet de changer aussi la couleur du texte. \item Les nouvelles fonctionnalités ont été documentées. \end{tdocnew} @@ -2360,7 +2850,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \begin{tdocbreak}[version = 1.4.0, date = 2024-09-28] \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 via un compteur commun. + \item Mise en avant de contenus : les exemples et remarques, indiqués via les environnements \tdocenv*{tdocexa} et \tdocenv*{tdocrem}, sont numérotés via un compteur commun. \item La macro inutilisée \tdocmacro{tdocxspace} a été supprimée. \end{tdocbreak} @@ -2369,7 +2859,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \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. + \item Factorisation du code : la macro \tdocmacro{tdocicon} se charge de l'ajout d'icônes devant du texte. \end{tdocnew} @@ -2456,7 +2946,7 @@ La participation en tant que codeuse, ou codeur, se fait via le dépôt \thisrep \begin{tdocnew}[version = 1.1.0, date = 2024-01-06] \item Journal des changements : deux nouveaux environnements. \begin{enumerate} - \item \tdocenv{tdocbreak} pour les \tdocquote{bifurcations}\,, soit les modifications non rétrocompatibles. + \item \tdocenv{tdocbreak} pour les \tdocquote{bifurcations}\,, c'est-à-dire les modifications non rétrocompatibles. \item \tdocenv{tdocprob} pour les problèmes repérés. \end{enumerate} diff --git a/Master/texmf-dist/tex/latex/tutodoc/DEPENDS.yaml b/Master/texmf-dist/tex/latex/tutodoc/DEPENDS.yaml deleted file mode 100644 index 1b8260eaad0..00000000000 --- a/Master/texmf-dist/tex/latex/tutodoc/DEPENDS.yaml +++ /dev/null @@ -1,27 +0,0 @@ -# ----------------------------------------------------------- # -# -- File generated automatically by TeXoptidep. -- # -# -- -- # -# -- WARNING! The alphabetical order used does not reflect -- # -# -- the order used in the source code. -- # -# ----------------------------------------------------------- # - -class: - - scrartcl - -package: - - clrstrip - - csquotes - - fontawesome5 - - geometry - - hyperref - - inputenc - - keytheorems - - marginnote - - minted - - tcolorbox - -library: - tcolorbox: - - breakable - - minted - - skins diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-bw.css.cls b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-bw.css.cls index cad88f64de4..4dc1296f243 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-bw.css.cls +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-bw.css.cls @@ -1,28 +1,16 @@ -% -- COLORFUL HIGHLIGHTING OF CONTENT -- % - -\NewExpandableDocumentCommand{\tutodoc@build@title@color}{m}{% - white% -} - -\NewExpandableDocumentCommand{\tutodoc@build@upper@color}{m}{% - \tdocdarkcolor[40]{Gray}% -} - -\NewExpandableDocumentCommand{\tutodoc@build@back@color}{m}{% - \tdoclightcolor[10]{Gray}% -} - -\NewExpandableDocumentCommand{\tutodoc@build@frame@color}{m}{% - Gray!75!black!45% -} - -\colorlet{tutodoc@admonition@shadow@color}{Gray!15} +% ================= % +% == ADMONITIONS == % +% ================= % +% ------------------------- % +% -- ICONS & ENV. COLORS -- % +% ------------------------- % \ExplSyntaxOn %%% -% We use two ''prop'' variables to factorize the code just after. +% We use two ''prop'' variables to associate each \env to its icon +% and color. %%% \prop_new:N \g__tutodoc_focus_color_prop \prop_new:N \g__tutodoc_focus_icon_prop @@ -46,12 +34,94 @@ \ExplSyntaxOff +% ------------------ % +% -- EXTRA COLORS -- % +% ------------------ % + +\NewExpandableDocumentCommand{\tutodoc@build@title@color}{m}{% + white% +} + +\NewExpandableDocumentCommand{\tutodoc@build@upper@color}{m}{% + \tdocdarkcolor[40]{Gray}% +} + +\NewExpandableDocumentCommand{\tutodoc@build@back@color}{m}{% + \tdoclightcolor[10]{Gray}% +} + +\NewExpandableDocumentCommand{\tutodoc@build@frame@color}{m}{% + Gray!75!black!45% +} + +\colorlet{tutodoc@admonition@shadow@color}{Gray!15} + + +% ----------------------- % +% -- VERTICAL SPACINGS -- % +% ----------------------- % + +\newcommand{\tutodoc@admonition@space@above}{\medskipamount} +\newcommand{\tutodoc@admonition@space@below}{\medskipamount} + + + +% ========================= % +% == LISTINGS - AGNOSTIC == % +% ========================= % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % + +\newcommand{\tutodoc@code@style}{friendly_grayscale} + +\colorlet{tutodoc@code@back@color}{gray!5} +\colorlet{tutodoc@code@text@color}{black} -% :: LEXER USED :: % + +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % + +\colorlet{tutodoc@code@frame@color}{darkgray} + +\newcommand{\tutodoc@code@left@len}{3pt} +\newcommand{\tutodoc@code@right@len}{3pt} +\newcommand{\tutodoc@code@top@len}{1.5pt} +\newcommand{\tutodoc@code@bottom@len}{1.5pt} + +\newcommand{\tutodoc@code@arc@len}{2pt} + +\newcommand{\tutodoc@code@left@rule@len}{1pt} +\newcommand{\tutodoc@code@right@rule@len}{1pt} +\newcommand{\tutodoc@code@top@rule@len}{1pt} +\newcommand{\tutodoc@code@bottom@rule@len}{1pt} + +\colorlet{tutodoc@code@shadow@color}{Gray!25} + +\newcommand{\tutodoc@code@shadow@xshift@len}{.75mm} +\newcommand{\tutodoc@code@shadow@yshift@len}{-.75mm} +\newcommand{\tutodoc@code@shadow@offset@len}{0mm} + +\colorlet{tutodoc@code@segment@color}{gray} + + + +% ====================== % +% == LISTINGS - LATEX == % +% ====================== % + +% ---------------- % +% -- LEXER USED -- % +% ---------------- % \newcommand{\tutodoc@latex@lexer}{latex} -% :: INLINE LATEX MACRO :: % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % \newcommand{\tutodoc@latex@style}{friendly_grayscale} @@ -59,23 +129,26 @@ \colorlet{tutodoc@latex@text@color}{black} -% :: THE TCOLORBOX LISTING STYLE :: % +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % \colorlet{tutodoc@latex@frame@color}{darkgray} -\newcommand{\tutodoc@latex@left@len}{1mm} -\newcommand{\tutodoc@latex@right@len}{1mm} -\newcommand{\tutodoc@latex@top@len}{1mm} -\newcommand{\tutodoc@latex@bottom@len}{1mm} +\newcommand{\tutodoc@latex@left@len}{3pt} +\newcommand{\tutodoc@latex@right@len}{3pt} +\newcommand{\tutodoc@latex@top@len}{1.5pt} +\newcommand{\tutodoc@latex@bottom@len}{1.5pt} -\newcommand{\tutodoc@latex@arc@len}{.75mm} +\newcommand{\tutodoc@latex@arc@len}{2pt} \newcommand{\tutodoc@latex@left@rule@len}{1pt} \newcommand{\tutodoc@latex@right@rule@len}{1pt} \newcommand{\tutodoc@latex@top@rule@len}{1pt} \newcommand{\tutodoc@latex@bottom@rule@len}{1pt} -\colorlet{tutodoc@latex@shadow@color}{black!30} +\colorlet{tutodoc@latex@shadow@color}{Gray!25} + \newcommand{\tutodoc@latex@shadow@xshift@len}{.75mm} \newcommand{\tutodoc@latex@shadow@yshift@len}{-.75mm} \newcommand{\tutodoc@latex@shadow@offset@len}{0mm} @@ -84,19 +157,25 @@ -% -- TEXT AND PAGE COLORS -- % +% ========================== % +% == TEXT AND PAGE COLORS == % +% ========================== % \colorlet{tutodoc@page@color}{white} \colorlet{tutodoc@text@color}{black} -% -- LINKS COLOR -- % +% ================= % +% == LINKS COLOR == % +% ================= % \definecolor{tutodoc@link@color}{named}{DimGray} -% -- SHOWCASE -- % +% ============== % +% == SHOWCASE == % +% ============== % \NewExpandableDocumentCommand{\tutodoc@showcase@rule@color}{}{% black% @@ -120,14 +199,22 @@ -% -- VERSION & CHANGES -- % +% ======================= % +% == VERSION & CHANGES == % +% ======================= % + +% -------------------- % +% -- DATE & VERSION -- % +% -------------------- % \NewExpandableDocumentCommand{\tutodoc@changes@when@color}{}{% gray% } -% -- ICONS -- % +% --------------------------- % +% -- ENVS FOR CHANGES MADE -- % +% --------------------------- % \newcommand{\tutodoc@changes@start@project@icon}{\faAnchor} diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-color.css.cls b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-color.css.cls index 8bcf1d0db00..50f46702e7f 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-color.css.cls +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-color.css.cls @@ -1,4 +1,42 @@ -% -- COLORFUL HIGHLIGHTING OF CONTENT -- % +% ================= % +% == ADMONITIONS == % +% ================= % + +% ------------------------- % +% -- ICONS & ENV. COLORS -- % +% ------------------------- % + +\ExplSyntaxOn + +%%% +% We use two ''prop'' variables to associate each \env to its icon +% and color. +%%% +\prop_new:N \g__tutodoc_focus_color_prop +\prop_new:N \g__tutodoc_focus_icon_prop + +\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, +} + +\ExplSyntaxOff + + +% ------------------ % +% -- EXTRA COLORS -- % +% ------------------ % \NewExpandableDocumentCommand{\tutodoc@build@title@color}{m}{% white% @@ -20,66 +58,101 @@ #1!75!black!45% } -\colorlet{tutodoc@admonition@shadow@color}{black!30} +\colorlet{tutodoc@admonition@shadow@color}{Gray!17} -\ExplSyntaxOn +% ----------------------- % +% -- VERTICAL SPACINGS -- % +% ----------------------- % -%%% -% We use two ''prop'' variables to factorize the code just after. -%%% -\prop_new:N \g__tutodoc_focus_color_prop -\prop_new:N \g__tutodoc_focus_icon_prop +\newcommand{\tutodoc@admonition@space@above}{\medskipamount} +\newcommand{\tutodoc@admonition@space@below}{\medskipamount} -\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, -} -\ExplSyntaxOff +% ========================= % +% == LISTINGS - AGNOSTIC == % +% ========================= % +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % +\newcommand{\tutodoc@code@style}{pastie} -% :: LEXER USED :: % +\colorlet{tutodoc@code@back@color}{gray!5} +\colorlet{tutodoc@code@text@color}{black} + + +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % + +\colorlet{tutodoc@code@frame@color}{darkgray} + +\newcommand{\tutodoc@code@left@len}{3pt} +\newcommand{\tutodoc@code@right@len}{3pt} +\newcommand{\tutodoc@code@top@len}{1.5pt} +\newcommand{\tutodoc@code@bottom@len}{1.5pt} + +\newcommand{\tutodoc@code@arc@len}{2pt} + +\newcommand{\tutodoc@code@left@rule@len}{1pt} +\newcommand{\tutodoc@code@right@rule@len}{1pt} +\newcommand{\tutodoc@code@top@rule@len}{1pt} +\newcommand{\tutodoc@code@bottom@rule@len}{1pt} + +\colorlet{tutodoc@code@shadow@color}{Gray!25} + +\newcommand{\tutodoc@code@shadow@xshift@len}{.75mm} +\newcommand{\tutodoc@code@shadow@yshift@len}{-.75mm} +\newcommand{\tutodoc@code@shadow@offset@len}{0mm} + +\colorlet{tutodoc@code@segment@color}{gray} + + + +% ====================== % +% == LISTINGS - LATEX == % +% ====================== % + +% ---------------- % +% -- LEXER USED -- % +% ---------------- % \newcommand{\tutodoc@latex@lexer}{latex} -% :: INLINE LATEX MACRO :: % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % \newcommand{\tutodoc@latex@style}{pastie} -\colorlet{tutodoc@latex@back@color}{yellow!4} +\colorlet{tutodoc@latex@back@color}{gray!5} \colorlet{tutodoc@latex@text@color}{black} -% :: THE TCOLORBOX LISTING STYLE :: % +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % \colorlet{tutodoc@latex@frame@color}{darkgray} -\newcommand{\tutodoc@latex@left@len}{1mm} -\newcommand{\tutodoc@latex@right@len}{1mm} -\newcommand{\tutodoc@latex@top@len}{1mm} -\newcommand{\tutodoc@latex@bottom@len}{1mm} +\newcommand{\tutodoc@latex@left@len}{3pt} +\newcommand{\tutodoc@latex@right@len}{3pt} +\newcommand{\tutodoc@latex@top@len}{1.5pt} +\newcommand{\tutodoc@latex@bottom@len}{1.5pt} -\newcommand{\tutodoc@latex@arc@len}{.75mm} +\newcommand{\tutodoc@latex@arc@len}{2pt} \newcommand{\tutodoc@latex@left@rule@len}{1pt} \newcommand{\tutodoc@latex@right@rule@len}{1pt} \newcommand{\tutodoc@latex@top@rule@len}{1pt} \newcommand{\tutodoc@latex@bottom@rule@len}{1pt} -\colorlet{tutodoc@latex@shadow@color}{black!30} +\colorlet{tutodoc@latex@shadow@color}{Gray!25} + \newcommand{\tutodoc@latex@shadow@xshift@len}{.75mm} \newcommand{\tutodoc@latex@shadow@yshift@len}{-.75mm} \newcommand{\tutodoc@latex@shadow@offset@len}{0mm} @@ -88,19 +161,25 @@ -% -- TEXT AND PAGE COLORS -- % +% ========================== % +% == TEXT AND PAGE COLORS == % +% ========================== % \colorlet{tutodoc@page@color}{white} \colorlet{tutodoc@text@color}{black} -% -- LINKS COLOR -- % +% ================= % +% == LINKS COLOR == % +% ================= % \colorlet{tutodoc@link@color}{NavyBlue!85!white} -% -- SHOWCASE -- % +% ============== % +% == SHOWCASE == % +% ============== % \NewExpandableDocumentCommand{\tutodoc@showcase@rule@color}{}{% black% @@ -124,14 +203,22 @@ -% -- VERSION & CHANGES -- % +% ======================= % +% == VERSION & CHANGES == % +% ======================= % + +% -------------------- % +% -- DATE & VERSION -- % +% -------------------- % \NewExpandableDocumentCommand{\tutodoc@changes@when@color}{}{% \tdoclightcolor[60]{DarkBlue}% } -% -- ICONS -- % +% --------------------------- % +% -- ENVS FOR CHANGES MADE -- % +% --------------------------- % \newcommand{\tutodoc@changes@start@project@icon}{\faAnchor} diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-dark.css.cls b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-dark.css.cls index 765081697d0..867264c1a17 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-dark.css.cls +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-dark.css.cls @@ -1,4 +1,42 @@ -% -- COLORFUL HIGHLIGHTING OF CONTENT -- % +% ================= % +% == ADMONITIONS == % +% ================= % + +% ------------------------- % +% -- ICONS & ENV. COLORS -- % +% ------------------------- % + +\ExplSyntaxOn + +%%% +% We use two ''prop'' variables to associate each \env to its icon +% and color. +%%% +\prop_new:N \g__tutodoc_focus_color_prop +\prop_new:N \g__tutodoc_focus_icon_prop + +\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, +} + +\ExplSyntaxOff + + +% ------------------ % +% -- EXTRA COLORS -- % +% ------------------ % \NewExpandableDocumentCommand{\tutodoc@build@title@color}{m}{% \tdocdarkcolor[95]{white}% @@ -20,42 +58,74 @@ \tdocdarkcolor[65]{#1}% } -\colorlet{tutodoc@admonition@shadow@color}{black!68} +\colorlet{tutodoc@admonition@shadow@color}{black!80} -\ExplSyntaxOn +% ----------------------- % +% -- VERTICAL SPACINGS -- % +% ----------------------- % -%%% -% We use two ''prop'' variables to factorize the code just after. -%%% -\prop_new:N \g__tutodoc_focus_color_prop -\prop_new:N \g__tutodoc_focus_icon_prop +\newcommand{\tutodoc@admonition@space@above}{\medskipamount} +\newcommand{\tutodoc@admonition@space@below}{\medskipamount} -\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, -} -\ExplSyntaxOff +% ========================= % +% == LISTINGS - AGNOSTIC == % +% ========================= % +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % +\newcommand{\tutodoc@code@style}{github-dark} -% :: LEXER USED :: % +\colorlet{tutodoc@code@back@color}{\tdocdarkcolor[30]{white}} +\colorlet{tutodoc@code@text@color}{\tdocdarkcolor[80]{white}} + + +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % + +\colorlet{tutodoc@code@frame@color}{darkgray} + +\newcommand{\tutodoc@code@left@len}{3pt} +\newcommand{\tutodoc@code@right@len}{3pt} +\newcommand{\tutodoc@code@top@len}{1.5pt} +\newcommand{\tutodoc@code@bottom@len}{1.5pt} + +\newcommand{\tutodoc@code@arc@len}{2pt} + +\newcommand{\tutodoc@code@left@rule@len}{1pt} +\newcommand{\tutodoc@code@right@rule@len}{1pt} +\newcommand{\tutodoc@code@top@rule@len}{1pt} +\newcommand{\tutodoc@code@bottom@rule@len}{1pt} + +\colorlet{tutodoc@code@shadow@color}{black!80} + +\newcommand{\tutodoc@code@shadow@xshift@len}{.75mm} +\newcommand{\tutodoc@code@shadow@yshift@len}{-.75mm} +\newcommand{\tutodoc@code@shadow@offset@len}{0mm} + +\colorlet{tutodoc@code@segment@color}{gray} + + + +% ====================== % +% == LISTINGS - LATEX == % +% ====================== % + +% ---------------- % +% -- LEXER USED -- % +% ---------------- % \newcommand{\tutodoc@latex@lexer}{latex} -% :: INLINE LATEX MACRO :: % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % \newcommand{\tutodoc@latex@style}{github-dark} @@ -63,23 +133,26 @@ \colorlet{tutodoc@latex@text@color}{\tdocdarkcolor[80]{white}} -% :: THE TCOLORBOX LISTING STYLE :: % +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % \colorlet{tutodoc@latex@frame@color}{darkgray} -\newcommand{\tutodoc@latex@left@len}{1mm} -\newcommand{\tutodoc@latex@right@len}{1mm} -\newcommand{\tutodoc@latex@top@len}{1mm} -\newcommand{\tutodoc@latex@bottom@len}{1mm} +\newcommand{\tutodoc@latex@left@len}{3pt} +\newcommand{\tutodoc@latex@right@len}{3pt} +\newcommand{\tutodoc@latex@top@len}{1.5pt} +\newcommand{\tutodoc@latex@bottom@len}{1.5pt} -\newcommand{\tutodoc@latex@arc@len}{.75mm} +\newcommand{\tutodoc@latex@arc@len}{2pt} \newcommand{\tutodoc@latex@left@rule@len}{1pt} \newcommand{\tutodoc@latex@right@rule@len}{1pt} \newcommand{\tutodoc@latex@top@rule@len}{1pt} \newcommand{\tutodoc@latex@bottom@rule@len}{1pt} -\colorlet{tutodoc@latex@shadow@color}{black!30} +\colorlet{tutodoc@latex@shadow@color}{black!80} + \newcommand{\tutodoc@latex@shadow@xshift@len}{.75mm} \newcommand{\tutodoc@latex@shadow@yshift@len}{-.75mm} \newcommand{\tutodoc@latex@shadow@offset@len}{0mm} @@ -88,19 +161,25 @@ -% -- TEXT AND PAGE COLORS -- % +% ========================== % +% == TEXT AND PAGE COLORS == % +% ========================== % \colorlet{tutodoc@page@color}{black} \colorlet{tutodoc@text@color}{\tdocdarkcolor[80]{white}} -% -- LINKS COLOR -- % +% ================= % +% == LINKS COLOR == % +% ================= % \definecolor{tutodoc@link@color}{HTML}{9591A6} -% -- SHOWCASE -- % +% ============== % +% == SHOWCASE == % +% ============== % \NewExpandableDocumentCommand{\tutodoc@showcase@rule@color}{}{% white% @@ -124,14 +203,22 @@ -% -- VERSION & CHANGES -- % +% ======================= % +% == VERSION & CHANGES == % +% ======================= % + +% -------------------- % +% -- DATE & VERSION -- % +% -------------------- % \NewExpandableDocumentCommand{\tutodoc@changes@when@color}{}{% \tdoclightcolor[60]{cyan}% } -% -- ICONS -- % +% --------------------------- % +% -- ENVS FOR CHANGES MADE -- % +% --------------------------- % \newcommand{\tutodoc@changes@start@project@icon}{\faAnchor} diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-draft.css.cls b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-draft.css.cls index d20943ab291..3798f815be6 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-draft.css.cls +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-draft.css.cls @@ -1,9 +1,16 @@ -% -- COLORFUL HIGHLIGHTING OF CONTENT -- % +% ================= % +% == ADMONITIONS == % +% ================= % + +% -------------------------------------- % +% -- ONY CLASSICAL THEOREM-LIKE \ENVS -- % +% -------------------------------------- % \ExplSyntaxOn %%% -% We use a ''seq'' variable to factorize the code just after. +% Without icons and colors, we just use a ''seq'' variable to give +% all the suffixes for the environments concerned. %%% \seq_new:N \g__tutodoc_focus_color_seq @@ -18,12 +25,72 @@ \ExplSyntaxOff +% ----------------------- % +% -- VERTICAL SPACINGS -- % +% ----------------------- % + +\newcommand{\tutodoc@admonition@space@above}{2pt plus 2pt} +\newcommand{\tutodoc@admonition@space@below}{2pt plus 2pt} + + + +% ========================= % +% == LISTINGS - AGNOSTIC == % +% ========================= % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % + +\codenolexertrue +\newcommand{\tutodoc@code@style}{default} + +\colorlet{tutodoc@code@back@color}{white} +\colorlet{tutodoc@code@text@color}{black} + + +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % + +\colorlet{tutodoc@code@frame@color}{darkgray} + +\newcommand{\tutodoc@code@left@len}{2pt} +\newcommand{\tutodoc@code@right@len}{2pt} +\newcommand{\tutodoc@code@top@len}{0pt} +\newcommand{\tutodoc@code@bottom@len}{0pt} + +\newcommand{\tutodoc@code@arc@len}{0pt} + +\newcommand{\tutodoc@code@left@rule@len}{1pt} +\newcommand{\tutodoc@code@right@rule@len}{0pt} +\newcommand{\tutodoc@code@top@rule@len}{0pt} +\newcommand{\tutodoc@code@bottom@rule@len}{0pt} + +\colorlet{tutodoc@code@shadow@color}{black} + +\newcommand{\tutodoc@code@shadow@xshift@len}{0mm} +\newcommand{\tutodoc@code@shadow@yshift@len}{0mm} +\newcommand{\tutodoc@code@shadow@offset@len}{0mm} -% :: LEXER USED :: % +\colorlet{tutodoc@code@segment@color}{black} + + + +% ====================== % +% == LISTINGS - LATEX == % +% ====================== % + +% ---------------- % +% -- LEXER USED -- % +% ---------------- % \newcommand{\tutodoc@latex@lexer}{text} -% :: INLINE LATEX MACRO :: % + +% ----------------- % +% -- INLINE CODE -- % +% ----------------- % \newcommand{\tutodoc@latex@style}{default} @@ -31,14 +98,16 @@ \colorlet{tutodoc@latex@text@color}{black} -% :: THE TCOLORBOX LISTING STYLE :: % +% -------------------------------- % +% -- FRAMED LISTING (tcolorbox) -- % +% -------------------------------- % \colorlet{tutodoc@latex@frame@color}{darkgray} -\newcommand{\tutodoc@latex@left@len}{1mm} -\newcommand{\tutodoc@latex@right@len}{1mm} -\newcommand{\tutodoc@latex@top@len}{1mm} -\newcommand{\tutodoc@latex@bottom@len}{1mm} +\newcommand{\tutodoc@latex@left@len}{2pt} +\newcommand{\tutodoc@latex@right@len}{2pt} +\newcommand{\tutodoc@latex@top@len}{0pt} +\newcommand{\tutodoc@latex@bottom@len}{0pt} \newcommand{\tutodoc@latex@arc@len}{0pt} @@ -48,6 +117,7 @@ \newcommand{\tutodoc@latex@bottom@rule@len}{0pt} \colorlet{tutodoc@latex@shadow@color}{black} + \newcommand{\tutodoc@latex@shadow@xshift@len}{0mm} \newcommand{\tutodoc@latex@shadow@yshift@len}{0mm} \newcommand{\tutodoc@latex@shadow@offset@len}{0mm} @@ -56,19 +126,39 @@ -% -- TEXT AND PAGE COLORS -- % +% ========================== % +% == TEXT AND PAGE COLORS == % +% ========================== % \colorlet{tutodoc@page@color}{white} \colorlet{tutodoc@text@color}{black} -% -- LINKS COLOR -- % +% ================ % +% == LINK COLOR == % +% ================ % \definecolor{tutodoc@link@color}{named}{black} +% ======================= % +% == VERTICAL SPACINGS == % +% ======================= % + +\setlength{\parskip}{0.5pt plus 1pt} + +\RedeclareSectionCommands[ + runin = false, + afterindent = false, + beforeskip = .25\baselineskip, + afterskip = 5pt +]{section, subsection, subsubsection} -% -- SHOWCASE -- % + + +% ============== % +% == SHOWCASE == % +% ============== % \NewExpandableDocumentCommand{\tutodoc@showcase@rule@color}{}{% black% @@ -92,28 +182,41 @@ -% -- VERSION & CHANGES -- % +% ======================= % +% == VERSION & CHANGES == % +% ======================= % + +% -------------------- % +% -- DATE & VERSION -- % +% -------------------- % \NewExpandableDocumentCommand{\tutodoc@changes@when@color}{}{% black% } -% -- (NO) ICONS -- % +% --------------------------- % +% -- ENVS FOR CHANGES MADE -- % +% --------------------------- % -\newcommand{\tutodoc@changes@start@project@icon}{} +%%% +% The draft theme doesn't use any icon. +%%% + +% \newcommand{\tutodoc@changes@start@project@icon}{} \ExplSyntaxOn -\prop_new:N \g__tutodoc_topic_change_prop -\prop_set_from_keyval:Nn \g__tutodoc_topic_change_prop { - break = , - fix = , - new = , - prob = , - tech = , - update = , - todo = , +\seq_new:N \g__tutodoc_topic_change_seq + +\seq_set_from_clist:Nn \g__tutodoc_topic_change_seq { + break , + fix , + new , + prob , + tech , + update, + todo , } \ExplSyntaxOff diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls b/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls index a85dd64b60e..fe1f0b52e42 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc.cls @@ -9,18 +9,14 @@ \ProvidesExplClass {tutodoc} - {2024-12-04} % Creation: 2023-11-29 - {1.7.0} + {2024-12-18} % Creation: 2023-11-29 + {1.7.1} {This package proposes tools for writing "human friendly" documentations of LaTeX packages.} -% =================== % -% == PACKAGES USED == % -% =================== % - -% ------------- % -% -- OPTIONS -- % -% ------------- % +% ================== % +% == \CLS OPTIONS == % +% ================== % %%% % refs:: @@ -36,6 +32,10 @@ { \msg_see_documentation_text:n { tutodoc } } +%%% +% The theme is identified by the following macro that can be changed +% when the class is loaded. +%%% \newcommand{\tutodoc@theme}{color} @@ -82,17 +82,17 @@ \ExplSyntaxOff -% ------------------------------------------------- % -% -- OPTIONS FOR PACKAGES IMPORTED BY OTHER ONES -- % -% ------------------------------------------------- % +% =============================================== % +% == OPTIONS FOR \PACKS IMPORTED BY OTHER ONES == % +% =============================================== % -% xcolor is loaded by minted and tcolorbox. +% ''xcolor'' will be loaded by ''minted'' and ''tcolorbox'' below. \PassOptionsToPackage{svgnames}{xcolor} -% ------------- % -% -- IMPORTS -- % -% ------------- % +% ============= % +% == IMPORTS == % +% ============= % \RequirePackage{geometry} @@ -102,7 +102,8 @@ \RequirePackage{clrstrip} -% Before the tcolorbox library minted. +% Special settings for ''minted'' need to be done before the loading +% of the ''tcolorbox'' library ''minted''. \RequirePackage[highlightmode = immediate] {minted} @@ -129,13 +130,9 @@ \RequirePackage{csquotes} -% =============== % -% == MAIN CODE == % -% =============== % - -% --------------------- % -% -- LOCALE SETTINGS -- % -% --------------------- % +% ===================== % +% == LOCALE SETTINGS == % +% ===================== % \ExplSyntaxOn @@ -149,39 +146,41 @@ { \msg_see_documentation_text:n { tutodoc } } -% Management of English composition rules. -\newcommand{\tutodoc@use@english}{\relax} - % Babel requires colon management for our translations. \newcommand{\tutodoc@colon}{:} \AtBeginDocument{ -% Babel is used. +%%% +% Settings if ''babel'' \pack is used. +%%% \@ifpackageloaded{babel}{ -% We must take care of colons and spacing. +% We must take care of spacings with colons. \iflanguage{french}{ \renewcommand{\tutodoc@colon}{\babelshorthand{:}} }{} }{} -% Polyglossia is used. +%%% +% Settings if ''polyglossia'' \pack is used. +%%% \@ifpackageloaded{polyglossia}{ -% If polyglossia is used, we must load english if necessary +% If ''polyglossia'' is used, we must load english if necessary % (see the ''\tutodoc@use@english'' macro below). \iflanguageloaded{english}{}{ \setotherlanguage{english} } }{}% +% Standard way to find the \lang to use. \newcommand{\tdoclang}{\BCPdata{language}} % We must take care of English rules for English contents. - \renewcommand\tutodoc@use@english{% + \newcommand\tutodoc@use@english{% \foreignlanguage{english}% } -% If the lang is not supported, we emit a warning and just turn -% to the english language. +% If the \lang is not supported, we emit a warning and just use +% the english language. \makeatletter \InputIfFileExists{tutodoc-\tdoclang.loc.cls}{}{ @@ -198,9 +197,9 @@ \ExplSyntaxOff -% ----------------------- % -% -- GEOMETRY SETTINGS -- % -% ----------------------- % +% =================== % +% == PAGE GEOMETRY == % +% =================== % \geometry{ top = 1.9cm, @@ -215,17 +214,13 @@ \setlength{\parindent}{0cm} -% --------------- % -% -- TOC & Co. -- % -% --------------- % - -\ifcsundef{chapter}% - {}% - {\renewcommand{\thechapter}{\Alph{chapter}}} +% ================== % +% == TITLES & TOC == % +% ================== % \renewcommand{\thesection}{\Roman{section}} \renewcommand{\thesubsection}{\arabic{subsection}} -\renewcommand{\thesubsubsection}{\roman{subsubsection}} +\renewcommand{\thesubsubsection}{\alph{subsubsection}} % Source % * https://tex.stackexchange.com/a/558025/6880 @@ -246,12 +241,10 @@ subparagraph } -\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section} - -% --------------------------- % -% -- COLOR TRANSFORMATIONS -- % -% --------------------------- % +% =========================== % +% == COLOR TRANSFORMATIONS == % +% =========================== % %%% % prototype:: @@ -277,9 +270,9 @@ \NewExpandableDocumentCommand{\tdoclightcolor}{ O{5} m }{#2!#1} -% ----------- % -% -- ICONS -- % -% ----------- % +% =========== % +% == ICONS == % +% =========== % %%% % prototype:: @@ -294,9 +287,54 @@ } -% ----------- % -% -- THEME -- % -% ----------- % +% ============== % +% == LISTINGS == % +% ============== % + +%%% +% We use a \std \latex boolean to switch on or off lexers for listings +% (this allows the ''draft'' mode to display listings in verbatim). +%%% +\newif\ifcodenolexer +\codenolexerfalse + + +\ExplSyntaxOn + +%%% +% prototype:: +% #1 : (style-abbrev) +% a shortcut for a \tcolorbox styling command. +% @ #1 in [code, sbs, std] +% +% In the following easy-to-understand macro, we use one fictive \tcolorbox +% style such as to indicate an unknown ''tutodoc'' shortcut style. For example, +% this will give the following message if the user type ''MISTYPED-STYLE''. +% +% term:: +% Package pgfkeys Error: I do not know the key '/tcb/[[tutodoc : tdoclatex +% bad option "MISTYPED-STYLE"]]' and I am going to ignore it. Perhaps you +% misspelled it. +% +% See the pgfkeys package documentation for explanation. +%%% + +\NewExpandableDocumentCommand{\tdoctcb}{ m }{ + \str_case:nnF { #1 } { + { sbs } { listing ~ side ~ text } + { code } { listing ~ only } + { std } { listing ~ and ~ text } + } { + [[tutodoc ~ : ~ LaTeX ~ listing ~ illegal ~ style ~ "#1"]] + } +} + +\ExplSyntaxOff + + +% ============================== % +% == THEME - GENERAL SETTINGS == % +% ============================== % \input{tutodoc-\tutodoc@theme.css.cls} @@ -312,9 +350,10 @@ } -% ------------- % -% -- QUOTING -- % -% ------------- % + +% ============= % +% == QUOTING == % +% ============= % %%% % prototype:: @@ -328,9 +367,9 @@ } -% ------------------------------ % -% -- EXPLAINING ENGLISH NAMES -- % -% ------------------------------ % +% ============================== % +% == EXPLAINING ENGLISH WORDS == % +% ============================== % %%% % prototype:: @@ -361,13 +400,14 @@ } -% ----------------------------------- % -% -- SOBER HIGHLIGHTING OF CONTENT -- % -% ----------------------------------- % -% :::::::::::::::::::::: % -% :: EXAMPLE & REMARK :: % -% :::::::::::::::::::::: % +% =========================== % +% == HIGHLIGHTING CONTENTS == % +% =========================== % + +% ---------------------- % +% -- EXAMPLE & REMARK -- % +% ---------------------- % \ExplSyntaxOn @@ -382,6 +422,14 @@ %%% +% Themes define specific vertical spacings. +%%% +\newkeytheoremstyle{tutodoc@admonition@exa@style}{ + spaceabove = \tutodoc@admonition@space@below, + spacebelow = \tutodoc@admonition@space@below +} + +%%% % prototype:: % :action: looping over ''\g__tutodoc_focus_std_seq'' to build new % numbered theorems sharing the same section level counter. @@ -393,11 +441,13 @@ \newkeytheorem{tdoc#1}[ name = \use:c { tutodoc@trans@#1@title }, within = section, + style = tutodoc@admonition@exa@style ] } { \newkeytheorem{tdoc#1}[ name = \use:c { tutodoc@trans@#1@title }, numberlike = tdocexa, + style = tutodoc@admonition@exa@style ] } @@ -407,10 +457,9 @@ \ExplSyntaxOff -% -------------------------------------- % -% -- COLORFUL HIGHLIGHTING OF CONTENT -- % -% -------------------------------------- % - +% ----------------- % +% -- ADMONITIONS -- % +% ----------------- % %%% % note:: @@ -422,16 +471,17 @@ % 1) ''\g__tutodoc_focus_color_seq'' is to use a dedicated basic theorem % (this should be only useful for the draft theme). % +% % warning:: % The variables should be defined inside the themes! -%%% -\ifcsundef{g__tutodoc_focus_color_seq}{ -%%% -% source:: +% +% +% refs:: % + https://tex.stackexchange.com/a/727022/6880 % + https://tex.stackexchange.com/a/682332/6880 % + https://tex.stackexchange.com/a/623232/6880 %%% +\ifcsundef{g__tutodoc_focus_color_seq}{ \tcbset{ tutodoc-focus-color-style/.style = { % General. @@ -448,6 +498,7 @@ % Padding. left = 3pt, right = 3pt, + arc = 2pt, % Frame. shadow = {.75mm}{-.75mm}{0mm}{tutodoc@admonition@shadow@color}, } @@ -461,7 +512,7 @@ % 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'' +% we use a \tcolorbox style given to the ''\newkeytheorem'' % macro from the ''keytheorems'' \pack, and icons from the % ''fontawesome5'' \pack. %%% @@ -487,7 +538,8 @@ \seq_map_inline:Nn \g__tutodoc_focus_color_seq { \newkeytheorem{tdoc#1}[ name = \use:c { tutodoc@trans@#1@title }, - numberlike = tdocexa, + numberlike = tdocexa,, + style = tutodoc@admonition@exa@style, % Some hooks... preheadhook = \small, postheadhook = \leavevmode, @@ -499,9 +551,10 @@ \ExplSyntaxOff -% ---------------------------------------------- % -% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- % -% ---------------------------------------------- % + +% ========================================= % +% == \PACKS, \CLSS, MACROS & \ENVS NAMES == % +% ========================================= % %%% % prototype:: @@ -541,65 +594,53 @@ %%% % prototype:: -% #1 : (env-options) -% hard typed options with the good delimiters -% #2 : (env-name) +% #1 : (env-name) % the name of an environment % % :extra: this macro has a star version. % -% Here are the four kind of outputs. +% Here are the different outputs available. % % 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 +% 2) ''\tdocenv*{myenv}'' prints % verb::''myenv''. %%% -% -% Cleaner code from https://tex.stackexchange.com/a/703379/6880 . -\NewDocumentCommand{\tdocenv}{ s O{} m }{% +\NewDocumentCommand{\tdocenv}{ s m }{% \IfBooleanTF{#1}{% - \texttt{#3}% + \texttt{#2}% }{% - \texttt{\string\begin\string{#3\string}#2 % +% Source: https://tex.stackexchange.com/a/703379/6880 . + \texttt{\string\begin\string{#2\string} % \!\!...\@\!\!\! % - \string\end\string{#3\string}}% + \string\end\string{#2\string}}% }% } -% ------------------------- % -% -- EXPLAINING PREFIXES -- % -% ------------------------- % +% ========================= % +% == 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... :: % -% :::::::::::::::::::: % +% -------------------- % +% -- PREFIX FROM... -- % +% -------------------- % \seq_new:N \l__tutodoc_prewhy_parts_seq \int_new:N \l__tutodoc_prewhy_nbparts_int \tl_new:N \l__tutodoc_pretext_tl \tl_new:N \l__tutodoc_posttext_tl + %%% % prototype:: % #1 : (pre.fix) @@ -636,9 +677,9 @@ \ExplSyntaxOff -% ::::::::::::::::::::: % -% :: JUST ONE PREFIX :: % -% ::::::::::::::::::::: % +% --------------------- % +% -- JUST ONE PREFIX -- % +% --------------------- % %%% % prototype:: @@ -656,14 +697,10 @@ } -% ------------------------ % -% -- GENERAL FORMATTING -- % -% ------------------------ % - -% :::::::::::::::::::::::: % -% :: TEXT INSIDE A RULE :: % -% :::::::::::::::::::::::: % +% ======================== % +% == TEXT BETWEEN RULES == % +% ======================== % \ExplSyntaxOn @@ -686,8 +723,10 @@ % cf::''this post ; % https://tex.stackexchange.com/a/604708/6880''. %%% - -\NewDocumentCommand{\tdocruler}{ O{\tutodoc@showcase@rule@color} m }{ +\NewDocumentCommand{\tdocruler}{ + O{\tutodoc@showcase@rule@color} + m +}{ \par { \centering @@ -713,9 +752,13 @@ \ExplSyntaxOff -% ::::::::::::::::::::::::::: % -% :: INTERNAL ENVIRONMENTS :: % -% ::::::::::::::::::::::::::: % +% ============== % +% == SHOWCASE == % +% ============== % + +% --------------------------- % +% -- INTERNAL ENVIRONMENTS -- % +% --------------------------- % %%% % prototype:: @@ -726,28 +769,26 @@ % #3 : (color) % one color used to set the one for the decorated texts printed % corresponding to the two first arguments. -% #4 : (text color) -% color of the content -% #5 : (rule color builder) +% #4 : (rule color builder) % the macro used to build the color from the user's rule color % % :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@showcase@basic}{ m m m m m }{% - \tdocruler[#5{#3}]{#1}% - \nopagebreak\medskip\nopagebreak\color{#4}% +\NewDocumentEnvironment{tutodoc@showcase@rules}{ m m m m }{% + \tdocruler[#4{#3}]{#1}% + \nopagebreak\medskip\nopagebreak% }{% \nopagebreak\medskip\nopagebreak% - \tdocruler[#5{#3}]{#2}% + \tdocruler[#4{#3}]{#2}% } %%% % prototype:: -% #1 .. #5 : :see: env.tutodoc@showcase@basic -% #6 : (back color builder) +% #1 .. #4 : :see: env.tutodoc@showcase@rules +% #5 : (back color builder) % the macro used to build the color from the user's back color % % :action: this environment adds a page-width colored stripe in the @@ -756,27 +797,26 @@ % produced by the macro ''\tdocruler'' such as to stress the % start and the end of the content. %%% - -\NewDocumentEnvironment{tutodoc@showcase@colorstrip}{ m m m m m m }{ - \begin{colorstrip}{#6{#3}}% - \begin{tutodoc@showcase@basic}{#1}{#2}{#3}{#4}{#5}% +\NewDocumentEnvironment{tutodoc@showcase@colorstrip}{ m m m m m }{ + \begin{colorstrip}{#5{#3}}% + \begin{tutodoc@showcase@rules}{#1}{#2}{#3}{#4}% }{% - \end{tutodoc@showcase@basic}% + \end{tutodoc@showcase@rules}% \end{colorstrip} } \ExplSyntaxOn -% ::::::::::::::::::::::: % -% :: SETTING SOME KEYS :: % -% ::::::::::::::::::::::: % +% ----------------------- % +% -- 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_stripe_color_tl -\tl_new:N \l_tutodoc_showcase_text_color_tl -\bool_new:N \l_tutodoc_showcase_no_stripe_bool +\tl_new:N \g_tutodoc_showcase_style_tl +\tl_new:N \l_tutodoc_showcase_before_tl +\tl_new:N \l_tutodoc_showcase_after_tl +\tl_new:N \l_tutodoc_showcase_stripe_color_tl +\tl_new:N \l_tutodoc_showcase_text_color_tl %%% @@ -788,14 +828,19 @@ % after : the descriptive text after the real output %%% \keys_define:nn { tutodoc / showcase } { +% Style? + style .choices:nn = { + minimal, + rule, + stripe + } { + \tl_gset:Nx \g_tutodoc_showcase_style_tl {#1} + }, % Colors. col-stripe .tl_set:N = \l_tutodoc_showcase_stripe_color_tl, col-stripe .initial:n = \tutodoc@showcase@stripe@color, col-text .tl_set:N = \l_tutodoc_showcase_text_color_tl, col-text .initial:n = \tutodoc@showcase@text@color, -% Stripe? - nostripe .bool_set:N = \l_tutodoc_showcase_no_stripe_bool, - nostripe .initial:n = false, % Texts. before .tl_set:N = \l_tutodoc_showcase_before_tl, before .initial:n = \tutodoc@trans@latex@show@start, @@ -804,13 +849,13 @@ } -% :::::::::::::::::::::::::::::: % -% :: SHOWCASE FROM TYPED CODE :: % -% :::::::::::::::::::::::::::::: % +% ------------------------------ % +% -- SHOWCASE FROM TYPED CODE -- % +% ------------------------------ % % prototype:: % #1 : (key-val options) -% :see: \keys_define:nn { tutodoc / showcase } +% :see: l3keys(tutodoc / showcase) % % :action: this \env formats \latex code, given as an argument, % by framing it with texts decorated by ''\tdocruler'', @@ -819,42 +864,53 @@ % It is also possible to have a coloured strip of the width % of the page in the background of the content. % -% :see: env.tutodoc@showcase@basic , +% :see: env.tutodoc@showcase@rules , % env.tutodoc@showcase@colorstrip %%% \NewDocumentEnvironment{tdocshowcase}{ O{} }{ \group_begin: + \tl_gset:Nn \g_tutodoc_showcase_style_tl {minimal} \keys_set:nn { tutodoc / showcase } { #1 } - \bool_if:NTF \l_tutodoc_showcase_no_stripe_bool { - \begin{tutodoc@showcase@basic} - { \tl_use:N \l_tutodoc_showcase_before_tl } - { \tl_use:N \l_tutodoc_showcase_after_tl } - { \tl_use:N \l_tutodoc_showcase_stripe_color_tl } - { \tl_use:N \l_tutodoc_showcase_text_color_tl } - { \tutodoc@showcase@build@rule@color } - }{ - \begin{tutodoc@showcase@colorstrip} - { \tl_use:N \l_tutodoc_showcase_before_tl } - { \tl_use:N \l_tutodoc_showcase_after_tl } - { \tl_use:N \l_tutodoc_showcase_stripe_color_tl } - { \tl_use:N \l_tutodoc_showcase_text_color_tl } - { \tutodoc@showcase@build@rule@color } - { \tutodoc@showcase@build@back@color } + \str_case:Nn { \g_tutodoc_showcase_style_tl } { + { minimal } { + \smallskip\par + } + { rule } { + \smallskip + \begin{tutodoc@showcase@rules} + { \tl_use:N \l_tutodoc_showcase_before_tl } + { \tl_use:N \l_tutodoc_showcase_after_tl } + { \tl_use:N \l_tutodoc_showcase_stripe_color_tl } + { \tutodoc@showcase@build@rule@color } + } + { stripe } { + \begin{tutodoc@showcase@colorstrip} + { \tl_use:N \l_tutodoc_showcase_before_tl } + { \tl_use:N \l_tutodoc_showcase_after_tl } + { \tl_use:N \l_tutodoc_showcase_stripe_color_tl } + { \tutodoc@showcase@build@rule@color } + { \tutodoc@showcase@build@back@color } + } } + + \color{ \tl_use:N \l_tutodoc_showcase_text_color_tl } }{ - \bool_if:NTF \l_tutodoc_showcase_no_stripe_bool { - \end{tutodoc@showcase@basic} - }{ + \str_case:Nn { \g_tutodoc_showcase_style_tl } { + { rule } { + \end{tutodoc@showcase@rules} + } + { stripe } { \end{tutodoc@showcase@colorstrip} } + } \group_end: } -% :::::::::::::::::::::::: % -% :: SHOWCASE FROM FILE :: % -% :::::::::::::::::::::::: % +% ------------------------ % +% -- SHOWCASE FROM FILE -- % +% ------------------------ % \tl_new:N \l__tutodoc_showcase_options_tl @@ -867,84 +923,53 @@ % the path of a file %%% \NewDocumentCommand{\tdocshowcaseinput}{ O{} m }{ - \group_begin: - \keys_set_known:nnN { tutodoc / showcase } - { #1 } - \l__tutodoc_showcase_options_tl - - \exp_last_unbraced:NNV \tdocshowcase [\l__tutodoc_showcase_options_tl] - \input{#2} - \endtdocshowcase - \group_end: + \begin{tdocshowcase}[#1] + \input{#2} + \end{tdocshowcase} } \ExplSyntaxOff -% -------------------- % -% -- LATEX EXAMPLES -- % -% -------------------- % - -% :::::::::::::::::::::::::::::::::::::::::::::: % -% :: STYLES OF THE LISTING ENV. AND THE MACRO :: % -% :::::::::::::::::::::::::::::::::::::::::::::: % +% ==================== % +% == LATEX EXAMPLES == % +% ==================== % -% :::::::::::::::::::::::: % -% :: INLINE LATEX MACRO :: % -% :::::::::::::::::::::::: % +% ----------------------------- % +% -- INLINE LATEX CODE MACRO -- % +% ----------------------------- % %%% -% See the \doc of the macro ''\newmintinline'' from the package ''minted'' +% See the \doc of the macro ''\newmintinline'' from the package \minted % to have \infos about the macro ''tdoclatexin''. %%% -\newmintinline[tdoclatexin]{\tutodoc@latex@lexer}{% - bgcolor = tutodoc@latex@back@color,% - style/.expand once = \tutodoc@latex@style % <-- This needs minted3! +\newmintinline[tdoclatexin]{\tutodoc@latex@lexer}{ + bgcolor = tutodoc@latex@back@color, + style/.expand once = \tutodoc@latex@style } -% ::::::::::::::::::::::::::::::::::: % -% :: TCOLORBOX LISTING ENVIRONMENT :: % -% ::::::::::::::::::::::::::::::::::: % - -\ExplSyntaxOn +% ------------------------------------------------ % +% -- MINTED/TCOLORBOX LATEX LISTING ENVIRONMENT -- % +% ------------------------------------------------ % %%% % prototype:: -% #1 : (tdoclatex-style) -% a style of formatting for a \latex listing and its output. -% -% :see: macro.tdoclatex , -% macro.tdoclatexinput +% #1 : (minted-like-options) +% a list of legal \minted options. +% #2 : (tcolorbox-styling-commands) +% you can override the default \tcolorbox settings with the help +% of the macro ''\tdoctcb''. % -% 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. +% :see: macro.tdoctcb % -% term:: -% Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option -% "MISTYPED-STYLE"' and I am going to ignore it. Perhaps you misspelled it. -% -% See the pgfkeys package documentation for explanation. -%%% -\NewExpandableDocumentCommand{\tutodoc@latex@listing@format@option}{ m }{ - \str_case:nnF { #1 } { - { sbs } { listing ~ side ~ text } - { code } { listing ~ only } - { std } { listing ~ and ~ text } - } { tdoclatex ~ bad ~ option ~ "#1" } -} - -\ExplSyntaxOff - -%% -% source:: +% refs:: % + https://tex.stackexchange.com/a/604821/6880 % + https://tex.stackexchange.com/a/327983/6880 -%% +%%% \tcbset{ - tutodoc-latex-listing-style/.style = { + tutodoc-latex-listing-style/.style 2 args = { % General. minted language/.expand once = \tutodoc@latex@lexer, minted style/.expand once = \tutodoc@latex@style, @@ -956,6 +981,7 @@ colupper = tutodoc@latex@text@color, collower = tutodoc@latex@text@color, % Padding. + boxsep = 0pt, left = \tutodoc@latex@left@len, right = \tutodoc@latex@right@len, bottom = \tutodoc@latex@bottom@len, @@ -976,58 +1002,62 @@ dash pattern = {on 5pt off 2.5pt}, line width = .75pt }, - #1 +% Extra minted otpions. + minted options = {#1}, +% Extra tcolorbox styles. + #2 }, } %%% % 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] +% #1 : (minted-like-options) +% :see: tcbset(tutodoc-latex-listing-style) +% #2 : (tcolorbox-styling-commands) +% :see: tcbset(tutodoc-latex-listing-style) % % note:: % See the \doc of the macro ''\newtcblisting'' from the package -% ''tcolorbox'' to have \infos about the environment ''tdoclatex''. +% \tcolorbox to have \infos about the environment ''tdoclatex''. %%% -\newtcblisting{tdoclatex}[1][std]{% - tutodoc-latex-listing-style = \tutodoc@latex@listing@format@option{#1} +\NewTCBListing{tdoclatex}{ O{} D<>{} }{% + tutodoc-latex-listing-style = {#1}{#2} } -% :::::::::::::::::::::::::::::::::::::: % -% :: TCOLORBOX IMPORTED LISTING MACRO :: % -% :::::::::::::::::::::::::::::::::::::: % +% -------------------------------------- % +% -- TCOLORBOX IMPORTED LISTING MACRO -- % +% -------------------------------------- % %%% % prototype:: -% #1 : (tdoclatex-style) -% :see: ''\newtcblisting{tdoclatex}'' -% #2 : (file path) +% #1 : (minted-like-options) +% :see: tcbset(tutodoc-latex-listing-style) +% #2 : (tcolorbox-styling-commands) +% :see: tcbset(tutodoc-latex-listing-style) +% #3 : (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''. +% \tcolorbox to have more \infos about the macro ''\tdoclatexinput''. %%% -\newtcbinputlisting{\tdoclatexinput}[2][std]{ - listing file = {#2}, - tutodoc-latex-listing-style = \tutodoc@latex@listing@format@option{#1} +\NewTCBInputListing{\tdoclatexinput}{ O{} D<>{} m }{ + listing file = {#3}, + tutodoc-latex-listing-style = {#1}{#2} } -% -------------------------- % -% -- LATEX REAL USE CASES -- % -% -------------------------- % +% ===================== % +% == LATEX USE CASES == % +% ===================== % \ExplSyntaxOn -% ::::::::::::::::::::: % -% :: SETTING THE KEY :: % -% ::::::::::::::::::::: % +% --------------------- % +% -- SETTING THE KEY -- % +% --------------------- % \tl_new:N \l_tutodoc_listing_explain_tl @@ -1036,7 +1066,6 @@ % prototype:: % explain : the text between the code and its highlighted output. % -% % note:: % This key can be used in addition to those of the ''tdocshowcase'' % \env, @@ -1047,9 +1076,9 @@ } -% ::::::::::::::::::::: % -% :: LATEXSHOW MACRO :: % -% ::::::::::::::::::::: % +% --------------------- % +% -- LATEXSHOW MACRO -- % +% --------------------- % \tl_new:N \l__tutodoc_showcase_options_passed_tl @@ -1057,8 +1086,8 @@ %%% % prototype:: % #1 : (key-val options) -% :see: \keys_define:nn { tutodoc / listing / latexshow } , -% \keys_define:nn { tutodoc / showcase } +% :see: l3keys(tutodoc / listing / latexshow) , +% l3keys(tutodoc / showcase) % #2 : (file path) % the path of a file % @@ -1071,7 +1100,7 @@ { #1 } \l__tutodoc_showcase_options_passed_tl - \tdoclatexinput[code]{#2} + \tdoclatexinput<\tdoctcb{code}>{#2} \tl_use:N \l_tutodoc_listing_explain_tl @@ -1083,13 +1112,155 @@ \ExplSyntaxOff -% -- CHANGES - WHEN? --% -\ExplSyntaxOn +% ========================= % +% == LISTINGS - AGNOSTIC == % +% ========================= % + +% ---------------------------------- % +% -- DOES THE THEME AVOID LEXERS? -- % +% ---------------------------------- % + +\NewExpandableDocumentCommand{\tutodoc@code@lexer}{ m }{% + \ifcodenolexer text\else #1\fi% +} + + +% ---------------------------------- % +% -- INLINE GENERALIST CODE MACRO -- % +% ---------------------------------- % + +%%% +% prototype:: +% #1 : (minted-like-options) +% a list of legal \minted options. +% #2 : (coding-lang) +% the name of the \minted lexer corresponding to the coding langage +% for the formating. +% +% warning:: +% There are only two arguments, because the \mintinline macro will eat +% the bit of inline code to be colored. +%%% +\NewDocumentCommand{\tdoccodein}{ O{} m }{% + \mintinline[ + bgcolor = tutodoc@code@back@color, + style/.expand once = \tutodoc@code@style, + #1 + ]{\tutodoc@code@lexer{#2}}% +} -% :::::::::::::: % -% :: MESSAGES :: % -% :::::::::::::: % + +% ----------------------------------------------------- % +% -- MINTED/TCOLORBOX GENERALIST LISTING ENVIRONMENT -- % +% ----------------------------------------------------- % + +%%% +% prototype:: +% #1 : (minted-like-options) +% :see: macro.tdoccodein +% #2 : (tcolorbox-styling-commands) +% you can override the default \tcolorbox settings with the help +% of the macro ''\tdoctcb''. +% #3 : (coding-lang) +% :see: macro.tdoccodein +% +% :see: macro.tdoctcb +% +% refs:: +% + https://tex.stackexchange.com/a/604821/6880 +% + https://tex.stackexchange.com/a/327983/6880 +%%% +\tcbset{ + tutodoc-full-listing-style/.style n args = {3}{ +% General. + minted style/.expand once = \tutodoc@code@style, + minted language/.expand once = \tutodoc@code@lexer{#3}, + breakable, + enhanced, +% Colors. + colframe = tutodoc@code@frame@color, + colback = tutodoc@code@back@color, + colupper = tutodoc@code@text@color, + collower = tutodoc@code@text@color, +% Padding. + boxsep = 0pt, + left = \tutodoc@code@left@len, + right = \tutodoc@code@right@len, + bottom = \tutodoc@code@bottom@len, + top = \tutodoc@code@top@len, +% Frame. + shadow = {\tutodoc@code@shadow@xshift@len}% + {\tutodoc@code@shadow@yshift@len}% + {\tutodoc@code@shadow@offset@len}% + {tutodoc@code@shadow@color}, + arc = \tutodoc@code@arc@len, + leftrule = \tutodoc@code@left@rule@len, + rightrule = \tutodoc@code@right@rule@len, + bottomrule = \tutodoc@code@bottom@rule@len, + toprule = \tutodoc@code@top@rule@len, +% Separating line. + segmentation style = { + tutodoc@code@segment@color, + dash pattern = {on 5pt off 2.5pt}, + line width = .75pt + }, + listing only, +% Extra minted otpions. + minted options = {#1}, +% Extra tcolorbox styles. + #2 + }, +} + + +%%% +% prototype:: +% #1 : (minted-like-options) +% :see: macro.tdoccodein +% #2 : (tcolorbox-styling-commands) +% :see: \tcbset{tutodoc-full-listing-style} +% #3 : (coding-lang) +% :see: macro.tdoccodein +% +% note:: +% See the \doc of the macro ''\NewTCBListing'' from the package +% \tcolorbox to have \infos about the environment ''tdoccode''. +%%% +\NewTCBListing{tdoccode}{ O{} D<>{} m }{% + tutodoc-full-listing-style = {#1}{#2}{#3} +} + + +% -------------------------------------- % +% -- TCOLORBOX IMPORTED LISTING MACRO -- % +% -------------------------------------- % + +%%% +% prototype:: +% #1 : (minted-like-options) +% :see: macro.tdoccodein +% #2 : (tcolorbox-styling-commands) +% :see: \tcbset{tutodoc-full-listing-style} +% #3 : (coding-lang) +% :see: macro.tdoccodein +% #4 : (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 ''\tdoccodeinput''. +%%% +\NewTCBInputListing{\tdoccodeinput}{ O{} D<>{} m m }{ + listing file = {#4}, + tutodoc-full-listing-style = {#1}{#2}{#3} +} + + + +% == CHANGES - WHEN? --% + +\ExplSyntaxOn \msg_set:nnnn { tutodoc ~ (version-n-change) } { version-n-change : date-bad-format } @@ -1097,9 +1268,9 @@ { Use ~ YYYY-MM-DD. } -% ::::::::::::::::: % -% :: MARGIN NOTE :: % -% ::::::::::::::::: % +% ----------------- % +% -- MARGIN NOTE -- % +% ----------------- % \reversemarginpar{} @@ -1198,9 +1369,9 @@ \ExplSyntaxOff -% :::::::::::::::::::::: % -% :: VERSION AND DATE :: % -% :::::::::::::::::::::: % +% ---------------------- % +% -- VERSION AND DATE -- % +% ---------------------- % \newlength{\tutodoc@version@date@vertical@sep@len} \setlength{\tutodoc@version@date@vertical@sep@len}{-4.25pt} @@ -1244,9 +1415,9 @@ } -% :::::::::: % -% :: DATE :: % -% :::::::::: % +% ---------- % +% -- DATE -- % +% ---------- % %%% % prototype:: @@ -1274,25 +1445,21 @@ } -% --------------------- % -% -- CHANGES - WHAT? -- % -% --------------------- % +% ===================== % +% == 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. } -% ::::::::::::::::::: % -% :: GENERIC TOPIC :: % -% ::::::::::::::::::: % +% ------------------- % +% -- GENERIC TOPIC -- % +% ------------------- % \tl_new:N \l_tutodoc_topic_what_color_tl \tl_new:N \l_tutodoc_topic_when_color_tl @@ -1325,6 +1492,25 @@ %%% +% For themes using icons, we need a specific paragraph with less vertical +% space consuming. +%%% +\ifcsundef{g__tutodoc_topic_change_seq}{ + \newcommand{\tutodoc@what@change@paragraph}{% + \@startsection{paragraph} % + {4} % Level 4 (after section and co) + {\z@} % No indentation before the title + {1.25ex \@plus 1ex \@minus .2ex} % Vertical space before: + % 2ex with flexibility (+1ex / -0.2ex) + {-1em} % Negative spacing after + % ==> Title slightly aligned to the left. + {\normalfont\normalsize % Title style + \bfseries\sffamily} % + } +}{} + + +%%% % prototype:: % #1 : (title) % a title that will be followed by a colon. @@ -1332,7 +1518,7 @@ % one material that expects to be an icon command from the % ''fontawsome5'' \pack % #3 : (key-val options) -% :see: \keys_define:nn { tutodoc / version-n-change / topic / options } +% :see: l3keys(tutodoc / version-n-change / topic / options) % % :action: this environment prints some \infos about specific changes % achieved in a new version (no special formatting is applied). @@ -1352,14 +1538,26 @@ \tl_put_right:Nn \l__tutodoc_topic_all_user_options_tl { \l_tutodoc_topic_date_tl } \group_begin: - \color{\tl_use:N \l_tutodoc_topic_what_color_tl} - - \paragraph{ \color{\tl_use:N \l_tutodoc_topic_what_color_tl} - \IfBlankF{#2}{\tdocicon{#2}} - \textsc{#1.} - \exp_args:Ne \IfBlankF{\l__tutodoc_topic_all_user_options_tl}{ + + \ifcsundef{g__tutodoc_topic_change_seq}{{} +% Icon used by the theme. + \tutodoc@what@change@paragraph{ + \color{\tl_use:N \l_tutodoc_topic_what_color_tl} + \IfBlankF{#2}{\tdocicon{#2}} + \textsc{#1.} + } + }{ +% No icon used by the theme. + \smallskip + { + \normalfont\normalsize\bfseries\sffamily + \textsc{#1.} + } + } + % A date and/or a version. + \exp_args:Ne \IfBlankF{\l__tutodoc_topic_all_user_options_tl}{ \exp_args:NNee \tutodoc@new@change@margin {\l_tutodoc_topic_when_color_tl} {\l_tutodoc_topic_version_tl} @@ -1367,18 +1565,17 @@ {\tutodoc@version@date@vertical@sep@len} {\tutodoc@version@date@vertical@offset@len} } - } - \begin{itemize} + \begin{itemize} }{ - \end{itemize} + \end{itemize} \group_end: } -% :::::::::::::::::::::: % -% :: CLASSICAL TOPICS :: % -% :::::::::::::::::::::: % +% ---------------------- % +% -- CLASSICAL TOPICS -- % +% ---------------------- % %%% % prototype:: @@ -1388,11 +1585,21 @@ % to build topic-like \envs using the \env ''tdoctopic'' % (the title respects the locale settings). %%% -\prop_map_inline:Nn \g__tutodoc_topic_change_prop { - \NewDocumentEnvironment{ tdoc#1 } { O{} } { - \begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } < #2 > [##1] - }{ - \end{tdoctopic} +\ifcsundef{g__tutodoc_topic_change_seq}{ + \prop_map_inline:Nn \g__tutodoc_topic_change_prop { + \NewDocumentEnvironment{ tdoc#1 } { O{} } { + \begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } < #2 > [##1] + }{ + \end{tdoctopic} + } + } +}{ + \seq_map_inline:Nn \g__tutodoc_topic_change_seq { + \NewDocumentEnvironment{ tdoc#1 } { O{} } { + \begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } [##1] + }{ + \end{tdoctopic} + } } } @@ -1406,21 +1613,33 @@ % % :action: the short text printed will be preceded by a pretty anchor icon. %%% -\NewDocumentCommand{ \tdocstartproj }{ O{tutodoc@text@color} m } { +\NewDocumentCommand{ \tdocstartproj }{ + O{tutodoc@text@color} + m +} { \group_begin: - \color{#1} - \tdocicon{\tutodoc@changes@start@project@icon}#2 + \color{#1} + \ifcsundef{g__tutodoc_topic_change_seq}{ +% Icon used. + \tdocicon{\tutodoc@changes@start@project@icon} + }{ +% No icon used. + \raisebox{4pt}{\normalfont\tiny\bfseries\sffamily[Init]}\kern2pt + } + + #2 \group_end: } \ExplSyntaxOff -% ----------------- % -% -- DECORATIONS -- % -% ----------------- % -% Source +% ================ % +% == DECORATION == % +% ================ % + +% refs:: % + https://tex.stackexchange.com/a/130529/6880 % (for the leaders trick) % + https://tex.stackexchange.com/a/269887/6880 |