From afbba3b1d12f17572ca4745766f2e0d55a6f58f3 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 8 Jan 2024 03:02:10 +0000 Subject: CTAN sync 202401080302 --- .../tutodoc/code/tdoc-locale-english.cfg.sty | 17 --- .../tutodoc/code/tdoc-locale-french.cfg.sty | 17 --- .../code/tutodoc-locale-main-english.cfg.sty | 17 +++ .../code/tutodoc-locale-main-french.cfg.sty | 17 +++ macros/latex/contrib/tutodoc/code/tutodoc.sty | 99 +++++++++---- macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf | Bin 687653 -> 709681 bytes macros/latex/contrib/tutodoc/doc/tutodoc-en.tex | 162 +++++++++++++++------ macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf | Bin 757927 -> 746351 bytes macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex | 130 ++++++++++++----- 9 files changed, 310 insertions(+), 149 deletions(-) delete mode 100644 macros/latex/contrib/tutodoc/code/tdoc-locale-english.cfg.sty delete mode 100644 macros/latex/contrib/tutodoc/code/tdoc-locale-french.cfg.sty create mode 100644 macros/latex/contrib/tutodoc/code/tutodoc-locale-main-english.cfg.sty create mode 100644 macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty (limited to 'macros/latex/contrib/tutodoc') diff --git a/macros/latex/contrib/tutodoc/code/tdoc-locale-english.cfg.sty b/macros/latex/contrib/tutodoc/code/tdoc-locale-english.cfg.sty deleted file mode 100644 index 58d8975905..0000000000 --- a/macros/latex/contrib/tutodoc/code/tdoc-locale-english.cfg.sty +++ /dev/null @@ -1,17 +0,0 @@ -\NewDocumentCommand{\tdoc@trans@in@EN}{}{in \ english} -\NewDocumentCommand{\tdoc@trans@latex@show@start}{}{Start \ of \ the \ real \ output} -\NewDocumentCommand{\tdoc@trans@latex@show@end}{}{End \ of \ the \ real \ output} -\NewDocumentCommand{\tdoc@trans@this@gives}{}{This \ gives} -\NewDocumentCommand{\tdoc@trans@exa@title}{}{Example} -\NewDocumentCommand{\tdoc@trans@rmk@title}{}{Remark} -\NewDocumentCommand{\tdoc@trans@important@title}{}{Important} -\NewDocumentCommand{\tdoc@trans@warn@title}{}{Warning} -\NewDocumentCommand{\tdoc@trans@caution@title}{}{Caution} -\NewDocumentCommand{\tdoc@trans@note@title}{}{Note} -\NewDocumentCommand{\tdoc@trans@tip@title}{}{Tip} - -\NewDocumentCommand{\tdoc@trans@chges@new}{}{New} -\NewDocumentCommand{\tdoc@trans@chges@update}{}{Update} -\NewDocumentCommand{\tdoc@trans@chges@fix}{}{Fix} - -\NewDocumentCommand{\tdoc@trans@date}{ mmm }{#1-#2-#3} diff --git a/macros/latex/contrib/tutodoc/code/tdoc-locale-french.cfg.sty b/macros/latex/contrib/tutodoc/code/tdoc-locale-french.cfg.sty deleted file mode 100644 index 2973757dd8..0000000000 --- a/macros/latex/contrib/tutodoc/code/tdoc-locale-french.cfg.sty +++ /dev/null @@ -1,17 +0,0 @@ -\NewDocumentCommand{\tdoc@trans@in@EN}{}{en \ anglais} -\NewDocumentCommand{\tdoc@trans@latex@show@start}{}{Début \ du \ rendu \ réel} -\NewDocumentCommand{\tdoc@trans@latex@show@end}{}{Fin \ du \ rendu \ réel} -\NewDocumentCommand{\tdoc@trans@this@gives}{}{Ceci \ donne} -\NewDocumentCommand{\tdoc@trans@exa@title}{}{Exemple} -\NewDocumentCommand{\tdoc@trans@rmk@title}{}{Remarque} -\NewDocumentCommand{\tdoc@trans@important@title}{}{Important} -\NewDocumentCommand{\tdoc@trans@warn@title}{}{Avertissement} -\NewDocumentCommand{\tdoc@trans@caution@title}{}{Prudence} -\NewDocumentCommand{\tdoc@trans@note@title}{}{Note} -\NewDocumentCommand{\tdoc@trans@tip@title}{}{Astuce} - -\NewDocumentCommand{\tdoc@trans@chges@new}{}{Nouveau} -\NewDocumentCommand{\tdoc@trans@chges@update}{}{Mise \ à \ jour} -\NewDocumentCommand{\tdoc@trans@chges@fix}{}{Réparation} - -\NewDocumentCommand{\tdoc@trans@date}{ mmm }{#3/#2/#1} diff --git a/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-english.cfg.sty b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-english.cfg.sty new file mode 100644 index 0000000000..339f10240c --- /dev/null +++ b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-english.cfg.sty @@ -0,0 +1,17 @@ +\NewDocumentCommand{\tutodoc@trans@date}{mmm}{#1-#2-#3} +\NewDocumentCommand{\tutodoc@trans@in@EN}{m}{#1 ~ in ~ english} +\NewDocumentCommand{\tutodoc@trans@this@gives}{m}{This ~ gives ~ #1} +\NewDocumentCommand{\tutodoc@trans@latex@show@start}{}{Start ~ of ~ the ~ real ~ output} +\NewDocumentCommand{\tutodoc@trans@latex@show@end}{}{End ~ of ~ the ~ real ~ output} +\NewDocumentCommand{\tutodoc@trans@exa@title}{}{Example} +\NewDocumentCommand{\tutodoc@trans@rmk@title}{}{Remark} +\NewDocumentCommand{\tutodoc@trans@note@title}{}{Note} +\NewDocumentCommand{\tutodoc@trans@tip@title}{}{Tip} +\NewDocumentCommand{\tutodoc@trans@important@title}{}{Important} +\NewDocumentCommand{\tutodoc@trans@caution@title}{}{Caution} +\NewDocumentCommand{\tutodoc@trans@warn@title}{}{Warning} +\NewDocumentCommand{\tutodoc@trans@chges@pb}{}{Problem} +\NewDocumentCommand{\tutodoc@trans@chges@break}{}{Break} +\NewDocumentCommand{\tutodoc@trans@chges@fix}{}{Fix} +\NewDocumentCommand{\tutodoc@trans@chges@new}{}{New} +\NewDocumentCommand{\tutodoc@trans@chges@update}{}{Update} \ No newline at end of file diff --git a/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty new file mode 100644 index 0000000000..c639e1e9e0 --- /dev/null +++ b/macros/latex/contrib/tutodoc/code/tutodoc-locale-main-french.cfg.sty @@ -0,0 +1,17 @@ +\NewDocumentCommand{\tutodoc@trans@date}{mmm}{#3/#2/#1} +\NewDocumentCommand{\tutodoc@trans@in@EN}{m}{#1 ~ en ~ anglais} +\NewDocumentCommand{\tutodoc@trans@this@gives}{m}{Ceci ~ donne ~ #1} +\NewDocumentCommand{\tutodoc@trans@latex@show@start}{}{Début ~ du ~ rendu ~ réel} +\NewDocumentCommand{\tutodoc@trans@latex@show@end}{}{Fin ~ du ~ rendu ~ réel} +\NewDocumentCommand{\tutodoc@trans@exa@title}{}{Exemple} +\NewDocumentCommand{\tutodoc@trans@rmk@title}{}{Remarque} +\NewDocumentCommand{\tutodoc@trans@note@title}{}{Note} +\NewDocumentCommand{\tutodoc@trans@tip@title}{}{Astuce} +\NewDocumentCommand{\tutodoc@trans@important@title}{}{Important} +\NewDocumentCommand{\tutodoc@trans@caution@title}{}{Caution} +\NewDocumentCommand{\tutodoc@trans@warn@title}{}{Danger} +\NewDocumentCommand{\tutodoc@trans@chges@pb}{}{Problème} +\NewDocumentCommand{\tutodoc@trans@chges@break}{}{Bifurcation} +\NewDocumentCommand{\tutodoc@trans@chges@fix}{}{Réparation} +\NewDocumentCommand{\tutodoc@trans@chges@new}{}{Nouveau} +\NewDocumentCommand{\tutodoc@trans@chges@update}{}{Mise ~ à ~ jour} \ No newline at end of file diff --git a/macros/latex/contrib/tutodoc/code/tutodoc.sty b/macros/latex/contrib/tutodoc/code/tutodoc.sty index cd4a6aecb3..5e0ea7a0fb 100644 --- a/macros/latex/contrib/tutodoc/code/tutodoc.sty +++ b/macros/latex/contrib/tutodoc/code/tutodoc.sty @@ -1,7 +1,7 @@ % ------------------------------------------------------- % % - This is file `tutodoc.sty' generated automatically. - % % - - % -% - Copyright (C) 2023 by Christophe BAL - % +% - Copyright (C) 2023-2024 by Christophe BAL - % % - - % % - This file may be distributed and/or modified under - % % - the conditions of the GNU 3 License. - % @@ -9,8 +9,8 @@ \ProvidesExplPackage {tutodoc} - {2023-12-08} % Creation: 2023-11-29 - {1.0.1} + {2024-01-06} % Creation: 2023-11-29 + {1.1.0} {This package proposes tools for writing "human friendly" documentations of LaTeX packages.} \RequirePackage[ @@ -88,18 +88,18 @@ % -- LOCALE SETTINGS -- % -\NewDocumentCommand{\tdoc@colon}{}{:} +\NewDocumentCommand{\tutodoc@colon}{}{:} % We must take care of the colons, babel and spacing. \@ifpackageloaded{babel}{ \iflanguage{french}{ - \RenewDocumentCommand{\tdoc@colon}{}{\babelshorthand{:}} + \RenewDocumentCommand{\tutodoc@colon}{}{\babelshorthand{:}} }{} }{} \ExplSyntaxOn -\input{tdoc-locale-\l_tdoc_opt_lang_str.cfg.sty} +\input{tutodoc-locale-main-\l_tdoc_opt_lang_str.cfg.sty} \ExplSyntaxOff @@ -199,7 +199,7 @@ \NewDocumentCommand{\tdocinEN}{s m}{% \tdocquote{#2}% \IfBooleanF{#1}{% No star used. - \ \tdoc@trans@in@EN{}% + \ \tutodoc@trans@in@EN{}% }% } @@ -212,7 +212,7 @@ % See the \doc of the macro ''\newtheorem'' from the package ''amsthm'' % to have \infos about the environment ''@@tdocexa@nb''. %%% -\newtheorem{@@tdocexa@nb}{\tdoc@trans@exa@title}% +\newtheorem{@@tdocexa@nb}{\tutodoc@trans@exa@title}% [subsubsection] %%% @@ -226,7 +226,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''@@tdocexa@no@nb''. %%% -\newtheorem*{@@tdocexa@no@nb}{\tdoc@trans@exa@title} +\newtheorem*{@@tdocexa@no@nb}{\tutodoc@trans@exa@title} % :: EXAMPLE - PUBLIC VERSION :: % @@ -268,7 +268,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdocrem''. %%% -\newtheorem*{tdocrem}{\tdoc@trans@rmk@title} +\newtheorem*{tdocrem}{\tutodoc@trans@rmk@title} % :: IMPORTANT :: % @@ -277,7 +277,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdocimportant''. %%% -\newtheorem*{tdocimportant}{\tdoc@trans@important@title} +\newtheorem*{tdocimportant}{\tutodoc@trans@important@title} % :: NOTE :: % @@ -286,7 +286,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdocnote''. %%% -\newtheorem*{tdocnote}{\tdoc@trans@note@title} +\newtheorem*{tdocnote}{\tutodoc@trans@note@title} % :: TIP :: % @@ -295,7 +295,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdoctip''. %%% -\newtheorem*{tdoctip}{\tdoc@trans@tip@title} +\newtheorem*{tdoctip}{\tutodoc@trans@tip@title} % :: CUATION :: % @@ -304,7 +304,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdoccaution''. %%% -\newtheorem*{tdoccaution}{\tdoc@trans@caution@title} +\newtheorem*{tdoccaution}{\tutodoc@trans@caution@title} % :: WARNING :: % @@ -313,7 +313,7 @@ % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdocwarn''. %%% -\newtheorem*{tdocwarn}{\tdoc@trans@warn@title} +\newtheorem*{tdocwarn}{\tutodoc@trans@warn@title} % -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- % @@ -563,9 +563,9 @@ \keys_define:nn { tdoc/showcase } { % Texts. before .tl_set:N = \l_tdoc_showcase_before_tl, - before .initial:n = \tdoc@trans@latex@show@start, + before .initial:n = \tutodoc@trans@latex@show@start, after .tl_set:N = \l_tdoc_showcase_after_tl, - after .initial:n = \tdoc@trans@latex@show@end, + after .initial:n = \tutodoc@trans@latex@show@end, % Decorations. color .tl_set:N = \l_tdoc_showcase_color_tl, color .initial:n = cyan, @@ -644,7 +644,7 @@ % See the \doc of the macro ''\newmintinline'' from the package ''minted'' % to have \infos about the macro ''tdocinlatex''. %%% -\newmintinline[tdocinlatex]{latex}{} +\newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4} % :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: % @@ -662,7 +662,7 @@ % % See the pgfkeys package documentation for explanation. %%% -\NewExpandableDocumentCommand{\tdoc@latex@listing@formating}{ m }{ +\NewExpandableDocumentCommand{\tutodoc@latex@listing@formating}{ m }{ \str_case:nnF { #1 } { { sbs } { listing ~ side ~ text } { code } { listing ~ only } @@ -721,7 +721,7 @@ % ''tcolorbox'' to have \infos about the environment ''tdoclatex''. %%% \newtcblisting{tdoclatex}[1][std]{% - tdoclatex_tcbstyle = \tdoc@latex@listing@formating{#1} + tdoclatex_tcbstyle = \tutodoc@latex@listing@formating{#1} } @@ -738,7 +738,7 @@ %%% \newtcbinputlisting{\tdoclatexinput}[2][std]{ listing file = {#2}, - tdoclatex_tcbstyle = \tdoc@latex@listing@formating{#1} + tdoclatex_tcbstyle = \tutodoc@latex@listing@formating{#1} } @@ -758,7 +758,7 @@ %%% \keys_define:nn { tdoc/latexshow } { explain .tl_set:N = \l_tdoc_listing_explain_tl, - explain .initial:n = { \tdoc@trans@this@gives \tdoc@colon }, + explain .initial:n = { \tutodoc@trans@this@gives \tutodoc@colon }, } @@ -817,7 +817,7 @@ % % :see: \__tdoc_translate_date:n %%% -\NewDocumentCommand{\tdoc@new@change@margin}{m m m m}{ +\NewDocumentCommand{\tutodoc@new@change@margin}{m m m m}{ \marginnote{ \color{#1} \scriptsize @@ -866,11 +866,11 @@ %%% % prototype:: % :action: this function extracts year, month and day in something -% like ''YYYY-MM-DD'' and then it calls ''\tdoc@trans@date'' +% like ''YYYY-MM-DD'' and then it calls ''\tutodoc@trans@date'' % to use the format expected for a "localised" date. %%% \cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop { - \tdoc@trans@date{#1} + \tutodoc@trans@date{#1} {#2} {#3} } @@ -894,7 +894,7 @@ % of the language chosen when loading the package. %%% \NewDocumentCommand{\tdocversion}{O{blue} m O{}}{ - \tdoc@new@change@margin{#1} % Color + \tutodoc@new@change@margin{#1} % Color {#3} % Date {#2} % Version {-4.25pt} % Last negative vertical spacing @@ -912,7 +912,7 @@ % prints a date. %%% \NewDocumentCommand{\tdocdate}{O{blue} m}{ - \tdoc@new@change@margin{#1} % Color + \tutodoc@new@change@margin{#1} % Color {#2} % Date {} % Version {-5.35pt} % Last negative spacing @@ -962,7 +962,7 @@ % translated into the good language. %%% \NewDocumentEnvironment{tdocnew}{}{ - \begin{tdoctopic}{\tdoc@trans@chges@new} + \begin{tdoctopic}{\tutodoc@trans@chges@new} }{ \end{tdoctopic} } @@ -978,7 +978,39 @@ % translated into the good language. %%% \NewDocumentEnvironment{tdocupdate}{}{ - \begin{tdoctopic}{\tdoc@trans@chges@update} + \begin{tdoctopic}{\tutodoc@trans@chges@update} +}{ + \end{tdoctopic} +} + + +% :: CHANGES - BREAK :: % + +%%% +% prototype:: +% :see: env.tdoctopic +% +% :action: similar to the \env ''tdoctopic'' with the title "Break" +% translated into the good language. +%%% +\NewDocumentEnvironment{tdocbreak}{}{ + \begin{tdoctopic}{\tutodoc@trans@chges@break} +}{ + \end{tdoctopic} +} + + +% :: CHANGES - PROBLEM :: % + +%%% +% prototype:: +% :see: env.tdoctopic +% +% :action: similar to the \env ''tdoctopic'' with the title "Problem" +% translated into the good language. +%%% +\NewDocumentEnvironment{tdocprob}{}{ + \begin{tdoctopic}{\tutodoc@trans@chges@pb} }{ \end{tdoctopic} } @@ -994,7 +1026,7 @@ % translated into the good language. %%% \NewDocumentEnvironment{tdocfix}{}{ - \begin{tdoctopic}{\tdoc@trans@chges@fix} + \begin{tdoctopic}{\tutodoc@trans@chges@fix} }{ \end{tdoctopic} } @@ -1004,6 +1036,9 @@ % -- DECORATIONS -- % +% Source for \addvspace{\medskipamount} instead of \medskip. +% * https://tex.stackexchange.com/a/705938/6880 + %%% % prototype:: % :action: this macro draws a centered horizontal rule with a height @@ -1012,8 +1047,8 @@ % Extra vertical spaces are added above and below the rule. %%% \NewDocumentCommand{\tdocsep}{}{ - \medskip - \hfill\rule{0.5\textwidth}{0.75pt}\hfill + \par\addvspace{\medskipamount} + \hfill\rule{0.5\textwidth}{0.75pt}\hfill\null \medskip \smallskip } diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf b/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf index a83fc1915d..6124b97c99 100644 Binary files a/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf and b/macros/latex/contrib/tutodoc/doc/tutodoc-en.pdf differ diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex b/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex index 8d628d7b4a..f6449b959c 100644 --- a/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex +++ b/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex @@ -1,27 +1,27 @@ - + % -------------------- % % -- RESOURCES USED -- % % -------------------- % \begin{filecontents*}[overwrite]{examples-focus-exa.tex} - Bla, bla, bla... +Bla, bla, bla... - \begin{tdocexa} - Ble, ble, ble... - \end{tdocexa} +\begin{tdocexa} + Ble, ble, ble... +\end{tdocexa} - \begin{tdocexa}[Wonderful] - Bli, bli, bli... - \end{tdocexa} +\begin{tdocexa}[Wonderful] + Bli, bli, bli... +\end{tdocexa} - \begin{tdocexa} - Blo, blo, blo... - \end{tdocexa} +\begin{tdocexa} + Blo, blo, blo... +\end{tdocexa} - \begin{tdocexa}[Superb] - Blu, blu, blu... - \end{tdocexa} +\begin{tdocexa}[Superb] + Blu, blu, blu... +\end{tdocexa} \end{filecontents*} @@ -119,7 +119,7 @@ \begin{tdocshowcase}[before = My beginning, after = My end, color = red] -Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} \end{filecontents*} @@ -143,9 +143,8 @@ Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... before = My beginning, after = My end, color = green] -Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... + Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla... \end{tdocshowcase} - \end{filecontents*} @@ -168,6 +167,13 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex} +\begin{tdoclatex} + \string[Strange... Or not!] +\end{tdoclatex} +\end{filecontents*} + + \begin{filecontents*}[overwrite]{examples-listing-xyz.tex} % Just one demo. $x y z = 1$ @@ -236,6 +242,22 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex} +\begin{tdocbreak} + \item Info 1... + \item Info 2... +\end{tdocbreak} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-version-n-change-pb.tex} +\begin{tdocprob} + \item Info 1... + \item Info 2... +\end{tdocprob} +\end{filecontents*} + + \begin{filecontents*}[overwrite]{examples-version-n-change-fix.tex} \begin{tdocfix} \item Info 1... @@ -244,8 +266,8 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-version-n-change-topic.tex} -\begin{tdoctopic}{Unclassifiable changes} +\begin{filecontents*}[overwrite]{examples-version-n-change-unclassifiable.tex} +\begin{tdoctopic}{Unclassifiable} % This is where the point needs to be put. \item Info 1... \item Info 2... @@ -265,7 +287,6 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \usepackage[english]{babel, varioref} \usepackage{enumitem} -%\frenchsetup{StandardItemLabels=true} \usepackage{tabularray} \usepackage{fmtcount} @@ -324,12 +345,11 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \title{Le package \texttt{tutodoc} - Documentation de type tutoriel} \author{Christophe BAL} -\date{8th Dec. 2023 - Version 1.0.1} +\date{\ordinalnum{1} Jan. 2024 - Version 1.1.0} \maketitle \begin{abstract} -\noindent The \tdocpack{tutodoc} package \footnote{ The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}. @@ -340,15 +360,10 @@ is used by its author to semantically produce documentation of \LaTeX\ packages }, and with a sober rendering for reading on screen. -\medskip -\noindent -Two important points to note. -\begin{itemize} - \item This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package. - - \item This documentation is also available in French. -\end{itemize} +\begin{tdocnote} + This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package. +\end{tdocnote} \end{abstract} @@ -374,6 +389,7 @@ The \tdocpack{geometry} package is loaded with the following settings. ]{geometry} \end{tdoclatex} + \subsection{Title and table of contents} The \tdocpack{titlesec} and \tdocpack{tocbasic} packages are set as follows. @@ -495,9 +511,9 @@ The macro \tdocmacro{tdocinEN} and its starred version are based on \tdocmacro{t Numbered or unnumbered examples can be indicated using the \tdocenv{tdocexa} environment, which offers two optional arguments. \begin{enumerate} - \item The \ordinalnum{1} argument between brackets \verb#<...># can take the values \verb#nb# to number, which is the default setting, and \verb#nonb# to not number. + \item The \ordinalnum{1} argument between brackets \tdocinlatex#<...># can take the values \tdocinlatex#nb# to number, which is the default setting, and \tdocinlatex#nonb# to not number. - \item The \ordinalnum{2} argument in square brackets \verb#[...]# is used to add a mini-title.. + \item The \ordinalnum{2} argument in square brackets \tdocinlatex#[...]# is used to add a mini-title.. \end{enumerate} @@ -545,13 +561,13 @@ The \tdocenv{tdocnote} environment is used to highlight useful information. Here \tdoclatexinput[sbs]{examples-focus-note.tex} - \subsection{Something important} The \tdocenv{tdocimportant} environment is used to indicate something important but harmless. \tdoclatexinput[sbs]{examples-focus-important.tex} + \subsection{Caution about a delicate point} The \tdocenv{tdoccaution} environment is used to indicate a delicate point to the user. Here's how to use it. @@ -566,6 +582,7 @@ The \tdocenv{tdocwarn} environment is used to warn the user of a trap to avoid. \tdoclatexinput[sbs]{examples-focus-warn.tex} +\newpage \section{Specify packages, classes, macros or environments} Here's what you can type semantically. @@ -698,7 +715,7 @@ It is sometimes useful to render code directly in the documentation. This type o \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. the following example. + 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} @@ -769,7 +786,7 @@ To obtain renderings by importing the code from an external file, instead of typ \medskip - As for \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+ , this will produce the colour change shown below. + As for \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+\,, this will produce the colour change shown below. \medskip @@ -777,6 +794,7 @@ To obtain renderings by importing the code from an external file, instead of typ \end{tdocexa} +\newpage \section{Use cases in \LaTeX} Documenting a package or a class is done efficiently using use cases showing both the code and the corresponding result. @@ -789,7 +807,7 @@ Documenting a package or a class is done efficiently using use cases showing bot The \tdocmacro{tdocinlatex} macro \footnote{ - The name of the macro \tdocmacro{tdocinlatex} comes from \tdocquote{tdocprewhy{in.line} \LaTeX}. + The name of the macro \tdocmacro{tdocinlatex} comes from \tdocquote{\tdocprewhy{in.line} \LaTeX}. } can be used to type inline code in a similar way to \tdocmacro{verb}. Here are some examples. @@ -803,10 +821,11 @@ Here are some examples. \begin{tdocnote} - The \tdocmacro{tdocinlatex} macro can be used in a footnote: see the bottom of this page + The \tdocmacro{tdocinlatex} macro can be used in a footnote: see below. \footnote{ - \tdocinlatex+$minted = TOP$+ was typed \tdocinlatex|\tdocinlatex+$minted = TOP$+| in this footnote. + \tdocinlatex+$minted = TOP$+ has been typed \tdocinlatex|\tdocinlatex+$minted = TOP$+| in this footnote... }. + In addition, a background color is deliberately used to subtly highlight the codes \tdocinlatex#\LaTeX#\,. \end{tdocnote} @@ -854,6 +873,11 @@ Here are some examples. \begin{tdocwarn} With default formatting, if the code begins with an opening bracket, the default option must be explicitly indicated. \tdocdocbasicinput{examples-listing-strange.tex} + + \smallskip + + Another method is to use the \tdocmacro{string} primitive. + \tdocdocbasicinput{examples-listing-strange-bis.tex} \end{tdocwarn} @@ -865,7 +889,7 @@ For the following codes, consider a file with the relative path \verb+examples-l \medskip -The \tdocmacro{tdoclatexinput} macro, shown below, is used in the same way as the \tdocenv{tdoclatex} environment except that the path to a file is supplied. +The \tdocmacro{tdoclatexinput} macro, shown below, expects the path of a file and offers the same options as the \tdocenv{tdoclatex} environment. % ------------------ % @@ -919,10 +943,11 @@ The \tdocmacro{tdoclatexinput} macro, shown below, is used in the same way as th % ------------------ % +\newpage \subsection{Imported codes put into practice} \label{tdoc-latexshow} \begin{tdocexa}[Showcase] - The following can be obtained via \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+. + The following comes from \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+. \medskip @@ -943,8 +968,7 @@ The \tdocmacro{tdoclatexinput} macro, shown below, is used in the same way as th \begin{tdocexa}[Changing the explanatory text] Using the key \tdocinlatex|explain|, you can use custom text. Thus, \tdocinlatex|tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex}| will produce the following. - \newpage -% \medskip + \medskip \begin{tdoc-doc-showcase} \tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex} @@ -1057,6 +1081,27 @@ during the latest changes. % ------------------ % +\begin{tdocexa}[For breaks] + \leavevmode + + \tdoclatexinput[sbs]{examples-version-n-change-break.tex} +\end{tdocexa} + + +% ------------------ % + + +\begin{tdocexa}[For problems] + \leavevmode + + \tdoclatexinput[sbs]{examples-version-n-change-pb.tex} +\end{tdocexa} + + +% ------------------ % + + +\newpage \begin{tdocexa}[For fixes] \leavevmode @@ -1070,9 +1115,10 @@ during the latest changes. \begin{tdocexa}[Chosen topics] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-topic.tex} + \tdoclatexinput[sbs]{examples-version-n-change-unclassifiable.tex} \end{tdocexa} + \section{Ornaments} Let's finish this documentation with a few small formatting tools that can be very useful. @@ -1083,6 +1129,16 @@ Bla, bla, bla... \tdocsep % Practical for demarcation. +This works with enumerations. + +\begin{itemize} + \item Underline. + + \item Something else useful. +\end{itemize} + +\tdocsep % Uniform behaviour. + Ble, ble, ble... Bli, bli, bli... @@ -1095,18 +1151,31 @@ Blo, blo, blo... Blu, blu, blu... \end{tdoclatex} +\newpage +\section{History} +\tdocversion{1.1.0}[2024-01-06] +\begin{tdocnew} + \item Change log : two new environments. + \begin{enumerate} + \item \tdocenv{tdocbreak} for breaking changes which are not backward compatible. -\newpage -\section{History} + \item \tdocenv{tdocprob} for identified problems. + \end{enumerate} + + \item \tdocmacro{tdocinlatex}: a light yellow is used as the background color. +\end{tdocnew} + +\tdocsep \tdocversion{1.0.1}[2023-12-08] \begin{tdocfix} \item \tdocmacro{tdocenv}: spacing is now correct, even if the \tdocpack{babel} package is not loaded with the French language. - \item \tdocenv[{[nostripe]}]{showcase}: page breaks around the rulers are no longer possible.\end{tdocfix} + \item \tdocenv[{[nostripe]}]{tdocshowcase}: page breaks around \tdocquote{framing} lines should be rare from now on. +\end{tdocfix} \tdocsep @@ -1115,3 +1184,4 @@ Blu, blu, blu... First public version of the project. \end{document} + \ No newline at end of file diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf index 3b37329ef4..a8691e1e8d 100644 Binary files a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf and b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.pdf differ diff --git a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex index ef86f8a9bc..ae9f99c300 100644 --- a/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex +++ b/macros/latex/contrib/tutodoc/doc/tutodoc-fr.tex @@ -167,6 +167,13 @@ Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex} +\begin{tdoclatex} + \string[Étrange... Ou pas !] +\end{tdoclatex} +\end{filecontents*} + + \begin{filecontents*}[overwrite]{examples-listing-xyz.tex} % Juste une démo. $x y z = 1$ @@ -235,6 +242,22 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \end{filecontents*} +\begin{filecontents*}[overwrite]{examples-version-n-change-break.tex} +\begin{tdocbreak} + \item Info 1... + \item Info 2... +\end{tdocbreak} +\end{filecontents*} + + +\begin{filecontents*}[overwrite]{examples-version-n-change-pb.tex} +\begin{tdocprob} + \item Info 1... + \item Info 2... +\end{tdocprob} +\end{filecontents*} + + \begin{filecontents*}[overwrite]{examples-version-n-change-fix.tex} \begin{tdocfix} \item Info 1... @@ -243,8 +266,8 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \end{filecontents*} -\begin{filecontents*}[overwrite]{examples-version-n-change-topic.tex} -\begin{tdoctopic}{Des changements inclassables} +\begin{filecontents*}[overwrite]{examples-version-n-change-unclassifiable.tex} +\begin{tdoctopic}{Inclassable} % Ici le point s'impose. \item Info 1... \item Info 2... @@ -269,7 +292,6 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... % Package documented. \usepackage[lang = french]{tutodoc} -\setlength{\parindent}{0em} % Source. % * https://tex.stackexchange.com/a/604698/6880 @@ -319,12 +341,11 @@ ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble... \title{Le package \texttt{tutodoc} - Documentation de type tutoriel} \author{Christophe BAL} -\date{8 Déc. 2023 - Version 1.0.1} +\date{1\ier{} Janv. 2024 - Version 1.1.0} \maketitle \begin{abstract} -\noindent Le package \tdocpack{tutodoc} \footnote{ Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} se traduit en \tdocquote{documentation de type tutoriel}. @@ -335,24 +356,15 @@ est utilisé par son auteur pour produire de façon sémantique des documentatio }, et avec un rendu sobre pour une lecture sur écran. -\medskip - -\noindent -Deux points importants à noter. -\begin{itemize} - \item Ce package impose un style de mise en forme. Dans un avenir plus ou moins proche, \tdocpack{tutodoc} sera sûrement éclaté en une classe et un package. - - \item Cette documentation est aussi disponible en anglais. -\end{itemize} - - -% ------------------ % +\begin{tdocnote} + Ce package impose un style de mise en forme. + Dans un avenir plus ou moins proche, \tdocpack{tutodoc} sera sûrement éclaté en une classe et un package. +\end{tdocnote} \tdocsep -{\noindent -\small\itshape +{\small\itshape \textbf{Abstract.} The \tdocpack{tutodoc} package \footnote{ @@ -364,15 +376,10 @@ is used by its author to semantically produce documentation of \LaTeX\ packages }, and with a sober rendering for reading on screen. -\medskip -\noindent -Two important points to note. -\begin{itemize} - \item This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package. - - \item This documentation is also available in French. -\end{itemize} +\begin{tdocnote} + This package imposes a formatting style. In the not-too-distant future, \tdocpack{tutodoc} will probably be split into a class and a package. +\end{tdocnote} } \end{abstract} @@ -521,9 +528,9 @@ La macro \tdocmacro{tdocinEN} et sa version étoilée s'appuient sur \tdocmacro{ Des exemples numérotés, ou non, s'indiquent via l'environnement \tdocenv{tdocexa} qui propose deux arguments optionnels. \begin{enumerate} - \item Le 1\ier{} argument entre chevrons \verb#<...># peut prendre au choix les valeurs \verb#nb# pour numéroter, réglage par défaut, et \verb#nonb# pour ne pas numéroter. + \item Le 1\ier{} argument entre chevrons \tdocinlatex#<...># peut prendre au choix les valeurs \tdocinlatex#nb# pour numéroter, réglage par défaut, et \tdocinlatex#nonb# pour ne pas numéroter. - \item Le 2\ieme{} argument entre crochets \verb#[...]# sert à ajouter un mini-titre. + \item Le 2\ieme{} argument entre crochets \tdocinlatex#[...]# sert à ajouter un mini-titre. \end{enumerate} @@ -795,7 +802,7 @@ Pour obtenir des rendus en important le code depuis un fichier externe, au lieu \medskip - Quant à \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+ , ceci produira le changement de couleur observable ci-après. + Quant à \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+\,, ceci produira le changement de couleur observable ci-après. \medskip @@ -829,10 +836,11 @@ Voici des exemples d'utilisation. \begin{tdocnote} - La macro \tdocmacro{tdocinlatex} est utilisable dans une note de pied de page : voir le bas de cette page + La macro \tdocmacro{tdocinlatex} est utilisable dans une note de pied de page : voir plus bas \footnote{ \tdocinlatex+$minted = TOP$+ a été tapé \tdocinlatex|\tdocinlatex+$minted = TOP$+| dans cette note de bas de page.. }. + De plus, une couleur de fond est volontairement utilisée pour subtilement faire ressortir les codes \tdocinlatex#\LaTeX#\,. \end{tdocnote} @@ -881,6 +889,11 @@ Voici des exemples d'utilisation. \begin{tdocwarn} Avec la mise en forme par défaut, si le code commence par un crochet ouvrant, il faudra indiquer explicitement l'option par défaut. \tdocdocbasicinput{examples-listing-strange.tex} + + \smallskip + + Une autre méthode consiste à utiliser la primitive \tdocmacro{string}. + \tdocdocbasicinput{examples-listing-strange-bis.tex} \end{tdocwarn} @@ -892,13 +905,12 @@ Pour les codes suivants, on considère un fichier de chemin relatif \verb+exampl \medskip -La macro \tdocmacro{tdoclatexinput} , présentée ci-après, s'utilise comme l'environnement \tdocenv{tdoclatex} excepté que l'on fournit le chemin d'un fichier. +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}. % ------------------ % -\newpage \begin{tdocexa}[Face à face] \leavevmode @@ -1067,7 +1079,6 @@ On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas lors des derniers changements. -\newpage \begin{tdocexa}[Pour les nouveautés] \leavevmode @@ -1088,6 +1099,26 @@ lors des derniers changements. % ------------------ % +\begin{tdocexa}[Pour les bifurcations] + \leavevmode + + \tdoclatexinput[sbs]{examples-version-n-change-break.tex} +\end{tdocexa} + + +% ------------------ % + + +\begin{tdocexa}[Pour les problèmes] + \leavevmode + + \tdoclatexinput[sbs]{examples-version-n-change-pb.tex} +\end{tdocexa} + + +% ------------------ % + + \begin{tdocexa}[Pour les réparations] \leavevmode @@ -1101,10 +1132,11 @@ lors des derniers changements. \begin{tdocexa}[Thématiques aux choix] \leavevmode - \tdoclatexinput[sbs]{examples-version-n-change-topic.tex} + \tdoclatexinput[sbs]{examples-version-n-change-unclassifiable.tex} \end{tdocexa} +\newpage \section{Décorations} Finissons cette documentation avec de petites outils de mise en forme pouvant rendre de grands services. @@ -1115,6 +1147,16 @@ Bla, bla, bla... \tdocsep % Pratique pour délimiter. +Ceci fonctionne avec des énumérations. + +\begin{itemize} + \item Point souligné. + + \item Autre chose utile. +\end{itemize} + +\tdocsep % Un comportement uniforme. + Ble, ble, ble... Bli, bli, bli... @@ -1127,16 +1169,30 @@ Blo, blo, blo... Blu, blu, blu... \end{tdoclatex} - \newpage \section{Historique} +\tdocversion{1.1.0}[2024-01-06] + +\begin{tdocnew} + \item Journal des changements : deux nouveaux environnements. + \begin{enumerate} + \item \tdocenv{tdocbreak} pour les \tdocquote{bifurcations}\,, soit les modifications non rétrocompatibles. + + \item \tdocenv{tdocprob} pour les problèmes repérés. + \end{enumerate} + + \item \tdocmacro{tdocinlatex}: un jaune léger est utilisé comme couleur de fond. +\end{tdocnew} + +\tdocsep + \tdocversion{1.0.1}[2023-12-08] \begin{tdocfix} \item \tdocmacro{tdocenv}: l'espacement est maintenant correct, même si le paquet \tdocpack{babel} n'est pas chargé avec la langue française. - \item \tdocenv[{[nostripe]}]{showcase}: les sauts de page autour des règles ne sont plus possibles. + \item \tdocenv[{[nostripe]}]{tdocshowcase}: les sauts de page autour des lignes \tdocquote{cadrantes} devraient être rares dorénavant. \end{tdocfix} \tdocsep -- cgit v1.2.3