% ==================== % % == RESOURCES USED == % % ==================== % \begin{filecontents*}[overwrite]{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*}[overwrite]{examples-version-n-change-user-choice-icon.tex} \begin{tdoctopic}{Don't look}[\faEyeSlash] % An icon from fontawesome5. \item Info 1... \item Info 2... \end{tdoctopic} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-version-n-change-user-choice.tex} \begin{tdoctopic}{End of icons} \item Info 1... \item Info 2... \end{tdoctopic} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-version-n-change-update.tex} \begin{tdocupdate} \item Info 1... \item Info 2... \end{tdocupdate} \end{filecontents*} \begin{filecontents*}[overwrite]{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*}[overwrite]{examples-version-n-change-first.tex} \tdocstartproj{1st version of the project.} \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-new.tex} \begin{tdocnew} \item Info 1... \item Info 2... \end{tdocnew} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-version-n-change-fix.tex} \begin{tdocfix} \item Info 1... \item Info 2... \end{tdocfix} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-exa-leavevmode.tex} \begin{tdocexa} \leavevmode \begin{enumerate} \item Point 1. \item Point 2. \end{enumerate} \end{tdocexa} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-important.tex} \begin{tdocimp} Important and harmless. \end{tdocimp} \begin{tdocimp}[Mini title] Useful? \end{tdocimp} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-note.tex} \begin{tdocnote} Something useful to tell you... \end{tdocnote} \begin{tdocnote}[Mini title] Useful? \end{tdocnote} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-caution.tex} \begin{tdoccaut} Caution, caution... \end{tdoccaut} \begin{tdoccaut}[Mini title] Useful? \end{tdoccaut} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-tip.tex} \begin{tdoctip} A tip. \end{tdoctip} \begin{tdoctip}[Mini title] Useful? \end{tdoctip} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-warn.tex} \begin{tdocwarn} Avoid the dangers... \end{tdocwarn} \begin{tdocwarn}[Mini title] Useful? \end{tdocwarn} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-exa.tex} \begin{tdocexa} An example... \end{tdocexa} \begin{tdocexa}[Mini title] Useful? \end{tdocexa} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-focus-rmk.tex} \begin{tdocrem} Just one remark... \end{tdocrem} \begin{tdocrem} Another? \end{tdocrem} \begin{tdocrem}[Mini title] Useful? \end{tdocrem} \end{filecontents*} \begin{filecontents*}[overwrite]{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*}[overwrite]{examples-listing-ABC.tex} \begin{tdoclatex}[sbs] $A = B + C$ \end{tdoclatex} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-listing-xyz.tex} % Just one demo. $x y z = 1$ \end{filecontents*} \begin{filecontents*}[overwrite]{examples-listing-strange.tex} \begin{tdoclatex}[std] [Strange... Or not!] \end{tdoclatex} \end{filecontents*} \begin{filecontents*}[overwrite]{examples-listing-strange-bis.tex} \begin{tdoclatex} \string[Strange... Or not!] \end{tdoclatex} \end{filecontents*} \begin{filecontents*}[overwrite]{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*}[overwrite]{examples-showcase-hook.tex} \begin{tdocshowcase} \string[This works...] \end{tdocshowcase} \end{filecontents*} \begin{filecontents*}[overwrite]{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*}[overwrite]{examples-showcase-external.tex} Blablobli, blablobli, blablobli, blablobli, blablobli, blablobli... \end{filecontents*} \begin{filecontents*}[overwrite]{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*}[overwrite]{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*} % ======================== % % == SOURCE FOR THE DOC == % % ======================== % \documentclass[10pt, a4paper]{article} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage[english]{babel, varioref} \usepackage{enumitem} \usepackage{fmtcount} \usepackage{multicol} \setlength{\parindent}{0em} \newcommand\thispack{\tdocpack{tutodoc}} % Package documented. \usepackage[lang = english]{tutodoc} % --------------- % % -- IMPORTANT -- % % --------------- % % % See the French version of this file for the text to be used % for languages other than English. % --------------- % % -- IMPORTANT -- % % --------------- % % % See the French version of this file for the text to be used % for languages other than English. % == FORDOC == % % Source. % * https://tex.stackexchange.com/a/604698/6880 \NewDocumentCommand{ \tdocdocbasicinput }{ m }{% Consider the following code. \tdoclatexinput[code]{#1} This will produce the following. \input{#1} } % == FORDOC == % % Source. % * https://tex.stackexchange.com/a/604698/6880 \NewDocumentCommand{ \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{ Start of the rendering in this doc. } O{ End of rendering in this doc. } }{ \tdocdocextraruler{#1} \nopagebreak\smallskip\nopagebreak }{ \nopagebreak\smallskip\nopagebreak \tdocdocextraruler{#2} } \begin{document} \title{The \texttt{tutodoc} package - Tutorial-style documentation} \author{Christophe BAL} \date{Sep 28, 2024 - Version 1.4.0} \maketitle \begin{abstract} The \thispack{} 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. \medskip Two important points to note. \begin{itemize} \item This package imposes a formatting style. In the not-too-distant future, \thispack{} will probably be split into a class and a package. \item This documentation is also available in French. \end{itemize} \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, \thispack{} 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 \thispack{} 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{keytheorems} package. } add a short title indicating the type of information provided. This short text will always be translated into the language indicated when the \thispack{} package is loaded. \end{tdocnote} \subsection{Content in the reading flow} % ------------------ % \begin{tdocimp} All the environments presented in this section share the same counter. \end{tdocimp} % ------------------ % \subsubsection{Examples} Numbered examples, if required, are indicated via \tdocenv{tdocexa}, which offers an optional argument for adding a mini-title. Here are two possible uses. \tdoclatexinput[sbs]{examples-focus-exa.tex} % ------------------ % \begin{tdocimp} The numbering of the examples is reset to zero as soon as a section with a level at least equal to a \tdocinlatex|\section| is opened. \end{tdocimp} % ------------------ % \begin{tdoctip} It can sometimes be useful to return to the line at the start of the content. The code below shows how to proceed (this trick also applies to the \verb#tdocrem# environment presented next). Note in passing that the numbering follows that of the previous example as desired. \end{tdoctip} \tdoclatexinput[sbs]{examples-focus-exa-leavevmode.tex} % \subsection{Content in the reading flow} \subsubsection{Some remarks} Everything happens via \tdocenv{tdocrem}, which works identically to the \tdocenv*{tdocexa} environment, as shown in the following example. \tdoclatexinput[sbs]{examples-focus-rmk.tex} \subsection{Flashy content} \label{tdoc-colorful-focus} \begin{tdocnote} Icons are obtained via the \tdocpack{fontawesome5} package, and text spacing is managed by the \tdocmacro{tdocicon} macro. \footnote{ For example, \tdocinlatex|\tdocicon{\faBed}{Tired}| produces\, \tdocicon{\faBed}{Tired}. } \end{tdocnote} \subsubsection{A tip} The \tdocenv*{tdoctip} environment is used to give tips. Here's how to use it. \tdoclatexinput[sbs]{examples-focus-tip.tex} \smallskip \begin{tdocnote} Colors are obtained via the expandable macros \tdocmacro{tdocbackcolor} and \tdocmacro{tdocdarkcolor}. For further information, please refer to the end of the section \ref{tdoc-color-macros} page \pageref{tdoc-color-macros}. \end{tdocnote} %\subsection{Flashy content} \subsubsection{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{Flashy content} \subsubsection{Something important} The \tdocenv*{tdocimp} environment is used to indicate something important but harmless. \tdoclatexinput[sbs]{examples-focus-important.tex} %\subsection{Flashy content} \subsubsection{Caution about a delicate point} The \tdocenv*{tdoccaut} environment is used to indicate a delicate point to the user. Here's how to use it. \tdoclatexinput[sbs]{examples-focus-caution.tex} %\subsection{Flashy content} \subsubsection{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... \\ \tdocenv[{[opt1]}]{env} \\ Just \tdocenv*{env}... \\ Finally \tdocenv*[{[opt1]}]{env}... \end{tdoclatex} \begin{tdocrem} Unlike \tdocmacro{tdocinlatex}, \tdocmacro{tdocenv} and \tdocmacro{tdocenv*} macros don't color the text they produce. In addition, \tdocinlatex{\tdocenv{monenv}} produces \tdocenv{monenv} with spaces to allow line breaks if required. \end{tdocrem} \begin{tdocwarn} The optional argument of the \tdocmacro{tdocenv} macro is copied and pasted \footnote{ Remember that almost anything is possible from now on. } when rendering. This may sometimes require the use of protective braces, as in the example above. \end{tdocwarn} \section{Origin of a prefix or suffix} To explain the names chosen, there is nothing like indicating and explaining the short prefixes and suffixes used. This is easily done as follows. \begin{tdoclatex}[sbs] \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} \label{tdoc-color-macros} \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. } \end{tdocexa} \input{examples-showcase-default.tex} \smallskip \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 \thispack{} 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've probably noticed that red is used as a base to obtain the colors used. \begin{itemize} \item The background color is provided by \tdocmacro{tdocbackcolor}. \item The color of titles and lines is provided by \tdocmacro{tdocdarkcolor}. \end{itemize} These expandable macros accept the following codes. \begin{tdoclatex}[code] % Argument 1 : optionally, the amount of color relative to black can be specified. % In general, there's no need to change this setting! % Argument 2 : a color in xcolor format. \NewExpandableDocumentCommand{\tdocdarkcolor}{O{50}m}{#2!#1!black} % Argument 1 : optionally, the transparency rate can be specified. % In general, there's no need to change this setting! % Argument 2 : a color in xcolor format. \NewExpandableDocumentCommand{\tdoclightcolor}{O{5}m}{#2!#1} \end{tdoclatex} You also have to know that behind the scene, the \tdocmacro{tdocruler} macro is used. \begin{tdoclatex}[std] \tdocruler{A decorated pseudo-title}{red} \end{tdoclatex} \end{tdocnote} % ------------------ % \begin{tdocwarn} With the default settings, if the code to be formatted begins with an opening bracket, use \tdocmacro{string} as in the following example. \tdoclatexinput[code]{examples-showcase-hook.tex} This will produce the following. \end{tdocwarn} \input{examples-showcase-hook.tex} \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} 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 class is best done through use cases showing both the code and the corresponding result. \footnote{ Code is formatted using the \tdocpack{minted} package. } \begin{tdoccaut} Version 3 of \tdocpack{minted} cannot be used at the moment, as it contains bugs: see \url{https://github.com/gpoore/minted/issues/401}. We therefore force the use of version 2 of minted. \end{tdoccaut} \subsection{\tdocquote{Inline} codes} \label{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 below. \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} % ------------------ % \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} \smallskip Another method is to use the \tdocmacro{string} primitive. \tdocdocbasicinput{examples-listing-strange-bis.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, expects the path of a file and offers the same options as the \tdocenv*{tdoclatex} environment. % ------------------ % \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 comes from \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 \thispack{}. \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} environment, 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{tdocimp} \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 \thispack{}: for example, if French is selected, the dates will be displayed in the format \texttt{DD/MM/YYYY}. \end{enumerate} \end{tdocimp} \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?} \thispack{} offers the macro \tdocmacro{tdocstartproj} and different environments to indicate quickly and clearly what has been done during the latest changes.% \footnote{ The user doesn't need all the technical details. } \begin{tdocnote} For icons, see the note at the beginning of the section \ref{tdoc-colorful-focus} page \pageref{tdoc-colorful-focus}. \end{tdocnote} % ------------------ % \begin{tdocexa}[Just for the very first version] \leavevmode \tdoclatexinput[sbs]{examples-version-n-change-first.tex} \end{tdocexa} % ------------------ % \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 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} % ------------------ % \begin{tdocexa}[For fixes] \leavevmode \tdoclatexinput[sbs]{examples-version-n-change-fix.tex} \end{tdocexa} % ------------------ % \begin{tdocexa}[Selectable themes with an icon] \leavevmode \tdoclatexinput[sbs]{examples-version-n-change-user-choice-icon.tex} \end{tdocexa} % ------------------ % \begin{tdocexa}[Selectable themes without icons] \leavevmode \tdoclatexinput[sbs]{examples-version-n-change-user-choice.tex} \end{tdocexa} \section{Ornaments} Let's finish this documentation with a small formatting tool that is very useful. \begin{tdoclatex}[sbs] Bla, bla, bla... \tdocsep % Practical for demarcation. This works with enumerations. \begin{itemize} \item Underline. \end{itemize} \tdocsep % Uniform behaviour. Ble, ble, ble... \end{tdoclatex} \section{History} \small \tdocversion{1.4.0}[2024-09-28] \begin{tdocbreak} \item The \tdocenv*{tdoccaution} environment has been renamed \tdocenv*{tdoccaut} for simplified input. \item Content highlighting: examples and remarks, indicated via the \tdocenv*{tdocexa} and \tdocenv*{tdocrem} environments, are always numbered, and share the same counter. \item The unused macro \tdocmacro{tdocxspace} has been deleted. \end{tdocbreak} \begin{tdocnew} \item Change log: the \tdocmacro{tdocstartproj} macro is used to manage the case of the first public version. \item Code factorization: the \tdocmacro{tdocicon} macro is responsible for adding icons in front of text. \end{tdocnew} \begin{tdocupdate} \item Colors: the \tdocmacro{tdocdarkcolor} and \tdocmacro{tdoclightcolor} macros offer an optional argument. \begin{enumerate} \item \tdocmacro{tdocdarkcolor} : the amount of color in relation to black can be optionally defined. \item \tdocmacro{tdoclightcolor} : the transparency rate can be optionally defined. \end{enumerate} \item Content highlighting: reduced space around content in colored frames. \item Versioning: better vertical spacing thanks to \tdocmacro{vphantom}. \end{tdocupdate} \tdocsep % ------------------ % \tdocversion{1.3.1}[2024-09-26] \begin{tdocnew} \item Star version of \tdocmacro{tdocenv} to display only the environment name. \end{tdocnew} \tdocsep % ------------------ % \tdocversion{1.3.0}[2024-09-25] \begin{tdocprob} \item Version 3 of \tdocpack{minted} cannot be used for the moment as it contains bugs: see \url{https://github.com/gpoore/minted/issues/401}. We therefore force the use of version 2 of \tdocpack{minted}. \end{tdocprob} \begin{tdocbreak} \item The \tdocenv*{tdocimportant} environment has been renamed \tdocenv*{tdocimp} for simplified input. \end{tdocbreak} \begin{tdocnew} \item Change log: proposed environments use icons. \item Content highlighting: colored frames with icons are proposed for the following environments. \bgroup \setlength\multicolsep{5pt} \begin{multicols}{3} \begin{enumerate}[topsep=0pt] \item \tdocenv*{tdoccaution} \item \tdocenv*{tdocimp} \item \tdocenv*{tdocnote} \item \tdocenv*{tdoctip} \item \tdocenv*{tdocwarn} \end{enumerate} \end{multicols} \egroup \end{tdocnew} \tdocsep % ------------------ % \tdocversion{1.2.0-a}[2024-08-23] \begin{tdocupdate} \item \tdocmacro{tdocversion} \begin{enumerate} \item The version number is above the date. \item The spacing is better managed when the date is absent. \end{enumerate} \end{tdocupdate} \begin{tdocfix} \item Content highlighting: the French translations of \tdocinEN*{caution} and \tdocinEN*{danger} were incorrect. \end{tdocfix} \tdocsep % ------------------ % \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. \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]}]{tdocshowcase}: page breaks around \tdocquote{framing} lines should be rare from now on. \end{tdocfix} \tdocsep % ------------------ % \tdocversion{1.0.0}[2023-11-29] \tdocstartproj{First public version of the project.} \end{document}