diff options
Diffstat (limited to 'macros/latex/contrib/tutodoc/doc/tutodoc-en.tex')
-rw-r--r-- | macros/latex/contrib/tutodoc/doc/tutodoc-en.tex | 162 |
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 |