texlive[69049] Master: tutodoc (6dec23)
commits+karl at tug.org
commits+karl at tug.org
Wed Dec 6 22:14:04 CET 2023
Revision: 69049
https://tug.org/svn/texlive?view=revision&revision=69049
Author: karl
Date: 2023-12-06 22:14:04 +0100 (Wed, 06 Dec 2023)
Log Message:
-----------
tutodoc (6dec23)
Modified Paths:
--------------
trunk/Master/tlpkg/bin/tlpkg-ctan-check
trunk/Master/tlpkg/libexec/ctan2tds
trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
Added Paths:
-----------
trunk/Master/texmf-dist/doc/latex/tutodoc/
trunk/Master/texmf-dist/doc/latex/tutodoc/MANIFEST.md
trunk/Master/texmf-dist/doc/latex/tutodoc/README.md
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
trunk/Master/texmf-dist/tex/latex/tutodoc/
trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-english.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-french.cfg.sty
trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
trunk/Master/tlpkg/tlpsrc/tutodoc.tlpsrc
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/MANIFEST.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/MANIFEST.md (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/MANIFEST.md 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,72 @@
+# Manifest for tutodoc
+
+This file is a listing of all files considered to be part of this package.
+It is automatically generated with `l3build manifest`.
+
+
+## Repository manifest
+
+The following groups list the files included in the development repository of the package.
+Files listed with a ‘†’ marker are included in the TDS but not CTAN files, and files listed
+with ‘‡’ are included in both.
+
+### Source files
+
+These are source files for a number of purposes, including the `unpack` process which
+generates the installation files of the package. Additional files included here will also
+be installed for processing such as testing.
+
+* tdoc-locale-english.cfg.sty †
+* tdoc-locale-french.cfg.sty †
+* tutodoc.sty †
+
+### Text files
+
+Plain text files included as documentation or metadata.
+
+* MANIFEST.md ‡
+* README.md ‡
+
+### Derived files
+
+The files created by ‘unpacking’ the package sources. This typically includes
+`.sty` and `.cls` files created from DocStrip `.dtx` files.
+
+* tdoc-locale-english.cfg.sty †
+* tdoc-locale-french.cfg.sty †
+* tutodoc.sty †
+
+
+## TDS manifest
+
+The following groups list the files included in the TeX Directory Structure used to install
+the package into a TeX distribution.
+
+### TeX files (TDS)
+
+All files included in the `tutodoc/tex` directory.
+
+* tdoc-locale-english.cfg.sty
+* tdoc-locale-french.cfg.sty
+* tutodoc.sty
+
+### Doc files (TDS)
+
+All files included in the `tutodoc/doc` directory.
+
+* MANIFEST.md
+* README.md
+* tutodoc-en.pdf
+* tutodoc-en.tex
+* tutodoc-fr.pdf
+* tutodoc-fr.tex
+
+
+## CTAN manifest
+
+The following group lists the files included in the CTAN package.
+
+### CTAN files
+
+* MANIFEST.md
+* README.md
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/MANIFEST.md
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/README.md (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/README.md 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,19 @@
+The `LaTeX` package `tutodoc`
+=============================
+
+About `tutodoc`
+---------------
+
+This package proposes some macros to write human documentations of `LaTeX` packages with a tutorial-like flavour.
+
+
+License
+-------
+
+This project may be distributed and/or modified under the conditions of the GNU 3 License.
+
+
+Where is the documentation?
+---------------------------
+
+At this time, there is a French and an English documentation writing with a tutorial-like flavor (in the repository, see the folder `rollout/doc`).
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/README.md
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf 2023-12-06 21:11:53 UTC (rev 69048)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf 2023-12-06 21:14:04 UTC (rev 69049)
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,1098 @@
+
+% -------------------- %
+% -- RESOURCES USED -- %
+% -------------------- %
+
+
+\begin{filecontents*}{examples-focus-exa.tex}
+ Bla, bla, bla...
+
+ \begin{tdocexa}
+ Ble, ble, ble...
+ \end{tdocexa}
+
+ \begin{tdocexa}[Wonderful]
+ Bli, bli, bli...
+ \end{tdocexa}
+
+ \begin{tdocexa}<nonb>
+ Blo, blo, blo...
+ \end{tdocexa}
+
+ \begin{tdocexa}<nonb>[Superb]
+ Blu, blu, blu...
+ \end{tdocexa}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-exa-leavevmode.tex}
+\begin{tdocexa}
+ \leavevmode
+
+ \begin{enumerate}
+ \item Point 1.
+
+ \item Point 2.
+ \end{enumerate}
+\end{tdocexa}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-rmk.tex}
+\begin{tdocrem}
+ Just one remark...
+\end{tdocrem}
+
+\begin{tdocrem}[Mini title]
+ Useful?
+\end{tdocrem}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-tip.tex}
+\begin{tdoctip}
+ A tip.
+\end{tdoctip}
+
+\begin{tdoctip}[Mini title]
+ Useful?
+\end{tdoctip}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-note.tex}
+\begin{tdocnote}
+ Something useful to tell you...
+\end{tdocnote}
+
+\begin{tdocnote}[Mini title]
+ Useful?
+\end{tdocnote}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-important.tex}
+\begin{tdocimportant}
+ Important and harmless.
+\end{tdocimportant}
+
+\begin{tdocimportant}[Mini title]
+ Useful?
+\end{tdocimportant}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-caution.tex}
+\begin{tdoccaution}
+ Caution, caution...
+\end{tdoccaution}
+
+\begin{tdoccaution}[Mini title]
+ Useful?
+\end{tdoccaution}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-warn.tex}
+\begin{tdocwarn}
+ Avoid the dangers...
+\end{tdocwarn}
+
+\begin{tdocwarn}[Mini title]
+ Useful?
+\end{tdocwarn}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-default.tex}
+\begin{tdocshowcase}
+ \bfseries A bit of code \LaTeX.
+
+ \bigskip
+
+ \emph{\large End of the awful demo.}
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-customized.tex}
+\begin{tdocshowcase}[before = My beginning,
+ after = My end,
+ color = red]
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-hook.tex}
+\begin{tdocshowcase}[]
+ [This works...]
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-no-clrstrip.tex}
+\begin{tdocshowcase}[nostripe]
+ Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-no-clrstrip-customized.tex}
+\begin{tdocshowcase}[nostripe,
+ before = My beginning,
+ after = My end,
+ color = green]
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-external.tex}
+Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-ABC.tex}
+\begin{tdoclatex}[sbs]
+ $A = B + C$
+\end{tdoclatex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-strange.tex}
+\begin{tdoclatex}[std]
+ [Strange... Or not!]
+\end{tdoclatex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-xyz.tex}
+% Just one demo.
+$x y z = 1$
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-latexshow-options.tex}
+\tdoclatexshow[explain = What comes next is colourful...,
+ before = Rendering below.,
+ after = Finished rendering.,
+ color = orange]
+ {examples-listing-xyz.tex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-dating.tex}
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+
+\medskip % CAUTION! This prevents overlapping.
+
+\tdocdate{2023-09-24}
+
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
+
+\medskip % CAUTION! This prevents overlapping.
+
+\tdocdate[gray]{2020-05-08}
+
+Bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli...
+
+Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo...
+
+Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-versioning.tex}
+\tdocversion[red]{10.2.0-beta}[2023-12-01]
+
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+
+\bigskip % CAUTION! This prevents overlapping.
+
+\tdocversion{10.2.0-alpha}
+
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-new.tex}
+\begin{tdocnew}
+ \item Info 1...
+ \item Info 2...
+\end{tdocnew}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-update.tex}
+\begin{tdocupdate}
+ \item Info 1...
+ \item Info 2...
+\end{tdocupdate}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-fix.tex}
+\begin{tdocfix}
+ \item Info 1...
+ \item Info 2...
+\end{tdocfix}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-topic.tex}
+\begin{tdoctopic}{Unclassifiable changes}
+% This is where the point needs to be put.
+ \item Info 1...
+ \item Info 2...
+\end{tdoctopic}
+\end{filecontents*}
+
+
+% ------------------------ %
+% -- SOURCE FOR THE DOC -- %
+% ------------------------ %
+
+\documentclass[12pt, a4paper]{article}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+
+\usepackage[english]{babel, varioref}
+
+\usepackage{enumitem}
+%\frenchsetup{StandardItemLabels=true}
+
+\usepackage{tabularray}
+\usepackage{fmtcount}
+
+% Package documented.
+\usepackage[lang = english]{tutodoc}
+
+
+% Source.
+% * https://tex.stackexchange.com/a/604698/6880
+
+\NewDocumentCommand{ \tdocdocbasicinput }{ 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{ \tdocdocextraruler }{ 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{ tdoc-doc-showcase }
+ { O{ Début du rendu dans cette doc. }
+ O{ Fin du rendu dans cette doc. } }{
+ \tdocdocextraruler{#1}
+ \smallskip
+}{
+ \smallskip
+ \tdocdocextraruler{#2}
+}
+
+
+
+\begin{document}
+
+\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
+\author{Christophe BAL}
+\date{29 Nov. 2023 - Version 1.0.0}
+
+\maketitle
+
+\begin{abstract}
+The \tdocpack{tutodoc} package
+\footnote{
+ The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
+}
+is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style
+\footnote{
+ The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected of coding documentation.
+},
+and with a sober rendering for reading on screen.
+
+
+\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}
+
+
+\newpage
+\tableofcontents
+\newpage
+\section{General formatting imposed}
+
+\subsection{Page geometry}
+
+The \tdocpack{geometry} package is loaded with the following settings.
+
+
+\begin{tdoclatex}[code]
+\RequirePackage[
+ top = 2.5cm,
+ bottom = 2.5cm,
+ left = 2.5cm,
+ right = 2.5cm,
+ marginparwidth = 2cm,
+ marginparsep = 2mm,
+ heightrounded
+]{geometry}
+\end{tdoclatex}
+
+\subsection{Title and table of contents}
+
+The \tdocpack{titlesec} and \tdocpack{tocbasic} packages are set as follows.
+
+
+\begin{tdoclatex}[code]
+\RequirePackage[raggedright]{titlesec}
+
+% ...
+\ifcsundef{chapter}%
+ {}%
+ {\renewcommand\thechapter{\Alph{chapter}.}}
+
+\renewcommand\thesection{\Roman{section}.}
+\renewcommand\thesubsection{\arabic{subsection}.}
+\renewcommand\thesubsubsection{\roman{subsubsection}.}
+
+\titleformat{\paragraph}[hang]%
+ {\normalfont\normalsize\bfseries}%
+ {\theparagraph}{1em}%
+ {}
+
+\titlespacing*{\paragraph}%
+ {0pt}%
+ {3.25ex plus 1ex minus .2ex}%
+ {0.5em}
+
+% Source
+% * https://tex.stackexchange.com/a/558025/6880
+\DeclareTOCStyleEntries[
+ raggedentrytext,
+ linefill = \hfill,
+ indent = 0pt,
+ dynindent,
+ numwidth = 0pt,
+ numsep = 1ex,
+ dynnumwidth
+]{tocline}{
+ chapter,
+ section,
+ subsection,
+ subsubsection,
+ paragraph,
+ subparagraph
+}
+
+\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section}
+\end{tdoclatex}
+
+
+\subsection{Dynamic links}
+
+The \tdocpack{hyperref} package is imported behind the scenes with the settings below.
+
+
+\begin{tdoclatex}[code]
+\hypersetup{
+ colorlinks,
+ citecolor = orange!75!black,
+ filecolor = orange!75!black,
+ linkcolor = orange!75!black,
+ urlcolor = orange!75!black
+}
+\end{tdoclatex}
+
+
+\section{Select language when loading package}
+
+By default, \tdocpack{tutodoc} is set for English, but it is possible to change the language: for example, a French documentation will use \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
+For the moment, we only have the following two choices.
+
+\begin{enumerate}
+ \item \tdocinlatex|english| is the default value.
+
+ \item \tdocinlatex|french|
+\end{enumerate}
+
+
+\begin{tdocnote}
+ Language names are those suggested by the \tdocpack{babel} package.
+\end{tdocnote}
+
+
+\section{What does that mean in \tdocquote{English}?}
+
+The macro \tdocmacro{tdocinEN} and its starred version are useless for English speakers because they have the following effects.
+
+
+\begin{tdoclatex}
+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 \tdocinlatex|tdocquote{semantic}| .
+
+
+\begin{tdocnote}
+ As the text \tdocquote{in English} is translated into the language indicated when \tdocpack{tutodoc} is imported, the macro \tdocmacro{tdocinEN} and its starred version become useful for non-English speakers.
+\end{tdocnote}
+
+
+\section{Highlighting content}
+
+\begin{tdocnote}
+ The environments presented in this section
+ \footnote{
+ The formatting comes from the \tdocpack{amsthm} package.
+ }
+ add a short title indicating the type of information provided.
+ This short text will always be translated into the language indicated when the \tdocpack{tutodoc} package is loaded.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\subsection{Examples}
+
+Numbered or unnumbered examples can be indicated using the \tdocenv{tdocexa} environment, which offers two optional arguments.
+
+\begin{enumerate}
+ \item The \ordinalnum{1} argument between brackets \verb#<...># can take the values \verb#nb# to number, which is the default setting, and \verb#nonb# to not number.
+
+ \item The \ordinalnum{2} argument in square brackets \verb#[...]# is used to add a mini-title..
+\end{enumerate}
+
+
+Here are some possible uses.
+
+\tdoclatexinput[sbs]{examples-focus-exa.tex}
+
+
+% ------------------ %
+
+
+\begin{tdocimportant}
+ The numbering of the examples is reset to zero as soon as a section with a level at least equal to a \tdocinlatex|\subsubsection| is opened.
+\end{tdocimportant}
+
+
+% ------------------ %
+
+
+\begin{tdoctip}
+ It can sometimes be useful to return to the line at the start of the content. Here's how to do it (this trick remains valid for the environments presented in the following sub-sections). Note in passing that the numbering follows that of the previous example as desired.
+
+ \tdoclatexinput[sbs]{examples-focus-exa-leavevmode.tex}
+\end{tdoctip}
+
+
+\subsection{Some remarks}
+
+Everything happens via the \tdocenv{tdocrem} environment, as in the following example.
+
+\tdoclatexinput[sbs]{examples-focus-rmk.tex}
+
+
+\subsection{A tip}
+
+The \tdocenv{tdoctip} environment is used to give tips. Here's how to use it.
+
+\tdoclatexinput[sbs]{examples-focus-tip.tex}
+
+
+\subsection{Informative note}
+
+The \tdocenv{tdocnote} environment is used to highlight useful information. Here's how to use it.
+
+\tdoclatexinput[sbs]{examples-focus-note.tex}
+
+
+
+\subsection{Something important}
+
+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.
+
+\tdoclatexinput[sbs]{examples-focus-caution.tex}
+
+
+\subsection{Warning of danger}
+
+The \tdocenv{tdocwarn} environment is used to warn the user of a trap to avoid. Here's how to use it.
+
+\tdoclatexinput[sbs]{examples-focus-warn.tex}
+
+
+\section{Specify packages, classes, macros or environments}
+
+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...
+
+We also have :
+
+\tdocenv[{[opt1]<opt2>}]{env}
+\end{tdoclatex}
+
+
+\begin{tdocrem}
+ The advantage of the previous macros over the use of \tdocmacro{tdocinlatex}, see the section \ref{tdoc-listing-inline} page \pageref{tdoc-listing-inline}, is the absence of colouring.
+ Furthermore, the \tdocmacro{tdocenv} macro simply asks you to type the name of the environment
+ \footnote{
+ In addition, \tdocinlatex{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if necessary.
+ }
+ with any options by typing the correct delimiters
+ \footnote{
+ Remember that almost anything is possible from now on.
+ }
+ by hand.
+\end{tdocrem}
+
+
+\begin{tdocwarn}
+ The optional argument to the \tdocmacro{tdocenv} macro is copied and pasted during rendering. This can sometimes require the use of protective braces, as in the previous example.
+\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]
+\tdocpre{sup} relates to...
+
+\tdocprewhy{sup.erbe} means...
+
+\emph{\tdocprewhy{sup.er} for...}
+\end{tdoclatex}
+
+
+\begin{tdocrem}
+ The choice of a full stop to split a word allows words with a hyphen to be used, as in \tdocinlatex+\tdocprewhy{bric.k-breaker}+ which gives \tdocprewhy{bric.k-breaker}.
+\end{tdocrem}
+
+
+\section{A real-life rendering} \label{tdoc-showcase}
+
+It is sometimes useful to render code directly in the documentation. This type of rendering must be dissociable from the explanatory text.
+
+
+% ------------------ %
+
+
+\subsection{With a coloured stripe}
+
+\begin{tdocexa} [With default text]
+ It can be useful to show a real rendering directly in a document
+ \footnote{
+ Typically when making a demo.
+ }.
+ This is done via \tdocenv{tdocshowcase} as follows.
+
+ \tdoclatexinput[code]{examples-showcase-default.tex}
+
+ The result is the following rendering
+ \footnote{
+ Behind the scenes, the strip is created effortlessly using the \tdocpack{clrstrip} package.
+ }.
+
+ \medskip
+
+ \input{examples-showcase-default.tex}
+\end{tdocexa}
+
+
+\begin{tdocrem}
+ See the section \ref{tdoc-latexshow} on page \pageref{tdoc-latexshow} to easily obtain code followed by its actual rendering as in the previous example.
+\end{tdocrem}
+
+
+\begin{tdocnote}
+ The explanatory texts adapt to the language chosen when \tdocpack{tutodoc} is loaded.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Change the default colour and/or text]
+ \leavevmode
+
+ \tdoclatexinput[code]{examples-showcase-customized.tex}
+
+ This will produce the following.
+
+ \medskip
+
+ \input{examples-showcase-customized.tex}
+\end{tdocexa}
+
+
+\begin{tdocnote}
+ You will have noticed that we don't obtain a pure red: behind the scenes, the expandable macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor} are used to create the background and title colours respectively from the ones proposed in \tdocenv{tdocshowcase}.
+ These macros have a single argument, the chosen colour, and accept the following codes.
+
+ \begin{tdoclatex}[code]
+\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
+\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
+ \end{tdoclatex}
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocwarn}
+ With the default settings, if the code to be formatted begins with an opening bracket, an empty option must be explicitly indicated, as in the following example.
+
+ \tdoclatexinput[code]{examples-showcase-hook.tex}
+
+ This will produce the following.
+
+ \medskip
+
+ \input{examples-showcase-hook.tex}
+\end{tdocwarn}
+
+
+\begin{tdocnote}
+ Behind the scenes, the \tdocmacro{tdocruler} macro is used.
+
+ \begin{tdoclatex}[std]
+ \tdocruler{Un pseudo-titre décoré}{red}
+ \end{tdoclatex}
+\end{tdocnote}
+
+
+\subsection{Without a colour 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.
+
+
+\begin{tdocexa}
+ The use of \tdocenv[{[nostripe]}]{tdocshowcase} indicate to not use \tdocpack{clrstrip}.
+ Here is an example.
+
+ \tdoclatexinput[code]{examples-showcase-no-clrstrip.tex}
+
+ This will produce the following.
+
+ \medskip
+
+ \input{examples-showcase-no-clrstrip.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Change the default colour and/or text]
+ \leavevmode
+
+ \tdoclatexinput[code]{examples-showcase-no-clrstrip-customized.tex}
+
+ This will produce the following.
+
+ \medskip
+
+ \input{examples-showcase-no-clrstrip-customized.tex}
+\end{tdocexa}
+
+
+\subsection{By importing the \LaTeX\ code}
+
+To obtain renderings by importing the code from an external file, instead of typing it, simply use the \tdocmacro{tdocshowcaseinput} macro whose option uses the syntax of that of \tdocenv{tdocshowcase} and the mandatory argument corresponds to the path of the file.
+
+
+\begin{tdocexa}<nonb>
+ The following was obtained via \tdocinlatex+\tdocshowcaseinput{external.tex}+.
+
+ \medskip
+
+ \tdocshowcaseinput{examples-showcase-external.tex}
+
+ \medskip
+
+ As for \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+ , this will produce the colour change shown below.
+
+ \medskip
+
+ \tdocshowcaseinput[color = orange]{examples-showcase-external.tex}
+\end{tdocexa}
+
+
+\section{Use cases in \LaTeX}
+
+Documenting a package or a class is done efficiently using use cases showing both the code and the corresponding result.
+
+
+% ------------------ %
+
+
+\subsection{\tdocquote{Inline} codes} \label{tdoc-listing-inline}
+
+The \tdocmacro{tdocinlatex} macro
+\footnote{
+ The name of the macro \tdocmacro{tdocinlatex} comes from \tdocquote{tdocprewhy{in.line} \LaTeX}.
+}
+can be used to type inline code in a similar way to \tdocmacro{verb}.
+Here are some examples.
+
+
+\begin{tdoclatex}[sbs]
+ 1: \tdocinlatex|$a^b = c$|
+
+ 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+
+\end{tdoclatex}
+
+
+\begin{tdocnote}
+ The \tdocmacro{tdocinlatex} macro can be used in a footnote: see the bottom of this page
+ \footnote{
+ \tdocinlatex+$minted = TOP$+ was typed \tdocinlatex|\tdocinlatex+$minted = TOP$+| in this footnote.
+ }.
+\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.
+ \tdocdocbasicinput{examples-listing-ABC.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Following]
+ \tdocenv{tdoclatex} produces the following result, which corresponds to the default option \tdocinlatex#std#
+ \footnote{
+ \tdocinlatex{std} refers to the \tdocquote{standard} behaviour of \tdocpack{tcolorbox} in relation to the \tdocpack{minted} library.
+ }.
+
+ \begin{tdoclatex}
+ $A = B + C$
+ \end{tdoclatex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Just the code]
+ Via \tdocenv[{[code]}]{tdoclatex}, we'll just get the code as shown below.
+
+ \begin{tdoclatex}[code]
+ $A = B + C$
+ \end{tdoclatex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\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}
+\end{tdocwarn}
+
+
+\subsection{Imported codes}
+
+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}
+
+\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.
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Side by side]
+ \leavevmode
+
+ \begin{tdoclatex}[code]
+\tdoclatexinput[sbs]{examples-listing-xyz.tex}
+ \end{tdoclatex}
+
+ This produces the following layout.
+
+ \tdoclatexinput[sbs]{examples-listing-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 \tdocinlatex#std#.
+
+ \tdoclatexinput{examples-listing-xyz.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Just the code]
+ \leavevmode
+
+ \begin{tdoclatex}[code]
+\tdoclatexinput[code]{examples-listing-xyz.tex}
+ \end{tdoclatex}
+
+ This produces the following layout.
+
+ \tdoclatexinput[code]{examples-listing-xyz.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\subsection{Imported codes put into practice} \label{tdoc-latexshow}
+
+\begin{tdocexa}[Showcase]
+ The following can be obtained via \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \tdoclatexshow{examples-listing-xyz.tex}
+ \end{tdoc-doc-showcase}
+\end{tdocexa}
+
+
+\begin{tdocnote}
+ The default texts take into account the language chosen when loading the package \tdocpack{tutodoc}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\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.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \tdoclatexshow[explain = Here is the actual rendering.]{examples-listing-xyz.tex}
+ \end{tdoc-doc-showcase}
+\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}, see \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
+ Here is an example to illustrate this.
+
+ \medskip
+
+ \tdoclatexinput[code]{examples-listing-latexshow-options.tex}
+
+ \medskip
+
+ This will produce the following.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \input{examples-listing-latexshow-options.tex}
+ \end{tdoc-doc-showcase}
+\end{tdocexa}
+
+
+\section{Indicate changes}
+
+To make it easier to monitor a package, it is essential to provide a history indicating the changes made when a new version is published.
+
+
+% ------------------ %
+
+
+\subsection{When?}
+
+You can either date something, or version it, in which case the version number can be dated.
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Dating new products]
+ 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.
+
+ \tdoclatexshow{examples-version-n-change-versioning.tex}
+\end{tdocexa}
+
+
+\begin{tdocimportant}
+ \leavevmode
+
+ \begin{enumerate}
+ \item The \tdocmacro{tdocdate} and \tdocmacro{tdocversion} macros require two compilations.
+
+ \item The final rendering of the dates takes into account the language specified when loading the package \tdocpack{tutodoc}: for example, if French is selected, the dates will be displayed in the format \texttt{DD/MM/YYYY}.
+ \end{enumerate}
+\end{tdocimportant}
+
+
+\begin{tdocwarn}
+ Only the use of the digital format \tdocinlatex+YYYY-MM-DD+ is verified.
+ \footnote{
+ Technically, checking the validity of a date using \LaTeX3 presents no difficulty.
+ },
+ and this is a choice! Why? Quite simply because dating and versioning explanations should be done semi-automatically to avoid any human bugs.
+\end{tdocwarn}
+
+
+\subsection{What's new?}
+
+\tdocpack{tutodoc} offers different environments to indicate quickly and clearly what has been done
+\footnote{
+ The user doesn't need all the technical details.
+}
+during the latest changes.
+
+
+\begin{tdocexa}[For new features]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[For updates]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[For fixes]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Chosen topics]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-topic.tex}
+\end{tdocexa}
+
+\section{Ornaments}
+
+Let's finish this documentation with a few small formatting tools that can be very useful.
+
+
+\begin{tdoclatex}[sbs]
+Bla, bla, bla...
+
+\tdocsep % Practical for demarcation.
+
+Ble, ble, ble...
+
+Bli, bli, bli...
+
+\tdocxspace % Subtle space
+ % but useful.
+
+Blo, blo, blo...
+
+Blu, blu, blu...
+
+\end{tdoclatex}
+
+
+
+\section{History}
+
+\tdocversion{1.0.0}[2023-11-29]
+
+First public version of the project.
+
+\end{document}
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-en.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf 2023-12-06 21:11:53 UTC (rev 69048)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf 2023-12-06 21:14:04 UTC (rev 69049)
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,1118 @@
+
+% -------------------- %
+% -- RESOURCES USED -- %
+% -------------------- %
+
+
+\begin{filecontents*}{examples-focus-exa.tex}
+Bla, bla, bla...
+
+\begin{tdocexa}
+ Ble, ble, ble...
+\end{tdocexa}
+
+\begin{tdocexa}[Magnifique]
+ Bli, bli, bli...
+\end{tdocexa}
+
+\begin{tdocexa}<nonb>
+ Blo, blo, blo...
+\end{tdocexa}
+
+\begin{tdocexa}<nonb>[Superbe]
+ Blu, blu, blu...
+\end{tdocexa}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-exa-leavevmode.tex}
+\begin{tdocexa}
+ \leavevmode
+
+ \begin{enumerate}
+ \item Point 1.
+
+ \item Point 2.
+ \end{enumerate}
+\end{tdocexa}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-rmk.tex}
+\begin{tdocrem}
+ Juste une remarque...
+\end{tdocrem}
+
+\begin{tdocrem}[Mini titre]
+ Utile ?
+\end{tdocrem}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-tip.tex}
+\begin{tdoctip}
+ Une astuce.
+\end{tdoctip}
+
+\begin{tdoctip}[Mini titre]
+ Utile ?
+\end{tdoctip}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-note.tex}
+\begin{tdocnote}
+ Un truc utile à vous dire...
+\end{tdocnote}
+
+\begin{tdocnote}[Mini titre]
+ Utile ?
+\end{tdocnote}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-important.tex}
+\begin{tdocimportant}
+ Un truc important sans danger.
+\end{tdocimportant}
+
+\begin{tdocimportant}[Mini titre]
+ Utile ?
+\end{tdocimportant}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-caution.tex}
+\begin{tdoccaution}
+ Prudence, prudence...
+\end{tdoccaution}
+
+\begin{tdoccaution}[Mini titre]
+ Utile ?
+\end{tdoccaution}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-focus-warn.tex}
+\begin{tdocwarn}
+ Evitez les dangers...
+\end{tdocwarn}
+
+\begin{tdocwarn}[Mini titre]
+ Utile ?
+\end{tdocwarn}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-default.tex}
+\begin{tdocshowcase}
+ \bfseries Un peu de code \LaTeX.
+
+ \bigskip
+
+ \emph{\large Fin de l'affreuse démo.}
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-customized.tex}
+\begin{tdocshowcase}[before = Mon début,
+ after = Ma fin à moi,
+ color = red]
+ Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-hook.tex}
+\begin{tdocshowcase}[]
+ [Cela fonctionne...]
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-no-clrstrip.tex}
+\begin{tdocshowcase}[nostripe]
+ Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-no-clrstrip-customized.tex}
+\begin{tdocshowcase}[nostripe,
+ before = Mon début,
+ after = Ma fin à moi,
+ color = green]
+ Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+\end{tdocshowcase}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-showcase-external.tex}
+Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-ABC.tex}
+\begin{tdoclatex}[sbs]
+ $A = B + C$
+\end{tdoclatex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-strange.tex}
+\begin{tdoclatex}[std]
+ [Étrange... Ou pas !]
+\end{tdoclatex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-xyz.tex}
+% Juste une démo.
+$x y z = 1$
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-listing-latexshow-options.tex}
+\tdoclatexshow[explain = Ce qui vient est coloré...,
+ before = Rendu ci-après.,
+ after = Rendu fini.,
+ color = orange]
+ {examples-listing-xyz.tex}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-dating.tex}
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+
+\medskip % ATTENTION ! Ceci évite le chevauchement.
+
+\tdocdate{2023-09-24}
+
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
+
+\medskip % ATTENTION ! Ceci évite le chevauchement.
+
+\tdocdate[gray]{2020-05-08}
+
+Bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli, bli...
+
+Blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo, blo...
+
+Blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu, blu...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-versioning.tex}
+\tdocversion[red]{10.2.0-beta}[2023-12-01]
+
+Bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla, bla...
+
+\bigskip % ATTENTION ! Ceci évite le chevauchement.
+
+\tdocversion{10.2.0-alpha}
+
+Ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble,
+ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble, ble...
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-new.tex}
+\begin{tdocnew}
+ \item Info 1...
+ \item Info 2...
+\end{tdocnew}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-update.tex}
+\begin{tdocupdate}
+ \item Info 1...
+ \item Info 2...
+\end{tdocupdate}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-fix.tex}
+\begin{tdocfix}
+ \item Info 1...
+ \item Info 2...
+\end{tdocfix}
+\end{filecontents*}
+
+
+\begin{filecontents*}{examples-version-n-change-topic.tex}
+\begin{tdoctopic}{Des changements inclassables}
+% Ici le point s'impose.
+ \item Info 1...
+ \item Info 2...
+\end{tdoctopic}
+\end{filecontents*}
+
+
+% ------------------------ %
+% -- SOURCE FOR THE DOC -- %
+% ------------------------ %
+
+\documentclass[10pt, a4paper]{article}
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+
+\usepackage[french]{babel, varioref}
+
+\usepackage{enumitem}
+\frenchsetup{StandardItemLabels=true}
+
+% Package documented.
+\usepackage[lang = french]{tutodoc}
+
+
+% Source.
+% * https://tex.stackexchange.com/a/604698/6880
+
+\NewDocumentCommand{ \tdocdocbasicinput }{ 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{ \tdocdocextraruler }{ 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{ tdoc-doc-showcase }
+ { O{ Début du rendu dans cette doc. }
+ O{ Fin du rendu dans cette doc. } }{
+ \tdocdocextraruler{#1}
+ \smallskip
+}{
+ \smallskip
+ \tdocdocextraruler{#2}
+}
+
+
+
+\begin{document}
+
+\title{Le package \texttt{tutodoc} - Documentation de type tutoriel}
+\author{Christophe BAL}
+\date{29 Nov. 2023 - Version 1.0.0}
+
+\maketitle
+
+\begin{abstract}
+Le package \tdocpack{tutodoc}
+\footnote{
+ Le nom vient de \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}} se traduit en \tdocquote{documentation de type tutoriel}.
+}
+est utilisé par son auteur pour produire de façon sémantique des documentations de packages et de classes \LaTeX\ dans un style de type tutoriel
+\footnote{
+ L'idée est de produire un fichier \texttt{PDF} efficace à parcourir pour des besoins ponctuels. C'est généralement ce que l'on attend d'une documentation liée au codage.
+},
+et avec un rendu sobre pour une lecture sur écran.
+
+
+\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
+
+{\small\itshape
+\textbf{Abstract.}
+The \tdocpack{tutodoc} package
+\footnote{
+ The name comes from \tdocquote{\tdocprewhy{tuto.rial-type} \tdocprewhy{doc.umentation}}.
+}
+is used by its author to semantically produce documentation of \LaTeX\ packages and classes in a tutorial style
+\footnote{
+ The idea is to produce an efficient \texttt{PDF} file that can be browsed for one-off needs. This is generally what is expected of coding documentation.
+},
+and with a sober rendering for reading on screen.
+
+
+\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}
+
+
+\newpage
+\tableofcontents
+\newpage
+\section{Mises en forme générales imposées}
+
+\subsection{Géométrie de la page}
+
+Le package \tdocpack{geometry} est chargé avec les réglages suivants.
+
+
+\begin{tdoclatex}[code]
+\RequirePackage[
+ top = 2.5cm,
+ bottom = 2.5cm,
+ left = 2.5cm,
+ right = 2.5cm,
+ marginparwidth = 2cm,
+ marginparsep = 2mm,
+ heightrounded
+]{geometry}
+\end{tdoclatex}
+
+
+\subsection{Titre et table des matières}
+
+Les packages \tdocpack{titlesec} et \tdocpack{tocbasic} sont réglés comme suit.
+
+
+\begin{tdoclatex}[code]
+\RequirePackage[raggedright]{titlesec}
+
+% ...
+\ifcsundef{chapter}%
+ {}%
+ {\renewcommand\thechapter{\Alph{chapter}.}}
+
+\renewcommand\thesection{\Roman{section}.}
+\renewcommand\thesubsection{\arabic{subsection}.}
+\renewcommand\thesubsubsection{\roman{subsubsection}.}
+
+\titleformat{\paragraph}[hang]%
+ {\normalfont\normalsize\bfseries}%
+ {\theparagraph}{1em}%
+ {}
+
+\titlespacing*{\paragraph}%
+ {0pt}%
+ {3.25ex plus 1ex minus .2ex}%
+ {0.5em}
+
+% Source
+% * https://tex.stackexchange.com/a/558025/6880
+\DeclareTOCStyleEntries[
+ raggedentrytext,
+ linefill = \hfill,
+ indent = 0pt,
+ dynindent,
+ numwidth = 0pt,
+ numsep = 1ex,
+ dynnumwidth
+]{tocline}{
+ chapter,
+ section,
+ subsection,
+ subsubsection,
+ paragraph,
+ subparagraph
+}
+
+\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section}
+\end{tdoclatex}
+
+
+\subsection{Liens dynamiques}
+
+Le package \tdocpack{hyperref} est importé en coulisse avec les réglages ci-dessous.
+
+
+\begin{tdoclatex}[code]
+\hypersetup{
+ colorlinks,
+ citecolor = orange!75!black,
+ filecolor = orange!75!black,
+ linkcolor = orange!75!black,
+ urlcolor = orange!75!black
+}
+\end{tdoclatex}
+
+
+\section{Choisir la langue au chargement du package}
+
+La présente documentation utilise le français via \tdocinlatex|\usepackage[lang = french]{tutodoc}| .
+Pour le moment, on a juste les deux choix suivants.
+
+\begin{enumerate}
+ \item \tdocinlatex|english| est la valeur par défaut.
+
+ \item \tdocinlatex|french| est pour \tdocinEN{français}.
+\end{enumerate}
+
+
+\begin{tdocnote}
+ Les noms des langues sont ceux proposés par le package \tdocpack{babel}.
+\end{tdocnote}
+
+
+\section{Cela veut dire quoi en \tdocquote{anglais}}
+
+Penser aux non-anglophones est bien, même si ces derniers se font de plus en plus rares.
+
+
+\begin{tdoclatex}
+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 \tdocinlatex|\tdocquote{sémantique}| .
+
+
+\begin{tdocnote}
+ Le texte \tdocquote{en anglais} est traduit dans la langue indiquée lors de l'importation de \tdocpack{tutodoc}.
+\end{tdocnote}
+
+
+\section{Mettre en avant du contenu}
+
+\begin{tdocnote}
+ Les environnements présentés dans cette section
+ \footnote{
+ La mise en forme provient du package \tdocpack{amsthm}.
+ }
+ ajoutent un court titre indiquant le type d'informations fournies.
+ Ce court texte sera toujours traduit dans la langue indiquée lors du chargement du package \tdocpack{tutodoc}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\subsection{Des exemples}
+
+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 2\ieme{} argument entre crochets \verb#[...]# sert à ajouter un mini-titre.
+\end{enumerate}
+
+
+Voici différents emplois possibles.
+
+\tdoclatexinput[sbs]{examples-focus-exa.tex}
+
+
+% ------------------ %
+
+
+\begin{tdocimportant}
+ La numérotation des exemples est remise à zéro dès qu'une section de niveau au moins égale à une \tdocinlatex|\subsubsection| est ouverte.
+\end{tdocimportant}
+
+
+% ------------------ %
+
+
+\begin{tdoctip}
+ Il peut parfois être utile de revenir à la ligne dès le début du contenu. Voici comment faire (ce tour de passe-passe reste valable pour les environnements présentés dans les sous-sections suivantes). Noter au passage que la numérotation suit celle de l'exemple précédent comme souhaité.
+
+ \tdoclatexinput[sbs]{examples-focus-exa-leavevmode.tex}
+\end{tdoctip}
+
+
+\subsection{Des remarques}
+
+Tout se passe via l'environnement \tdocenv{tdocrem} comme dans l'exemple suivant.
+
+\tdoclatexinput[sbs]{examples-focus-rmk.tex}
+
+
+\subsection{Une astuce}
+
+L'environnement \tdocenv{tdoctip} sert à donner des astuces. Voici comment l'employer.
+
+\tdoclatexinput[sbs]{examples-focus-tip.tex}
+
+
+\subsection{Note informative}
+
+L'environnement \tdocenv{tdocnote} sert à mettre en avant des informations utiles. Voici comment l'utiliser.
+
+\tdoclatexinput[sbs]{examples-focus-note.tex}
+
+
+\subsection{Un truc important}
+
+L'environnement \tdocenv{tdocimportant} permet d'indiquer quelque chose d'important mais sans danger.
+
+\tdoclatexinput[sbs]{examples-focus-important.tex}
+
+
+\subsection{Avertir d'un point très délicat}
+
+L'environnement \tdocenv{tdoccaution} sert à indiquer un point délicat à l'utilisateur. Voici comment l'employer.
+
+\tdoclatexinput[sbs]{examples-focus-caution.tex}
+
+
+\subsection{Avertir d'un danger}
+
+L'environnement \tdocenv{tdocwarn} sert à avertir l'utilisateur d'un piège à éviter. Voici comment l'employer.
+
+\tdoclatexinput[sbs]{examples-focus-warn.tex}
+
+
+\section{Indiquer des packages, des classes, des macros ou des environnements}
+
+Voici ce qu'il est possible de taper de façon sémantique.
+
+
+\begin{tdoclatex}[sbs]
+\tdoccls{maclasse} sert à...
+
+\tdocpack{monpackage} est pour...
+
+\tdocmacro{unemacro} permet de...
+
+\tdocenv{env} produit...
+
+On a aussi :
+
+\tdocenv[{[opt1]<opt2>}]{env}
+\end{tdoclatex}
+
+
+\begin{tdocrem}
+ L'intérêt des macros précédentes vis à vis de l'usage de \tdocmacro{tdocinlatex}, voir la section \ref{tdoc-listing-inline} page \pageref{tdoc-listing-inline}, est l'absence de coloration.
+ De plus, la macro \tdocmacro{tdocenv} demande juste de taper le nom de l'environnement
+ \footnote{
+ De plus, \tdocinlatex{\tdocenv{monenv}} produit \tdocenv{monenv} avec des espaces afin d'autoriser des retours à la ligne si besoin.
+ }
+ avec des éventuelles options en tapant les bons délimiteurs
+ \footnote{
+ Se souvenir que tout est possible ou presque dorénavant.
+ }
+ à la main.
+\end{tdocrem}
+
+
+\begin{tdocwarn}
+ L'argument optionnel de la macro \tdocmacro{tdocenv} est copié-collé lors du rendu. Ceci peut donc parfois nécessiter d'utiliser des accolades protectrices comme dans l'exemple précédent.
+\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...
+
+\emph{\tdocprewhy{sup.er} pour...}
+\end{tdoclatex}
+
+
+\begin{tdocrem}
+ Le choix du point pour scinder un mot permet d'utiliser des mots avec un tiret comme dans \tdocinlatex+\tdocprewhy{ca.sse-brique}+ qui donne \tdocprewhy{ca.sse-brique}.
+\end{tdocrem}
+
+
+\section{Un rendu en situation réelle} \label{tdoc-showcase}
+
+Il est parfois utile d'obtenir directement le rendu d'un code dans la documentation. Ceci nécessite que ce type de rendu soit dissociable du texte donnant des explications.
+
+
+% ------------------ %
+
+
+\subsection{Avec une bande colorée}
+
+\begin{tdocexa}[Avec les textes par défaut]
+ 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.
+
+ \tdoclatexinput[code]{examples-showcase-default.tex}
+
+ On obtient alors le rendu suivant
+ \footnote{
+ En coulisse, la bande est créée sans effort grâce au package \tdocpack{clrstrip}.
+ }.
+
+ \medskip
+
+ \input{examples-showcase-default.tex}
+\end{tdocexa}
+
+
+\begin{tdocrem}
+ Voir la section \ref{tdoc-latexshow} page \pageref{tdoc-latexshow} pour obtenir facilement un code suivi de son rendu réel comme dans l'exemple précédent.
+\end{tdocrem}
+
+
+\begin{tdocnote}
+ Les textes explicatifs s'adaptent à la langue choisie lors du chargement de \tdocpack{tutodoc}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Changer la couleur et/ou les textes par défaut]
+ \leavevmode
+
+ \tdoclatexinput[code]{examples-showcase-customized.tex}
+
+ Ceci produira ce qui suit.
+
+ \medskip
+
+ \input{examples-showcase-customized.tex}
+\end{tdocexa}
+
+
+\begin{tdocnote}
+ Vous avez sûrement noté que l'on n'obtient pas un rouge pur : en coulisse les macros développables \tdocmacro{tdocbackcolor} et \tdocmacro{tdocdarkcolor} sont utilisées pour créer celles du fond et des titres respectivement à partir de la couleur proposée à \tdocenv{tdocshowcase}.
+ Ces macros à un seul argument, la couleur choisie, admettent les codes suivants.
+
+ \begin{tdoclatex}[code]
+\NewExpandableDocumentCommand{\tdocbackcolor}{m}{#1!5}
+\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{#1!50!black}
+ \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 indiquer explicitement une option vide comme dans l'exemple suivant.
+
+ \tdoclatexinput[code]{examples-showcase-hook.tex}
+
+ Ceci produira ce qui suit.
+
+ \medskip
+
+ \input{examples-showcase-hook.tex}
+\end{tdocwarn}
+
+
+\begin{tdocnote}
+ Il faut savoir qu'en coulisse la macro \tdocmacro{tdocruler} est utilisée.
+
+ \begin{tdoclatex}[std]
+ \tdocruler{Un pseudo-titre décoré}{red}
+ \end{tdoclatex}
+\end{tdocnote}
+
+
+\subsection{Sans bande colorée}
+
+Le rendu de \tdocenv{tdocshowcase} avec une bande colorée peut ne pas convenir, ou parfois ne pas être acceptable malgré le travail fait par \tdocpack{clrstrip}.
+Il est possible de ne pas utiliser une bande colorée comme nous allons le voir tout de suite.
+
+
+\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-no-clrstrip.tex}
+
+ Ceci produira ce qui suit.
+
+ \medskip
+
+ \input{examples-showcase-no-clrstrip.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Changer la couleur et/ou les textes par défaut]
+ \leavevmode
+
+ \tdoclatexinput[code]{examples-showcase-no-clrstrip-customized.tex}
+
+ Ceci produira ce qui suit.
+
+ \medskip
+
+ \input{examples-showcase-no-clrstrip-customized.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}<nonb>
+ Ce qui suit a été obtenu via \tdocinlatex+\tdocshowcaseinput{external.tex}+.
+
+ \medskip
+
+ \tdocshowcaseinput{examples-showcase-external.tex}
+
+ \medskip
+
+ Quant à \tdocinlatex+\tdocshowcaseinput[color = orange]{external.tex}+ , ceci produira le changement de couleur observable ci-après.
+
+ \medskip
+
+ \tdocshowcaseinput[color = orange]{examples-showcase-external.tex}
+\end{tdocexa}
+
+
+\section{Cas d'utilisation en \LaTeX}
+
+Documenter un package ou une classe se fait efficacement via des cas d'utilisation montrant à la fois du code et le résultat correspondant.
+
+
+% ------------------ %
+
+
+\subsection{Codes \tdocquote{en ligne}} \label{tdoc-listing-inline}
+
+La macro \tdocmacro{tdocinlatex}
+\footnote{
+ Le nom de la macro \tdocmacro{tdocinlatex} vient de \tdocquote{\tdocprewhy{in.line} \LaTeX} soit \tdocinEN{\LaTeX\ en ligne}.
+}
+permet de taper du code en ligne via un usage similaire à \tdocmacro{verb}.
+Voici des exemples d'utilisation.
+
+
+\begin{tdoclatex}[sbs]
+ 1: \tdocinlatex|$a^b = c$|
+
+ 2: \tdocinlatex+\tdocinlatex|$a^b = c$|+
+\end{tdoclatex}
+
+
+\begin{tdocnote}
+ La macro \tdocmacro{tdocinlatex} est utilisable dans une note de pied de page : voir le bas de cette page
+ \footnote{
+ \tdocinlatex+$minted = TOP$+ a été tapé \tdocinlatex|\tdocinlatex+$minted = TOP$+| dans cette note de bas de page..
+ }.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\subsection{Codes tapés directement}
+
+\begin{tdocexa}[Face à face]
+ Via \tdocenv[{[sbs]}]{tdoclatex}, on affichera un code et son rendu côte à côte.
+ Indiquons que \tdocinlatex#sbs# est pour \tdocquote{\tdocprewhy{s.ide} \tdocprewhy{b.y} \tdocprewhy{s.ide}} soit \tdocinEN{côte à côte}.
+ \tdocdocbasicinput{examples-listing-ABC.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[À la suite]
+ \tdocenv{tdoclatex} produit le résultat suivant qui correspond à l'option par défaut \tdocinlatex#std#
+ \footnote{
+ \tdocinlatex{std} fait référence au comportement \tdocquote{standard} de \tdocpack{tcolorbox} vis à vis de la librairie \tdocpack{minted}.
+ }.
+
+ \begin{tdoclatex}
+ $A = B + C$
+ \end{tdoclatex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Juste le code]
+ Via \tdocenv[{[code]}]{tdoclatex}, on aura juste le code comme ci-après.
+
+ \begin{tdoclatex}[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.
+ \tdocdocbasicinput{examples-listing-strange.tex}
+\end{tdocwarn}
+
+
+\subsection{Codes importés}
+
+Pour les codes suivants, on considère un fichier de chemin relatif \verb+examples-listing-xyz.tex+, et ayant le contenu suivant.
+
+\tdoclatexinput[code]{examples-listing-xyz.tex}
+
+\medskip
+
+La macro \tdocmacro{tdoclatexinput} , présentée ci-après, s'utilise comme l'environnement \tdocenv{tdoclatex} excepté que l'on fournit le chemin d'un fichier.
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Face à face]
+ \leavevmode
+
+ \begin{tdoclatex}[code]
+\tdoclatexinput[sbs]{examples-listing-xyz.tex}
+ \end{tdoclatex}
+
+ Ceci produit la mise en forme suivante.
+
+ \tdoclatexinput[sbs]{examples-listing-xyz.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[À la suite]
+ \leavevmode
+
+ \begin{tdoclatex}[code]
+\tdoclatexinput{examples-listing-xyz.tex}
+ \end{tdoclatex}
+
+ Ceci produit la mise en forme suivante où l'option employée par défaut est \tdocinlatex#std#.
+
+ \tdoclatexinput{examples-listing-xyz.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Juste le code]
+ \leavevmode
+
+ \begin{tdoclatex}[code]
+\tdoclatexinput[code]{examples-listing-xyz.tex}
+ \end{tdoclatex}
+
+ Ceci produit la mise en forme suivante.
+
+ \tdoclatexinput[code]{examples-listing-xyz.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\subsection{Codes importés et mis en situation} \label{tdoc-latexshow}
+
+\begin{tdocexa}[Showcase]
+ Ce qui suit s'obtient via \tdocinlatex+\tdoclatexshow{examples-listing-xyz.tex}+.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \tdoclatexshow{examples-listing-xyz.tex}
+ \end{tdoc-doc-showcase}
+\end{tdocexa}
+
+
+\begin{tdocnote}
+ Les textes par défaut tiennent compte de la langue choisie lors du chargement du package \tdocpack{tutodoc}.
+\end{tdocnote}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Changer le texte explicatif]
+ Via la clé \tdocinlatex|explain|, on peut utiliser un texte personnalisé. Ainsi, \tdocinlatex|\tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}| produira ce qui suit.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \tdoclatexshow[explain = Voici le rendu réel.]{examples-listing-xyz.tex}
+ \end{tdoc-doc-showcase}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Les options disponibles]
+ En plus du texte explicatif, il est aussi possible d'utiliser toutes les options de \tdocenv{tdocshowcase}, voir \ref{tdoc-showcase} page \pageref{tdoc-showcase}.
+ Voici un exemple illustrant ceci.
+
+ \medskip
+
+ \tdoclatexinput[code]{examples-listing-latexshow-options.tex}
+
+ \medskip
+
+ Ceci va produire ce qui suit.
+
+ \medskip
+
+ \begin{tdoc-doc-showcase}
+ \input{examples-listing-latexshow-options.tex}
+ \end{tdoc-doc-showcase}
+\end{tdocexa}
+
+
+\section{Indiquer les changements}
+
+Afin de faciliter le suivi d'un package, il est indispensable de fournir un historique indiquant les changements effectués lors de la publication d'une nouvelle version.
+
+
+% ------------------ %
+
+
+\subsection{À quel moment ?}
+
+On peut au choix dater quelque chose, ou bien le versionner, dans ce second cas le numéro de version pourra éventuellement être daté.
+
+
+% ------------------ %
+
+
+\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]
+ Associer un numéro de version à une nouveauté se fait via la macro \tdocmacro{tdocversion}, la couleur et la date étant des arguments optionnels.
+
+ \tdoclatexshow{examples-version-n-change-versioning.tex}
+\end{tdocexa}
+
+
+\begin{tdocimportant}
+ \leavevmode
+
+ \begin{enumerate}
+ \item Les macros \tdocmacro{tdocdate} et \tdocmacro{tdocversion} nécessitent deux compilations.
+
+ \item Comme la langue indiquée pour cette documentation est le français, la date dans le rendu final est au format \texttt{JJ/MM/AAAA} alors que dans le code celle-ci devra toujours être saisie au format anglais \texttt{AAAA-MM-JJ}.
+ \end{enumerate}
+\end{tdocimportant}
+
+
+\begin{tdocwarn}
+ Seul l'emploi du format numérique \tdocinlatex+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 \tdocpack{tutodoc} est entrain de mettre en place un ensemble d'outils permettant une telle semi-automatisation.
+% }.
+\end{tdocwarn}
+
+
+\subsection{Quoi de neuf ?}
+
+\tdocpack{tutodoc} propose différents environnements pour indiquer rapidement et clairement ce qui a été fait
+\footnote{
+ L'utilisateur n'a pas besoin de tous les détails techniques.
+}
+lors des derniers changements.
+
+
+\begin{tdocexa}[Pour les nouveautés]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-new.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Pour les mises à jour]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-update.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Pour les réparations]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-fix.tex}
+\end{tdocexa}
+
+
+% ------------------ %
+
+
+\begin{tdocexa}[Thématiques aux choix]
+ \leavevmode
+
+ \tdoclatexinput[sbs]{examples-version-n-change-topic.tex}
+\end{tdocexa}
+
+
+\section{Décorations}
+
+Finissons cette documentation avec de petites outils de mise en forme pouvant rendre de grands services.
+
+
+\begin{tdoclatex}[sbs]
+Bla, bla, bla...
+
+\tdocsep % Pratique pour délimiter.
+
+Ble, ble, ble...
+
+Bli, bli, bli...
+
+\tdocxspace % Espace subtile
+ % mais utile.
+
+Blo, blo, blo...
+
+Blu, blu, blu...
+
+\end{tdoclatex}
+\section{Historique}
+
+\tdocversion{1.0.0}[2023-11-29]
+
+Première version publique du projet.
+
+\end{document}
Property changes on: trunk/Master/texmf-dist/doc/latex/tutodoc/tutodoc-fr.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-english.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-english.cfg.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-english.cfg.sty 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,17 @@
+\NewDocumentCommand{\tdoc at trans@in at EN}{}{in \ english}
+\NewDocumentCommand{\tdoc at trans@latex at show@start}{}{Start \ of \ the \ real \ output}
+\NewDocumentCommand{\tdoc at trans@latex at show@end}{}{End \ of \ the \ real \ output}
+\NewDocumentCommand{\tdoc at trans@this at gives}{}{This \ gives}
+\NewDocumentCommand{\tdoc at trans@exa at title}{}{Example}
+\NewDocumentCommand{\tdoc at trans@rmk at title}{}{Remark}
+\NewDocumentCommand{\tdoc at trans@important at title}{}{Important}
+\NewDocumentCommand{\tdoc at trans@warn at title}{}{Warning}
+\NewDocumentCommand{\tdoc at trans@caution at title}{}{Caution}
+\NewDocumentCommand{\tdoc at trans@note at title}{}{Note}
+\NewDocumentCommand{\tdoc at trans@tip at title}{}{Tip}
+
+\NewDocumentCommand{\tdoc at trans@chges at new}{}{New}
+\NewDocumentCommand{\tdoc at trans@chges at update}{}{Update}
+\NewDocumentCommand{\tdoc at trans@chges at fix}{}{Fix}
+
+\NewDocumentCommand{\tdoc at trans@date}{ mmm }{#1-#2-#3}
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-english.cfg.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-french.cfg.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-french.cfg.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-french.cfg.sty 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,17 @@
+\NewDocumentCommand{\tdoc at trans@in at EN}{}{en \ anglais}
+\NewDocumentCommand{\tdoc at trans@latex at show@start}{}{Début \ du \ rendu \ réel}
+\NewDocumentCommand{\tdoc at trans@latex at show@end}{}{Fin \ du \ rendu \ réel}
+\NewDocumentCommand{\tdoc at trans@this at gives}{}{Ceci \ donne}
+\NewDocumentCommand{\tdoc at trans@exa at title}{}{Exemple}
+\NewDocumentCommand{\tdoc at trans@rmk at title}{}{Remarque}
+\NewDocumentCommand{\tdoc at trans@important at title}{}{Important}
+\NewDocumentCommand{\tdoc at trans@warn at title}{}{Avertissement}
+\NewDocumentCommand{\tdoc at trans@caution at title}{}{Prudence}
+\NewDocumentCommand{\tdoc at trans@note at title}{}{Note}
+\NewDocumentCommand{\tdoc at trans@tip at title}{}{Astuce}
+
+\NewDocumentCommand{\tdoc at trans@chges at new}{}{Nouveau}
+\NewDocumentCommand{\tdoc at trans@chges at update}{}{Mise \ à \ jour}
+\NewDocumentCommand{\tdoc at trans@chges at fix}{}{Réparation}
+
+\NewDocumentCommand{\tdoc at trans@date}{ mmm }{#3/#2/#1}
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tdoc-locale-french.cfg.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty 2023-12-06 21:14:04 UTC (rev 69049)
@@ -0,0 +1,1026 @@
+% ------------------------------------------------------- %
+% - This is file `tutodoc.sty' generated automatically. - %
+% - - %
+% - Copyright (C) 2023 by Christophe BAL - %
+% - - %
+% - This file may be distributed and/or modified under - %
+% - the conditions of the GNU 3 License. - %
+% ------------------------------------------------------- %
+
+\ProvidesExplPackage
+ {tutodoc}
+ {2023-11-29} % Creation: 2023-11-29
+ {1.0.0}
+ {This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
+
+\RequirePackage[
+ top = 2.5cm,
+ bottom = 2.5cm,
+ left = 2.5cm,
+ right = 2.5cm,
+ marginparwidth = 2cm,
+ marginparsep = 2mm,
+ heightrounded
+]{geometry}[2020-01-02]
+
+\RequirePackage[raggedright]{titlesec}[2021/07/05]
+\RequirePackage{tocbasic}
+
+\RequirePackage{xcolor}[2022/06/12]
+\RequirePackage{hyperref}[2023-02-07]
+
+
+% We delegate the management of quoting to the `csquotes' package,
+% which takes care of the linguistic parameters.
+\RequirePackage{csquotes}[2022-09-14]
+
+
+\RequirePackage{amsthm}[2017/09]
+
+
+\RequirePackage{clrstrip}[2021-08-28]
+
+
+\RequirePackage{tcolorbox}[2023/06/19]
+\tcbuselibrary{minted, breakable, skins}
+
+
+\RequirePackage{marginnote}[2023-09-07]
+
+
+% -- LOCALE LANG -- %
+
+\ExplSyntaxOn
+
+% :: SOME MESSAGES :: %
+
+\msg_set:nnnn { tdoc } { package-option-lang-unknown }
+ { Unknown ~ language. }
+ { See ~ the ~ documentation ~ for ~ the ~ supported ~ languages. }
+
+
+% :: SETTING SOME KEYS :: %
+
+\str_new:N \l_tdoc_opt_lang_str
+
+%%%
+% We define the key-val options that will be exposed by the package.
+%%%
+\keys_define:nn { tdoc } {
+ lang .choices:nn =
+ { french, english }
+ {
+ \tl_set:Nn \l_tdoc_opt_lang_str
+ { \tl_use:N \l_keys_choice_tl }
+ },
+ lang .initial:n = english,
+ lang / unknown .code:n =
+ \msg_error:nnxxx { tdoc } { package-option-lang-unknown }
+ { lang } % Name of choice key
+ { french, english } % Valid choices
+ { \exp_not:n {#1} } % Invalid choice given
+}
+
+\ProcessKeyOptions[tdoc]
+
+\ExplSyntaxOff
+
+
+% -- LOCALE SETTINGS -- %
+
+\NewDocumentCommand{\tdoc at colon}{}{:}
+
+% We must take care of the colons, babel and spacing.
+\@ifpackageloaded{babel}{
+ \iflanguage{french}{
+ \RenewDocumentCommand{\tdoc at colon}{}{\babelshorthand{:}}
+ }{}
+}{}
+
+\ExplSyntaxOn
+
+\input{tdoc-locale-\l_tdoc_opt_lang_str.cfg.sty}
+
+\ExplSyntaxOff
+
+
+% -- GENERAL SETTINGS -- %
+
+\setlength{\parindent}{0cm}
+
+
+% -- LINKS -- %
+
+\hypersetup{
+ colorlinks,
+ citecolor = orange!75!black,
+ filecolor = orange!75!black,
+ linkcolor = orange!75!black,
+ urlcolor = orange!75!black
+}
+
+
+% -- TOC & Co. -- %
+
+\ifcsundef{chapter}%
+ {}%
+ {\renewcommand\thechapter{\Alph{chapter}.}}
+
+\renewcommand\thesection{\Roman{section}.}
+\renewcommand\thesubsection{\arabic{subsection}.}
+\renewcommand\thesubsubsection{\roman{subsubsection}.}
+
+\titleformat{\paragraph}[hang]%
+ {\normalfont\normalsize\bfseries}%
+ {\theparagraph}{1em}%
+ {}
+
+\titlespacing*{\paragraph}%
+ {0pt}%
+ {3.25ex plus 1ex minus .2ex}%
+ {0.5em}
+
+% Source
+% * https://tex.stackexchange.com/a/558025/6880
+\DeclareTOCStyleEntries[
+ raggedentrytext,
+ linefill = \hfill,
+ indent = 0pt,
+ dynindent,
+ numwidth = 0pt,
+ numsep = 1ex,
+ dynnumwidth
+]{tocline}{
+ chapter,
+ section,
+ subsection,
+ subsubsection,
+ paragraph,
+ subparagraph
+}
+
+\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section}
+
+
+% -- QUOTING -- %
+
+%%%
+% prototype::
+% #1 : a text to quote.
+%
+% For example, ''\tdocquote{Something}'' prints something like **"Something"**.
+%%%
+\NewDocumentCommand{\tdocquote}{m}{%
+ \enquote{\emph{#1}}%
+}
+
+
+% -- EXPLAINING ENGLISH NAMES -- %
+
+%%%
+% prototype::
+% #1 : an english text to explain in another language.
+%
+% :extra: this macro has a star version.
+%
+% For example, if the language chosen is ''french'', we have
+% the following outputs.
+%
+% 1) ''\tdocinEN{Something}'' prints
+% **"Something" en anglais**.
+%
+% 2) ''\tdocinEN*{Something}'' just prints
+% **"Something"**.
+% This can be useful in a case like
+% ''\tdocinEN*{Something} et \tdocinEN{Another thing}''
+% which gives
+% **"Something" et "Another thing" en anglais**.
+%%%
+\NewDocumentCommand{\tdocinEN}{s m}{%
+ \tdocquote{#2}%
+ \IfBooleanF{#1}{% No star used.
+ \ \tdoc at trans@in at EN{}%
+ }%
+}
+
+
+% -- FOCUS ON SOME CONTENT -- %
+
+% :: EXAMPLE - HIDDEN VERSIONS :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem'' from the package ''amsthm''
+% to have \infos about the environment ''@@tdocexa at nb''.
+%%%
+\newtheorem{@@tdocexa at nb}{\tdoc at trans@exa at title}%
+ [subsubsection]
+
+%%%
+% We redefine the counter associated to the environment ''@@tdocexa at nb''
+% to obtain only one single arabic number.
+%%%
+\renewcommand{\the@@tdocexa at nb}{\arabic{@@tdocexa at nb}}
+
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''@@tdocexa at no@nb''.
+%%%
+\newtheorem*{@@tdocexa at no@nb}{\tdoc at trans@exa at title}
+
+
+% :: EXAMPLE - PUBLIC VERSION :: %
+
+\ExplSyntaxOn
+
+\msg_set:nnnn { tdoc } { env-tdocexa-unknown-option }
+ { Unknown ~ rafters ~ option. }
+ { See ~ the ~ documentation ~ for ~ the ~ supported ~ options. }
+
+\NewDocumentEnvironment{tdocexa}{D<>{nb} O{}}{
+ \str_case:nnF { #1 } {
+ { nb } {
+ \begin{@@tdocexa at nb}[#2]
+ }
+ { nonb } {
+ \begin{@@tdocexa at no@nb}[#2]
+ }
+ }{
+ \msg_error:nn { tdoc } { env-tdocexa-unknown-option }
+ }
+}{
+ \str_case:nnF { #1 } {
+ { nb } {
+ \end{@@tdocexa at nb}
+ }
+ { nonb } {
+ \end{@@tdocexa at no@nb}
+ }
+ }{}
+}
+
+\ExplSyntaxOff
+
+
+% :: REMARK :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocrem''.
+%%%
+\newtheorem*{tdocrem}{\tdoc at trans@rmk at title}
+
+
+% :: IMPORTANT :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocimportant''.
+%%%
+\newtheorem*{tdocimportant}{\tdoc at trans@important at title}
+
+
+% :: NOTE :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocnote''.
+%%%
+\newtheorem*{tdocnote}{\tdoc at trans@note at title}
+
+
+% :: TIP :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdoctip''.
+%%%
+\newtheorem*{tdoctip}{\tdoc at trans@tip at title}
+
+
+% :: CUATION :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdoccaution''.
+%%%
+\newtheorem*{tdoccaution}{\tdoc at trans@caution at title}
+
+
+% :: WARNING :: %
+
+%%%
+% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm''
+% to have \infos about the environment ''tdocwarn''.
+%%%
+\newtheorem*{tdocwarn}{\tdoc at trans@warn at title}
+
+
+% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- %
+
+%%%
+% prototype::
+% #1 : the name of a class
+%
+% :action: ''\tdoccls{myclass}'' prints verb::''myclass''.
+%%%
+\NewDocumentCommand{\tdoccls}{m}{%
+ \texttt{#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : the name of a package
+%
+% :action:''\tdocpack{mypack}'' prints verb::''mypack''.
+%%%
+\NewDocumentCommand{\tdocpack}{m}{%
+ \texttt{#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : the name of a macro
+%
+% :action: ''\tdocenv{mymacro}'' prints verb::''\mymacro''.
+%%%
+\NewDocumentCommand{\tdocmacro}{m}{%
+ \texttt{\textbackslash{}#1}%
+}
+
+
+%%%
+% prototype::
+% #1 : hard typed options with the good delimiters
+% #2 : the name of an environment
+%
+% :action: ''\tdocenv{myenv}'' prints verb::''\begin{myenv} ... \end{myenv}''
+% or something like verb::''\begin{myenv}<opt1> ... \end{myenv}'',
+% the spaces being secable.
+%%%
+\NewDocumentCommand{\tdocenv}{O{}m}{%
+ \texttt{\textbackslash{}begin\{#2\}#1 %
+ \!...\! %
+ \textbackslash{}end\{#2\}}%
+}
+
+
+% -- EXPLAINING PREFIXES -- %
+
+\ExplSyntaxOn
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { bdoc } { prefixwhy-bad-format }
+{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
+{ You ~ must ~ use ~ one ~ single ~ point. }
+
+
+% :: PREFIX FROM... :: %
+
+%%%
+% prototype::
+% #1 : a prefix and a suffix separated by one colon.
+%
+% :action: ''\tdocprewhy{pre.fix}'' prints verb::''pre''.fix.
+%%%
+\NewDocumentCommand{\tdocprewhy}{m}{%
+% Do we have 2 parts?
+ \seq_set_split:Nnn \l_tmpa_seq { . } { #1 }
+
+ \int_set:Nn \l_tmpa_int
+ {\int_eval:n {\seq_count:N \l_tmpa_seq}}
+
+ \if_int_compare:w \l_tmpa_int = 2
+ \else:
+ \msg_error:nn { bdoc } { prefixwhy-bad-format }
+ \fi:
+
+% Let's go.
+ \seq_pop:NN \l_tmpa_seq \l_tmpa_tl
+ \seq_pop:NN \l_tmpa_seq \l_tmpb_tl
+
+ \textbf{\tdocpre{\tl_use:N \l_tmpa_tl}\kern.5pt\textperiodcentered\kern.5pt{\tl_use:N \l_tmpb_tl}}
+}
+
+\ExplSyntaxOff
+
+
+% :: JUST ONE PREFIX :: %
+
+%%%
+% prototype::
+% #1 : just a prefix
+%
+% :action: ''\tdocpre{pre}'' only prints verb::''pre''.
+% This can be useful in a case like
+% ''\tdocpre{pre} comes from \tdocprewhy{pre}{fix}''
+% which prints:
+% verb::''pre'' comes from verb::''pre''-fix.
+%%%
+\NewDocumentCommand{\tdocpre}{m}{%
+ \texttt{#1}%
+}
+
+
+% -- GENERAL FORMATTING -- %
+
+% :: TEXT INSIDE A RULE :: %
+
+\ExplSyntaxOn
+
+%%%
+% prototype::
+% #1 : a text
+% #2 : a color
+%
+% :action: this macro adds two horizontal lines on either side of the text.
+% The final output is centered.
+%
+% note::
+% The code used comes from
+% cf::''this post ;
+% https://tex.stackexchange.com/a/604708/6880''.
+%%%
+\NewDocumentCommand{\tdocruler}{m m}{
+ \par
+ {
+ \centering
+ \scriptsize
+ \itshape
+ \bfseries
+ \color{#2}
+
+ \hbox_set:Nn \l_tmpa_box { \,\, #1 \,\, }
+ \dim_set:Nn \l_tmpa_dim {
+ .35 \linewidth - .5 \box_wd:N \l_tmpa_box
+ }
+
+ \rule[.75pt] { \dim_use:N \l_tmpa_dim }
+ { 2.5pt }
+ \box_use:N \l_tmpa_box
+ \rule[.75pt] { \dim_use:N \l_tmpa_dim }
+ { 2.5pt }
+ \par
+ }
+}
+
+\ExplSyntaxOff
+
+
+% :: COLOR TRANSFORMATIONS :: %
+
+%%%
+% prototype::
+% #1 : one color following the ''xcolor'' format.
+%
+% :return: a "darker" version of the color ''#1''.
+%%%
+\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{%
+ #1!50!black%
+}
+
+
+%%%
+% prototype::
+% #1 : one color following the ''xcolor'' format.
+%
+% :return: a "transparent" version of the color `#1`.
+%%%
+\NewExpandableDocumentCommand{\tdoclightcolor}{m}{%
+ #1!5%
+}
+
+
+% :: INTERNAL ENVIRONMENTS :: %
+
+%%%
+% prototype::
+% #1 : the text before the real output
+% #2 : the text after the real output
+% #3 : one color following the ''xcolor'' format.
+% This color is used to set the one for the decorated texts printed
+% corresponding to the two first arguments.
+%
+% :action: this environment just adds its content processed by \latex
+% between centered materials produced by the macro ''\tdocruler''
+% such as to stress the start and the end of the content.
+%%%
+\NewDocumentEnvironment{tdoc at showcase@basic}{m m m}{
+ \tdocruler{#1}{\tdocdarkcolor{#3}}
+ \medskip
+}{
+ \medskip
+ \tdocruler{#2}{\tdocdarkcolor{#3}}
+}
+
+
+%%%
+% prototype::
+% #1 : the text before the real output
+% #2 : the text after the real output
+% #3 : the color following the ''xcolor'' format.
+% This color is used to set the ones of the stripe and the decorated
+% texts printed (see the two first arguments).
+%
+% :action: this environment adds a page-width colored stripe in the
+% background of the environment content processed by \latex.
+% This stripe is preceded and followed by centered materials
+% produced by the macro ''\tdocruler'' such as to stress the
+% start and the end of the content.
+%%%
+
+\NewDocumentEnvironment{tdoc at showcase@colorstrip}{m m m}{
+ \begin{colorstrip}{\tdoclightcolor{#3}}
+ \begin{tdoc at showcase@basic}{#1}{#2}{#3}
+}{
+ \end{tdoc at showcase@basic}
+ \end{colorstrip}
+}
+
+
+\ExplSyntaxOn
+
+% :: SETTING SOME KEYS :: %
+
+\tl_new:N \l_tdoc_showcase_before_tl
+\tl_new:N \l_tdoc_showcase_after_tl
+\tl_new:N \l_tdoc_showcase_color_tl
+\bool_new:N \l_tdoc_showcase_nostripe_bool
+
+
+%%%
+% prototype::
+% :see: env.tdocshowcase
+%
+% We define the key-val options that will be exposed by the \env
+% ''tdocshowcase''.
+%%%
+\keys_define:nn { tdoc/showcase } {
+% Texts.
+ before .tl_set:N = \l_tdoc_showcase_before_tl,
+ before .initial:n = \tdoc at trans@latex at show@start,
+ after .tl_set:N = \l_tdoc_showcase_after_tl,
+ after .initial:n = \tdoc at trans@latex at show@end,
+% Decorations.
+ color .tl_set:N = \l_tdoc_showcase_color_tl,
+ color .initial:n = cyan,
+ nostripe .bool_set:N = \l_tdoc_showcase_nostripe_bool,
+ nostripe .initial:n = false,
+}
+
+
+% :: SHOWCASE FROM TYPED CODE :: %
+
+% prototype::
+% #1 : the key-value options.
+%
+% :action: this \env formats \latex code, given as an argument,
+% by framing it with texts decorated by ''\tdocruler'',
+% in order to clearly identify a rendering used as an
+% example.
+% It is also possible to have a coloured strip of the width
+% of the page in the background of the content.
+%
+% :see: env.tdoc at showcase@basic ,
+% env.tdoc at showcase@colorstrip
+%%%
+\NewDocumentEnvironment{tdocshowcase}{O{}}{
+ \group_begin:
+ \keys_set:nn { tdoc/showcase } { #1 }
+
+ \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
+ \begin{tdoc at showcase@basic}%
+ { \tl_use:N \l_tdoc_showcase_before_tl }%
+ { \tl_use:N \l_tdoc_showcase_after_tl }%
+ { \tl_use:N \l_tdoc_showcase_color_tl }
+ }{
+ \begin{tdoc at showcase@colorstrip}%
+ { \tl_use:N \l_tdoc_showcase_before_tl }%
+ { \tl_use:N \l_tdoc_showcase_after_tl }%
+ { \tl_use:N \l_tdoc_showcase_color_tl }
+ }
+}{
+ \bool_if:NTF \l_tdoc_showcase_nostripe_bool {
+ \end{tdoc at showcase@basic}
+ }{
+ \end{tdoc at showcase@colorstrip}
+ }
+ \group_end:
+}
+
+
+% :: SHOWCASE FROM FILE :: %
+
+%%%
+% prototype::
+% #1 : the key-value options supported by the ''tdocshowcase'' \env.
+% #2 : the path of a file
+%
+% :see: env.tdocshowcase
+%%%
+\NewDocumentCommand{\tdocshowcaseinput}{O{} m}{
+ \group_begin:
+ \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl
+
+ \exp_last_unbraced:NNV \tdocshowcase [\l_tmpa_tl]
+ \input{#2}
+ \endtdocshowcase
+ \group_end:
+}
+
+\ExplSyntaxOff
+
+
+% -- LATEX EXAMPLES -- %
+
+% :: INLINE SHORT LATEX CODE :: %
+
+%%%
+% See the \doc of the macro ''\newmintinline'' from the package ''minted''
+% to have \infos about the macro ''tdocinlatex''.
+%%%
+\newmintinline[tdocinlatex]{latex}{}
+
+
+% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: %
+
+\ExplSyntaxOn
+
+%%%
+% In the following easy-to-understand macro, we use one fictive ''tcolorbox''
+% style such as to indicate an unknown ''tdoc'' style to the user.
+% For example, this can give one message similar to the following one.
+%
+% term::
+% Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option
+% "NOT-A-STYLE"' and I am going to ignore it. Perhaps you misspelled it.
+%
+% See the pgfkeys package documentation for explanation.
+%%%
+\NewExpandableDocumentCommand{\tdoc at latex@listing at formating}{ m }{
+ \str_case:nnF { #1 } {
+ { sbs } { listing ~ side ~ text }
+ { code } { listing ~ only }
+ { std } { listing ~ and ~ text }
+ } { tdoclatex ~ bad ~ option ~ "#1" }
+}
+
+\ExplSyntaxOff
+
+
+% :: THE TCOLORBOX LISTING STYLE :: %
+
+%%%
+% note::
+% The settings used come from the following sources.
+% * https://tex.stackexchange.com/a/604821/6880
+% * https://tex.stackexchange.com/a/327983/6880
+%%%
+\tcbset{
+ tdoclatex_tcbstyle/.style = {
+ minted language = latex,
+ breakable,
+% Code and output
+ colback = yellow!5,
+% Frame
+ colframe = darkgray,
+ shadow = {.75mm}{-.75mm}{0mm}{black!30},
+ arc = .75mm,
+ left = 1mm, right = 1mm,
+ bottom = 1mm, top = 1mm,
+% We can use ''sharp corners'' to obtain an "old school" style.
+%
+% Separating line
+ enhanced,
+ segmentation style = {
+ gray,
+ dash pattern = {on 5pt off 2.5pt},
+ line width = 1.25pt
+ },
+ #1
+ },
+}
+
+
+% :: TCOLORBOX LISTING ENVIRONMENT :: %
+
+%%%
+% prototype::
+% #1 : the style to be used (code only, code and output side by side,
+% or the standard style corresponding to the code followed by
+% its output)
+% @ #1 in [code, sbs, std]
+%
+% note::
+% See the \doc of the macro ''\newtcblisting'' from the package
+% ''tcolorbox'' to have \infos about the environment ''tdoclatex''.
+%%%
+\newtcblisting{tdoclatex}[1][std]{%
+ tdoclatex_tcbstyle = \tdoc at latex@listing at formating{#1}
+}
+
+
+% :: TCOLORBOX IMPORTED LISTING MACRO :: %
+
+%%%
+% prototype::
+% #1 : :see: \newtcblisting{tdoclatex}.
+% #2 : the path of the file to input and format.
+%
+% note::
+% See the \doc of the macro ''\newtcbinputlisting'' from the package
+% ''tcolorbox'' to have more \infos about the macro ''\tdoclatexinput''.
+%%%
+\newtcbinputlisting{\tdoclatexinput}[2][std]{
+ listing file = {#2},
+ tdoclatex_tcbstyle = \tdoc at latex@listing at formating{#1}
+}
+
+
+% -- LATEX REAL USE CASES -- %
+
+\ExplSyntaxOn
+
+% :: SETTING SOME KEYS :: %
+
+\tl_new:N \l_tdoc_listing_explain_tl
+
+%%%
+% prototype::
+% :see: macro.tdoclatexshow
+%
+% We define the key-val options that will be exposed by ''\tdoclatexshow''.
+%%%
+\keys_define:nn { tdoc/latexshow } {
+ explain .tl_set:N = \l_tdoc_listing_explain_tl,
+ explain .initial:n = { \tdoc at trans@this at gives \tdoc at colon },
+}
+
+
+% :: LATEXSHOW MACRO :: %
+
+%%%
+% prototype::
+% #1 : the key-value options supported by the ''tdocshowcase'' \env,
+% plus one allowing you to change the description of a line
+% printed between the code and its focused output.
+% #2 : the path of a file
+%
+% :see: env.tdocshowcase ,
+% macro.tdoclatexinput
+%%%
+\NewDocumentCommand{\tdoclatexshow}{O{} m}{
+ \group_begin:
+ \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl
+
+ \tdoclatexinput[code]{#2}
+
+ \tl_use:N \l_tdoc_listing_explain_tl
+
+% Source: https://tex.stackexchange.com/a/696700/6880
+ \exp_last_unbraced:NNV \tdocshowcaseinput [\l_tmpa_tl] {#2}
+ \group_end:
+}
+
+\ExplSyntaxOff
+
+
+% -- CHANGES - WHEN? --%
+
+\ExplSyntaxOn
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { tdoc } { date-bad-format }
+ { Bad ~ format ~ for ~ a ~ date. }
+ { Use ~ YYYY-MM-DD. }
+
+
+% :: MARGIN NOTE :: %
+
+\reversemarginpar{}
+
+%%%
+% prototype::
+% #1 : the color of the margin note
+% #2 : the first material (a date or nothing)
+% #3 : the second material (a version number or nothing)
+% #4 : the last negative vertical spacing for the 2nd rule
+%
+% :action: this macro factorizes the printing of the changes
+% in the left margin.
+%
+% :see: \__tdoc_translate_date:n
+%%%
+\NewDocumentCommand{\tdoc at new@change at margin}{m m m m}{
+ \marginnote{
+ \color{#1}
+ \scriptsize
+ \centering
+
+ \vspace{0pt}
+ \rule{1.65cm}{.95pt}
+ \vspace{-2.9pt}
+
+ \IfBlankTF{#2}{}{
+ \par
+ \__tdoc_translate_date:n { #2 }
+ \par
+ }
+
+ \vspace{1pt}
+
+ \par
+ #3
+ \par
+
+ \vspace{#4}
+ \rule{1.65cm}{.95pt}
+ }[-.345cm]
+}
+
+
+%%%
+% prototype::
+% :action: this function checks if we have something like
+% ''YYYY-MM-DD'' and then it calls the function
+% ''\__tdoc_translate_date_process:w'' to finish
+% the job.
+%
+% :see: \__tdoc_translate_date_process:w
+%%%
+\cs_new:Nn \__tdoc_translate_date:n {
+ \regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{
+ \__tdoc_translate_date_process:w #1 \q_stop
+ }{
+ \msg_error:nn { tdoc } { date-bad-format }
+ }
+}
+
+
+%%%
+% prototype::
+% :action: this function extracts year, month and day in something
+% like ''YYYY-MM-DD'' and then it calls ''\tdoc at trans@date''
+% to use the format expected for a "localised" date.
+%%%
+\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop {
+ \tdoc at trans@date{#1}
+ {#2}
+ {#3}
+}
+
+
+% :: VERSION AND DATE :: %
+
+%%%
+% prototype::
+% #1 : the color of the margin note
+% #2 : a version number
+% #3 : a date ''YYYY-MM-DD''
+%
+% :action: this macro prints a margin note showing a version number
+% below a date, and the optional argument is used to colorize
+% all this text.
+%
+% warning::
+% The date must use an english formatting like ''2021-07-14''. This allows
+% to parse the date such as to display it following the standard convention
+% of the language chosen when loading the package.
+%%%
+\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{
+ \tdoc at new@change at margin{#1} % Color
+ {#3} % Date
+ {#2} % Version
+ {-4.25pt} % Last negative vertical spacing
+}
+
+
+% :: DATE :: %
+
+%%%
+% prototype::
+% #1 : the color of the margin note
+% #2 : a date ''YYYY-MM-DD''
+%
+% :action: this macro is similar to ''\tdocversion'' except that it just
+% prints a date.
+%%%
+\NewDocumentCommand{\tdocdate}{O{blue} m}{
+ \tdoc at new@change at margin{#1} % Color
+ {#2} % Date
+ {} % Version
+ {-5.35pt} % Last negative spacing
+}
+
+
+% -- CHANGES - WHAT?
+
+% :: MESSAGES :: %
+
+\msg_set:nnnn { tdoc } { changes-topic-missing-title }
+ { Missing ~ title. }
+ { One ~ single ~ title ~ must ~ be ~ indicated. }
+
+
+% :: CHANGES - TOPIC :: %
+
+%%%
+% prototype::
+% #1 : a title that will be followed by a colon.
+%
+% :action: this environment prints some ¨infos about specific changes
+% achieved in a new version (no special formatting is applied).
+%%%
+\NewDocumentEnvironment{tdoctopic}{ m }{
+ \IfBlankT{#1}{
+ \msg_fatal:nn { tdoc } { changes-topic-missing-title }
+ }
+
+ \textbf{
+ \textsc{#1.}
+ }
+
+ \begin{itemize}
+}{
+ \end{itemize}
+}
+
+
+% :: CHANGES - NEW THINGS :: %
+
+%%%
+% prototype::
+% :see: env.tdoctopic
+%
+% :action: similar to the \env ''tdoctopic'' with the title "New"
+% translated into the good language.
+%%%
+\NewDocumentEnvironment{tdocnew}{}{
+ \begin{tdoctopic}{\tdoc at trans@chges at new}
+}{
+ \end{tdoctopic}
+}
+
+
+% :: CHANGES - UPDATE :: %
+
+%%%
+% prototype::
+% :see: env.tdoctopic
+%
+% :action: similar to the \env ''tdoctopic'' with the title "Update"
+% translated into the good language.
+%%%
+\NewDocumentEnvironment{tdocupdate}{}{
+ \begin{tdoctopic}{\tdoc at trans@chges at update}
+}{
+ \end{tdoctopic}
+}
+
+
+% :: CHANGES - FIX :: %
+
+%%%
+% prototype::
+% :see: env.tdoctopic
+%
+% :action: similar to the \env ''tdoctopic'' with the title "Fix"
+% translated into the good language.
+%%%
+\NewDocumentEnvironment{tdocfix}{}{
+ \begin{tdoctopic}{\tdoc at trans@chges at fix}
+}{
+ \end{tdoctopic}
+}
+
+\ExplSyntaxOff
+
+
+% -- DECORATIONS -- %
+
+%%%
+% prototype::
+% :action: this macro draws a centered horizontal rule with a height
+% of qty::''0.75 pt'', and a width equal to half of the current
+% text width.
+% Extra vertical spaces are added above and below the rule.
+%%%
+\NewDocumentCommand{\tdocsep}{}{
+ \medskip
+ \hfill\rule{0.5\textwidth}{0.75pt}\hfill
+ \medskip
+ \smallskip
+}
+
+
+%%%
+% prototype::
+% :action: this macro adds a tiny vertical spacing.
+%%%
+\NewDocumentCommand{\tdocxspace}{}{
+ \vspace{0.25em}
+}
Property changes on: trunk/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/tlpkg/bin/tlpkg-ctan-check
===================================================================
--- trunk/Master/tlpkg/bin/tlpkg-ctan-check 2023-12-06 21:11:53 UTC (rev 69048)
+++ trunk/Master/tlpkg/bin/tlpkg-ctan-check 2023-12-06 21:14:04 UTC (rev 69049)
@@ -863,7 +863,7 @@
trigonometry trimspaces trivfloat trivialpursuit trsym truncate truthtable
tsemlines tsvtemplate
tucv tuda-ci tudscr tufte-latex tugboat tugboat-plain
- tui turabian turabian-formatting turkmen turnstile turnthepage
+ tui turabian turabian-formatting turkmen turnstile turnthepage tutodoc
twemoji-colr twemojis twoinone twoup
txfonts txfontsb txgreeks txuprcal
type1cm typed-checklist typeface typehtml typeoutfileinfo typewriter
Modified: trunk/Master/tlpkg/libexec/ctan2tds
===================================================================
--- trunk/Master/tlpkg/libexec/ctan2tds 2023-12-06 21:11:53 UTC (rev 69048)
+++ trunk/Master/tlpkg/libexec/ctan2tds 2023-12-06 21:14:04 UTC (rev 69049)
@@ -1874,6 +1874,7 @@
'tlc3-examples' => '&POSTtlc3_examples',
'trivialpursuit' => '&POST_onelevel',
'tudscr' => '&POSTtudscr',
+ 'tutodoc' => '&POST_onelevel',
'unicode-alphabets' => '&POST_onelevel',
'unimath-plain-xetex' => '&POSTunimath_plain_xetex',
'updatemarks' => '&POST_onelevel',
@@ -7832,14 +7833,14 @@
#
sub POST_onelevel {
print "POST_onelevel ($package) - handle doc/source/tex directories\n";
- for my $dir (qw(latex lualatex luatex metapost opentype
+ for my $dir (qw(code latex lualatex luatex metapost opentype
scripts source tex)) {
next unless -d $dir;
- # theoretically we should use $whichformat, $sourceformat,
+ # theoretically we should use $whichformat, $sourceformat, etc.,
# but in practice they are always the same.
my $format = $whichdocformat;
my $destdir = $dir;
- if ($dir =~ /(lua)?(la)?tex/) { # tex/$format/$package
+ if ($dir =~ /(lua)?(la)?tex|code/) { # tex/$format/$package
$destdir = "tex";
} elsif ($dir =~ /metapost|scripts/) { # {metapost,scripts}/$package
$format = "";
Modified: trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc
===================================================================
--- trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc 2023-12-06 21:11:53 UTC (rev 69048)
+++ trunk/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc 2023-12-06 21:14:04 UTC (rev 69049)
@@ -1401,6 +1401,7 @@
depend truncate
depend tucv
depend turnthepage
+depend tutodoc
depend twoinone
depend twoup
depend txgreeks
Added: trunk/Master/tlpkg/tlpsrc/tutodoc.tlpsrc
===================================================================
More information about the tex-live-commits
mailing list.