summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tutodoc/doc/tutodoc-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tutodoc/doc/tutodoc-en.tex')
-rw-r--r--macros/latex/contrib/tutodoc/doc/tutodoc-en.tex162
1 files changed, 116 insertions, 46 deletions
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}<nonb>
- Blo, blo, blo...
- \end{tdocexa}
+\begin{tdocexa}<nonb>
+ Blo, blo, blo...
+\end{tdocexa}
- \begin{tdocexa}<nonb>[Superb]
- Blu, blu, blu...
- \end{tdocexa}
+\begin{tdocexa}<nonb>[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