% ********************************************************* %
% ** This is file `tutodoc.cls' generated automatically. ** %
% ** ** %
% ** Copyright (C) 2023-2024 by Christophe, BAL ** %
% ** ** %
% ** This file may be distributed and/or modified under ** %
% ** the conditions of the GNU 3 License. ** %
% ********************************************************* %
\ProvidesExplClass
{tutodoc}
{2024-12-18} % Creation: 2023-11-29
{1.7.1}
{This package proposes tools for writing "human friendly" documentations of LaTeX packages.}
% ================== %
% == \CLS OPTIONS == %
% ================== %
%%%
% refs::
% + https://tex.stackexchange.com/a/729929/6880
% + https://tex.stackexchange.com/a/729913/6880
%%%
\ExplSyntaxOn
\msg_set:nnnn { tutodoc ~ (main) }
{ main : scrartcl-illegal-option }
{ The ~ option ~ << ~ #1 ~ >> ~ is ~ not ~ allowed. }
{ \msg_see_documentation_text:n { tutodoc } }
%%%
% The theme is identified by the following macro that can be changed
% when the class is loaded.
%%%
\newcommand{\tutodoc@theme}{color}
%%%
% prototype::
% theme : the theme to format the document.
% fontsize : this key is one of those of the '''scrartcl'' class.
% As \tutodoc imposes the value of this key, we must
% forbid its use.
% DIV : similar to the preceding key but here we just want
% to avoid any use of special ''DIV'' value.
%%%
\keys_define:nn { tutodoc / main / class / options } {
theme .choices:nn = {
bw,
color,
dark,
draft
} {
\exp_args:NNV \renewcommand \tutodoc@theme \l_keys_choice_tl
},
fontsize .code:n = {
\msg_error:nnn { tutodoc ~ (main) }
{ main : scrartcl-illegal-option }
{ fontsize }
},
DIV .code:n = {
\msg_error:nnn { tutodoc ~ (main) }
{ main : scrartcl-illegal-option }
{ DIV }
},
}
\PassOptionsToClass{ fontsize = 10pt }{ scrartcl }
\DeclareUnknownKeyHandler[ tutodoc / main / class / options ]{
\PassOptionsToClass{ \CurrentOption }{ scrartcl }
}
\ProcessKeyOptions[ tutodoc / main / class / options ]
\LoadClass{ scrartcl }
\ExplSyntaxOff
% =============================================== %
% == OPTIONS FOR \PACKS IMPORTED BY OTHER ONES == %
% =============================================== %
% ''xcolor'' will be loaded by ''minted'' and ''tcolorbox'' below.
\PassOptionsToPackage{svgnames}{xcolor}
% ============= %
% == IMPORTS == %
% ============= %
\RequirePackage{geometry}
\RequirePackage{marginnote}
\RequirePackage{fontawesome5}
\RequirePackage{keytheorems}
\RequirePackage{clrstrip}
% Special settings for ''minted'' need to be done before the loading
% of the ''tcolorbox'' library ''minted''.
\RequirePackage[highlightmode = immediate]
{minted}
\RequirePackage{tcolorbox}
\tcbuselibrary{
minted,
breakable,
skins
}
\RequirePackage{hyperref}
%%%
% We delegate the management of quoting to the ''csquotes'' package,
% which takes care of the locale settings.
%
% warning::
% We must load ''inputenc'' before ''csquotes''
%%%
\RequirePackage[utf8]
{inputenc}
\RequirePackage{csquotes}
% ===================== %
% == LOCALE SETTINGS == %
% ===================== %
\ExplSyntaxOn
\msg_set:nnnn { tutodoc ~ (main) }
{ main : unsupported-lang }
{
unsupported ~ language ~ << ~ #1 ~ >>. %
~ %
We ~ will ~ use ~ << ~ en ~ >>.
}
{ \msg_see_documentation_text:n { tutodoc } }
% Babel requires colon management for our translations.
\newcommand{\tutodoc@colon}{:}
\AtBeginDocument{
%%%
% Settings if ''babel'' \pack is used.
%%%
\@ifpackageloaded{babel}{
% We must take care of spacings with colons.
\iflanguage{french}{
\renewcommand{\tutodoc@colon}{\babelshorthand{:}}
}{}
}{}
%%%
% Settings if ''polyglossia'' \pack is used.
%%%
\@ifpackageloaded{polyglossia}{
% If ''polyglossia'' is used, we must load english if necessary
% (see the ''\tutodoc@use@english'' macro below).
\iflanguageloaded{english}{}{
\setotherlanguage{english}
}
}{}%
% Standard way to find the \lang to use.
\newcommand{\tdoclang}{\BCPdata{language}}
% We must take care of English rules for English contents.
\newcommand\tutodoc@use@english{%
\foreignlanguage{english}%
}
% If the \lang is not supported, we emit a warning and just use
% the english language.
\makeatletter
\InputIfFileExists{tutodoc-\tdoclang.loc.cls}{}{
\input{tutodoc-en.loc.cls}
\msg_critical:nnx { tutodoc ~ (main) }
{ main : unsupported-lang }
{ \tdoclang }
}
\makeatother
}
\ExplSyntaxOff
% =================== %
% == PAGE GEOMETRY == %
% =================== %
\geometry{
top = 1.9cm,
bottom = 1.9cm,
left = 2.25cm,
right = 2.25cm,
marginparwidth = 2cm,
marginparsep = 2pt,
heightrounded
}
\setlength{\parindent}{0cm}
% ================== %
% == TITLES & TOC == %
% ================== %
\renewcommand{\thesection}{\Roman{section}}
\renewcommand{\thesubsection}{\arabic{subsection}}
\renewcommand{\thesubsubsection}{\alph{subsubsection}}
% 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
}
% =========================== %
% == COLOR TRANSFORMATIONS == %
% =========================== %
%%%
% prototype::
% #1 : (black-rate)
% the amount of color relative to black.
% #2 : (color)
% one color following the ''color'' format.
%
% :return: a "darker" version of the color ''#1''.
%%%
\NewExpandableDocumentCommand{\tdocdarkcolor}{ O{50} m }{#2!#1!black}
%%%
% prototype::
% #1 : (transparency)
% the transparency rate.
% #2 : (color)
% one color following the ''color'' format.
%
% :return: a "transparent" version of the color `#1`.
%%%
\NewExpandableDocumentCommand{\tdoclightcolor}{ O{5} m }{#2!#1}
% =========== %
% == ICONS == %
% =========== %
%%%
% prototype::
% #1 : (aws-icon)
% one material that expects to be an icon command from the
% ''fontawsome5'' \pack.
%
% :return: the icon followed by a small insecable space.
%%%
\NewDocumentCommand{\tdocicon}{ m }{%
#1\kern.45em%
}
% ============== %
% == LISTINGS == %
% ============== %
%%%
% We use a \std \latex boolean to switch on or off lexers for listings
% (this allows the ''draft'' mode to display listings in verbatim).
%%%
\newif\ifcodenolexer
\codenolexerfalse
\ExplSyntaxOn
%%%
% prototype::
% #1 : (style-abbrev)
% a shortcut for a \tcolorbox styling command.
% @ #1 in [code, sbs, std]
%
% In the following easy-to-understand macro, we use one fictive \tcolorbox
% style such as to indicate an unknown ''tutodoc'' shortcut style. For example,
% this will give the following message if the user type ''MISTYPED-STYLE''.
%
% term::
% Package pgfkeys Error: I do not know the key '/tcb/[[tutodoc : tdoclatex
% bad option "MISTYPED-STYLE"]]' and I am going to ignore it. Perhaps you
% misspelled it.
%
% See the pgfkeys package documentation for explanation.
%%%
\NewExpandableDocumentCommand{\tdoctcb}{ m }{
\str_case:nnF { #1 } {
{ sbs } { listing ~ side ~ text }
{ code } { listing ~ only }
{ std } { listing ~ and ~ text }
} {
[[tutodoc ~ : ~ LaTeX ~ listing ~ illegal ~ style ~ "#1"]]
}
}
\ExplSyntaxOff
% ============================== %
% == THEME - GENERAL SETTINGS == %
% ============================== %
\input{tutodoc-\tutodoc@theme.css.cls}
\pagecolor{tutodoc@page@color}
\color{tutodoc@text@color}
\hypersetup{
colorlinks,
citecolor = tutodoc@link@color,
filecolor = tutodoc@link@color,
linkcolor = tutodoc@link@color,
urlcolor = tutodoc@link@color
}
% ============= %
% == QUOTING == %
% ============= %
%%%
% prototype::
% #1 : (text)
% a text to quote.
%
% For example, ''\tdocquote{Something}'' prints **"Something"**.
%%%
\NewDocumentCommand{\tdocquote}{ m }{%
\enquote{\emph{#1}}%
}
% ============================== %
% == EXPLAINING ENGLISH WORDS == %
% ============================== %
%%%
% prototype::
% #1 : (EN-text)
% an english text that will be explained in another \lang.
%
% :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"**.
%
% 3) ''\tdocinEN*{Something} et \tdocinEN{Another thing}''
% gives
% **"Something" et "Another thing" en anglais**.
%%%
\NewDocumentCommand{\tdocinEN}{ s m }{%
\IfBooleanTF{#1}{}{\tutodoc@trans@in@EN}%
% We must activate the English typesetting rules.
{%
\tdocquote{\tutodoc@use@english{#2}}%
}%
}
% =========================== %
% == HIGHLIGHTING CONTENTS == %
% =========================== %
% ---------------------- %
% -- EXAMPLE & REMARK -- %
% ---------------------- %
\ExplSyntaxOn
%%%
% We use a ''seq'' variable to factorize the code just after.
%%%
\seq_new:N \g__tutodoc_focus_std_seq
\seq_set_from_clist:Nn \g__tutodoc_focus_std_seq {
exa,
rem
}
%%%
% Themes define specific vertical spacings.
%%%
\newkeytheoremstyle{tutodoc@admonition@exa@style}{
spaceabove = \tutodoc@admonition@space@below,
spacebelow = \tutodoc@admonition@space@below
}
%%%
% prototype::
% :action: looping over ''\g__tutodoc_focus_std_seq'' to build new
% numbered theorems sharing the same section level counter.
% To achieve that, we use the ''\newkeytheorem'' macro from
% the ''keytheorems'' \pack.
%%%
\seq_map_inline:Nn \g__tutodoc_focus_std_seq {
\str_if_eq:nnTF { #1 } { exa } {
\newkeytheorem{tdoc#1}[
name = \use:c { tutodoc@trans@#1@title },
within = section,
style = tutodoc@admonition@exa@style
]
} {
\newkeytheorem{tdoc#1}[
name = \use:c { tutodoc@trans@#1@title },
numberlike = tdocexa,
style = tutodoc@admonition@exa@style
]
}
\cs_set:cpn { the tdoc #1 } { \thesection.\arabic{tdoc#1} }
}
\ExplSyntaxOff
% ----------------- %
% -- ADMONITIONS -- %
% ----------------- %
%%%
% note::
% We provide two ways to define admonitions.
%
% 1) ''\g__tutodoc_focus_color_prop'' and ''g__tutodoc_focus_icon_prop''
% are for iconised and colored frames.
%
% 1) ''\g__tutodoc_focus_color_seq'' is to use a dedicated basic theorem
% (this should be only useful for the draft theme).
%
%
% warning::
% The variables should be defined inside the themes!
%
%
% refs::
% + https://tex.stackexchange.com/a/727022/6880
% + https://tex.stackexchange.com/a/682332/6880
% + https://tex.stackexchange.com/a/623232/6880
%%%
\ifcsundef{g__tutodoc_focus_color_seq}{
\tcbset{
tutodoc-focus-color-style/.style = {
% General.
use color stack, % Must be before breakable!
breakable,
enhanced,
% Colors.
coltitle = \tutodoc@build@title@color{#1},
colupper = \tutodoc@build@upper@color{#1},
colback = \tutodoc@build@back@color{#1},
colframe = \tutodoc@build@frame@color{#1},
% We want to use the same color for the footnotes in the frame.
before upper = {\let\default@color\current@color},
% Padding.
left = 3pt,
right = 3pt,
arc = 2pt,
% Frame.
shadow = {.75mm}{-.75mm}{0mm}{tutodoc@admonition@shadow@color},
}
}
}{}
\ExplSyntaxOn
\ifcsundef{g__tutodoc_focus_color_seq}{
%%%
% prototype::
% :action: ''key/value'' iteration over ''\g__tutodoc_focus_color_prop''
% to build new colorful unumbered theorems. To achieve that,
% we use a \tcolorbox style given to the ''\newkeytheorem''
% macro from the ''keytheorems'' \pack, and icons from the
% ''fontawesome5'' \pack.
%%%
\prop_map_inline:Nn \g__tutodoc_focus_color_prop {
\newkeytheorem{tdoc#1}[
numbered = false,
% tcolorbox-no-titlebar can be used.
tcolorbox = {tutodoc-focus-color-style=#2},
name = {
\tdocicon{ \prop_item:Nn \g__tutodoc_focus_icon_prop { #1 } }
\use:c { tutodoc@trans@#1@title }
}
]
}
} {
%%%
% prototype::
% :action: looping over ''\g__tutodoc_focus_color_seq'' to build new
% numbered theorems sharing the same section level counter.
% To achieve that, we use the ''\newkeytheorem'' macro from
% the ''keytheorems'' \pack.
%%%
\seq_map_inline:Nn \g__tutodoc_focus_color_seq {
\newkeytheorem{tdoc#1}[
name = \use:c { tutodoc@trans@#1@title },
numberlike = tdocexa,,
style = tutodoc@admonition@exa@style,
% Some hooks...
preheadhook = \small,
postheadhook = \leavevmode,
postfoothook = \normalsize
]
}
}
\ExplSyntaxOff
% ========================================= %
% == \PACKS, \CLSS, MACROS & \ENVS NAMES == %
% ========================================= %
%%%
% prototype::
% #1 : (cls-name)
% the name of a class
%
% :action: ''\tdoccls{myclass}'' prints verb::''myclass''.
%%%
\NewDocumentCommand{\tdoccls}{ m }{%
\texttt{#1}%
}
%%%
% prototype::
% #1 : (pck-name)
% the name of a package
%
% :action:''\tdocpack{mypack}'' prints verb::''mypack''.
%%%
\NewDocumentCommand{\tdocpack}{ m }{%
\texttt{#1}%
}
%%%
% prototype::
% #1 : (cmd-name)
% the name of a macro
%
% :action: ''\tdocmacro{mymacro}'' prints verb::''\mymacro''.
%%%
\NewDocumentCommand{\tdocmacro}{ m }{%
\texttt{\textbackslash{}#1}%
}
%%%
% prototype::
% #1 : (env-name)
% the name of an environment
%
% :extra: this macro has a star version.
%
% Here are the different outputs available.
%
% 1) ''\tdocenv{myenv}'' prints
% verb::''\begin{myenv} ... \end{myenv}''.
%
% 2) ''\tdocenv*{myenv}'' prints
% verb::''myenv''.
%%%
\NewDocumentCommand{\tdocenv}{ s m }{%
\IfBooleanTF{#1}{%
\texttt{#2}%
}{%
% Source: https://tex.stackexchange.com/a/703379/6880 .
\texttt{\string\begin\string{#2\string} %
\!\!...\@\!\!\! %
\string\end\string{#2\string}}%
}%
}
% ========================= %
% == EXPLAINING PREFIXES == %
% ========================= %
\ExplSyntaxOn
\msg_set:nnnn { tutodoc ~ (macroenv) }
{ macroenv : prefix-why-bad-format }
{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. }
{ You ~ must ~ use ~ one ~ single ~ point. }
% -------------------- %
% -- PREFIX FROM... -- %
% -------------------- %
\seq_new:N \l__tutodoc_prewhy_parts_seq
\int_new:N \l__tutodoc_prewhy_nbparts_int
\tl_new:N \l__tutodoc_pretext_tl
\tl_new:N \l__tutodoc_posttext_tl
%%%
% prototype::
% #1 : (pre.fix)
% 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__tutodoc_prewhy_parts_seq { . } { #1 }
\int_set:Nn \l__tutodoc_prewhy_nbparts_int
{\int_eval:n {\seq_count:N \l__tutodoc_prewhy_parts_seq}}
\if_int_compare:w \l__tutodoc_prewhy_nbparts_int = 2
\else:
\msg_error:nn { tutodoc ~ (macroenv) }
{ macroenv : prefix-why-bad-format }
\fi:
% Let's go.
\seq_pop:NN \l__tutodoc_prewhy_parts_seq \l__tutodoc_pretext_tl
\seq_pop:NN \l__tutodoc_prewhy_parts_seq \l__tutodoc_posttext_tl
\textbf{
\tdocpre{\tl_use:N \l__tutodoc_pretext_tl}
\kern.5pt
\textperiodcentered
\kern.5pt
{\tl_use:N \l__tutodoc_posttext_tl}
}
}
\ExplSyntaxOff
% --------------------- %
% -- JUST ONE PREFIX -- %
% --------------------- %
%%%
% prototype::
% #1 : (pre)
% 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}%
}
% ======================== %
% == TEXT BETWEEN RULES == %
% ======================== %
\ExplSyntaxOn
\box_new:N \l__tutodoc_content_box
\dim_new:N \l__tutodoc_content_dim
%%%
% prototype::
% #1 : (color)
% the color for the rule and the text
% #2 : (text)
% the text surrounded by two horizontal rules
%
% :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}{
O{\tutodoc@showcase@rule@color}
m
}{
\par
{
\centering
\scriptsize
\itshape
\bfseries
\color{#1}
\hbox_set:Nn \l__tutodoc_content_box { \,\, #2 \,\, }
\dim_set:Nn \l__tutodoc_content_dim {
.35 \linewidth - .5 \box_wd:N \l__tutodoc_content_box
}
\rule[.75pt] { \dim_use:N \l__tutodoc_content_dim }
{ 2.5pt }
\box_use:N \l__tutodoc_content_box
\rule[.75pt] { \dim_use:N \l__tutodoc_content_dim }
{ 2.5pt }
\par
}
}
\ExplSyntaxOff
% ============== %
% == SHOWCASE == %
% ============== %
% --------------------------- %
% -- INTERNAL ENVIRONMENTS -- %
% --------------------------- %
%%%
% prototype::
% #1 : (up-text)
% the descriptive text before the real output
% #2 : (down-text)
% the descriptive text after the real output
% #3 : (color)
% one color used to set the one for the decorated texts printed
% corresponding to the two first arguments.
% #4 : (rule color builder)
% the macro used to build the color from the user's rule color
%
% :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{tutodoc@showcase@rules}{ m m m m }{%
\tdocruler[#4{#3}]{#1}%
\nopagebreak\medskip\nopagebreak%
}{%
\nopagebreak\medskip\nopagebreak%
\tdocruler[#4{#3}]{#2}%
}
%%%
% prototype::
% #1 .. #4 : :see: env.tutodoc@showcase@rules
% #5 : (back color builder)
% the macro used to build the color from the user's back color
%
% :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{tutodoc@showcase@colorstrip}{ m m m m m }{
\begin{colorstrip}{#5{#3}}%
\begin{tutodoc@showcase@rules}{#1}{#2}{#3}{#4}%
}{%
\end{tutodoc@showcase@rules}%
\end{colorstrip}
}
\ExplSyntaxOn
% ----------------------- %
% -- SETTING SOME KEYS -- %
% ----------------------- %
\tl_new:N \g_tutodoc_showcase_style_tl
\tl_new:N \l_tutodoc_showcase_before_tl
\tl_new:N \l_tutodoc_showcase_after_tl
\tl_new:N \l_tutodoc_showcase_stripe_color_tl
\tl_new:N \l_tutodoc_showcase_text_color_tl
%%%
% prototype::
% col-stripe : the color of the stripe
% col-text : the color of the descriptive texts
% nostripe : a boolean flag to avoid the use of a stripe
% before : the descriptive text before the real output
% after : the descriptive text after the real output
%%%
\keys_define:nn { tutodoc / showcase } {
% Style?
style .choices:nn = {
minimal,
rule,
stripe
} {
\tl_gset:Nx \g_tutodoc_showcase_style_tl {#1}
},
% Colors.
col-stripe .tl_set:N = \l_tutodoc_showcase_stripe_color_tl,
col-stripe .initial:n = \tutodoc@showcase@stripe@color,
col-text .tl_set:N = \l_tutodoc_showcase_text_color_tl,
col-text .initial:n = \tutodoc@showcase@text@color,
% Texts.
before .tl_set:N = \l_tutodoc_showcase_before_tl,
before .initial:n = \tutodoc@trans@latex@show@start,
after .tl_set:N = \l_tutodoc_showcase_after_tl,
after .initial:n = \tutodoc@trans@latex@show@end,
}
% ------------------------------ %
% -- SHOWCASE FROM TYPED CODE -- %
% ------------------------------ %
% prototype::
% #1 : (key-val options)
% :see: l3keys(tutodoc / showcase)
%
% :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.tutodoc@showcase@rules ,
% env.tutodoc@showcase@colorstrip
%%%
\NewDocumentEnvironment{tdocshowcase}{ O{} }{
\group_begin:
\tl_gset:Nn \g_tutodoc_showcase_style_tl {minimal}
\keys_set:nn { tutodoc / showcase } { #1 }
\str_case:Nn { \g_tutodoc_showcase_style_tl } {
{ minimal } {
\smallskip\par
}
{ rule } {
\smallskip
\begin{tutodoc@showcase@rules}
{ \tl_use:N \l_tutodoc_showcase_before_tl }
{ \tl_use:N \l_tutodoc_showcase_after_tl }
{ \tl_use:N \l_tutodoc_showcase_stripe_color_tl }
{ \tutodoc@showcase@build@rule@color }
}
{ stripe } {
\begin{tutodoc@showcase@colorstrip}
{ \tl_use:N \l_tutodoc_showcase_before_tl }
{ \tl_use:N \l_tutodoc_showcase_after_tl }
{ \tl_use:N \l_tutodoc_showcase_stripe_color_tl }
{ \tutodoc@showcase@build@rule@color }
{ \tutodoc@showcase@build@back@color }
}
}
\color{ \tl_use:N \l_tutodoc_showcase_text_color_tl }
}{
\str_case:Nn { \g_tutodoc_showcase_style_tl } {
{ rule } {
\end{tutodoc@showcase@rules}
}
{ stripe } {
\end{tutodoc@showcase@colorstrip}
}
}
\group_end:
}
% ------------------------ %
% -- SHOWCASE FROM FILE -- %
% ------------------------ %
\tl_new:N \l__tutodoc_showcase_options_tl
%%%
% prototype::
% #1 : (key-val options)
% :see: env.tdocshowcase
% #2 : (file path)
% the path of a file
%%%
\NewDocumentCommand{\tdocshowcaseinput}{ O{} m }{
\begin{tdocshowcase}[#1]
\input{#2}
\end{tdocshowcase}
}
\ExplSyntaxOff
% ==================== %
% == LATEX EXAMPLES == %
% ==================== %
% ----------------------------- %
% -- INLINE LATEX CODE MACRO -- %
% ----------------------------- %
%%%
% See the \doc of the macro ''\newmintinline'' from the package \minted
% to have \infos about the macro ''tdoclatexin''.
%%%
\newmintinline[tdoclatexin]{\tutodoc@latex@lexer}{
bgcolor = tutodoc@latex@back@color,
style/.expand once = \tutodoc@latex@style
}
% ------------------------------------------------ %
% -- MINTED/TCOLORBOX LATEX LISTING ENVIRONMENT -- %
% ------------------------------------------------ %
%%%
% prototype::
% #1 : (minted-like-options)
% a list of legal \minted options.
% #2 : (tcolorbox-styling-commands)
% you can override the default \tcolorbox settings with the help
% of the macro ''\tdoctcb''.
%
% :see: macro.tdoctcb
%
% refs::
% + https://tex.stackexchange.com/a/604821/6880
% + https://tex.stackexchange.com/a/327983/6880
%%%
\tcbset{
tutodoc-latex-listing-style/.style 2 args = {
% General.
minted language/.expand once = \tutodoc@latex@lexer,
minted style/.expand once = \tutodoc@latex@style,
breakable,
enhanced,
% Colors.
colframe = tutodoc@latex@frame@color,
colback = tutodoc@latex@back@color,
colupper = tutodoc@latex@text@color,
collower = tutodoc@latex@text@color,
% Padding.
boxsep = 0pt,
left = \tutodoc@latex@left@len,
right = \tutodoc@latex@right@len,
bottom = \tutodoc@latex@bottom@len,
top = \tutodoc@latex@top@len,
% Frame.
shadow = {\tutodoc@latex@shadow@xshift@len}%
{\tutodoc@latex@shadow@yshift@len}%
{\tutodoc@latex@shadow@offset@len}%
{tutodoc@latex@shadow@color},
arc = \tutodoc@latex@arc@len,
leftrule = \tutodoc@latex@left@rule@len,
rightrule = \tutodoc@latex@right@rule@len,
bottomrule = \tutodoc@latex@bottom@rule@len,
toprule = \tutodoc@latex@top@rule@len,
% Separating line.
segmentation style = {
tutodoc@latex@segment@color,
dash pattern = {on 5pt off 2.5pt},
line width = .75pt
},
% Extra minted otpions.
minted options = {#1},
% Extra tcolorbox styles.
#2
},
}
%%%
% prototype::
% #1 : (minted-like-options)
% :see: tcbset(tutodoc-latex-listing-style)
% #2 : (tcolorbox-styling-commands)
% :see: tcbset(tutodoc-latex-listing-style)
%
% note::
% See the \doc of the macro ''\newtcblisting'' from the package
% \tcolorbox to have \infos about the environment ''tdoclatex''.
%%%
\NewTCBListing{tdoclatex}{ O{} D<>{} }{%
tutodoc-latex-listing-style = {#1}{#2}
}
% -------------------------------------- %
% -- TCOLORBOX IMPORTED LISTING MACRO -- %
% -------------------------------------- %
%%%
% prototype::
% #1 : (minted-like-options)
% :see: tcbset(tutodoc-latex-listing-style)
% #2 : (tcolorbox-styling-commands)
% :see: tcbset(tutodoc-latex-listing-style)
% #3 : (file path)
% 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}{ O{} D<>{} m }{
listing file = {#3},
tutodoc-latex-listing-style = {#1}{#2}
}
% ===================== %
% == LATEX USE CASES == %
% ===================== %
\ExplSyntaxOn
% --------------------- %
% -- SETTING THE KEY -- %
% --------------------- %
\tl_new:N \l_tutodoc_listing_explain_tl
%%%
% prototype::
% explain : the text between the code and its highlighted output.
%
% note::
% This key can be used in addition to those of the ''tdocshowcase''
% \env,
%%%
\keys_define:nn { tutodoc / listing / latexshow } {
explain .tl_set:N = \l_tutodoc_listing_explain_tl,
explain .initial:n = { \tutodoc@trans@this@gives \tutodoc@colon },
}
% --------------------- %
% -- LATEXSHOW MACRO -- %
% --------------------- %
\tl_new:N \l__tutodoc_showcase_options_passed_tl
%%%
% prototype::
% #1 : (key-val options)
% :see: l3keys(tutodoc / listing / latexshow) ,
% l3keys(tutodoc / showcase)
% #2 : (file path)
% the path of a file
%
% :see: env.tdocshowcase ,
% macro.tdoclatexinput
%%%
\NewDocumentCommand{\tdoclatexshow}{ O{} m} {
\group_begin:
\keys_set_known:nnN { tutodoc / listing / latexshow }
{ #1 }
\l__tutodoc_showcase_options_passed_tl
\tdoclatexinput<\tdoctcb{code}>{#2}
\tl_use:N \l_tutodoc_listing_explain_tl
% Source: https://tex.stackexchange.com/a/696700/6880
\exp_last_unbraced:NNV \tdocshowcaseinput [\l__tutodoc_showcase_options_passed_tl] {#2}
\group_end:
}
\ExplSyntaxOff
% ========================= %
% == LISTINGS - AGNOSTIC == %
% ========================= %
% ---------------------------------- %
% -- DOES THE THEME AVOID LEXERS? -- %
% ---------------------------------- %
\NewExpandableDocumentCommand{\tutodoc@code@lexer}{ m }{%
\ifcodenolexer text\else #1\fi%
}
% ---------------------------------- %
% -- INLINE GENERALIST CODE MACRO -- %
% ---------------------------------- %
%%%
% prototype::
% #1 : (minted-like-options)
% a list of legal \minted options.
% #2 : (coding-lang)
% the name of the \minted lexer corresponding to the coding langage
% for the formating.
%
% warning::
% There are only two arguments, because the \mintinline macro will eat
% the bit of inline code to be colored.
%%%
\NewDocumentCommand{\tdoccodein}{ O{} m }{%
\mintinline[
bgcolor = tutodoc@code@back@color,
style/.expand once = \tutodoc@code@style,
#1
]{\tutodoc@code@lexer{#2}}%
}
% ----------------------------------------------------- %
% -- MINTED/TCOLORBOX GENERALIST LISTING ENVIRONMENT -- %
% ----------------------------------------------------- %
%%%
% prototype::
% #1 : (minted-like-options)
% :see: macro.tdoccodein
% #2 : (tcolorbox-styling-commands)
% you can override the default \tcolorbox settings with the help
% of the macro ''\tdoctcb''.
% #3 : (coding-lang)
% :see: macro.tdoccodein
%
% :see: macro.tdoctcb
%
% refs::
% + https://tex.stackexchange.com/a/604821/6880
% + https://tex.stackexchange.com/a/327983/6880
%%%
\tcbset{
tutodoc-full-listing-style/.style n args = {3}{
% General.
minted style/.expand once = \tutodoc@code@style,
minted language/.expand once = \tutodoc@code@lexer{#3},
breakable,
enhanced,
% Colors.
colframe = tutodoc@code@frame@color,
colback = tutodoc@code@back@color,
colupper = tutodoc@code@text@color,
collower = tutodoc@code@text@color,
% Padding.
boxsep = 0pt,
left = \tutodoc@code@left@len,
right = \tutodoc@code@right@len,
bottom = \tutodoc@code@bottom@len,
top = \tutodoc@code@top@len,
% Frame.
shadow = {\tutodoc@code@shadow@xshift@len}%
{\tutodoc@code@shadow@yshift@len}%
{\tutodoc@code@shadow@offset@len}%
{tutodoc@code@shadow@color},
arc = \tutodoc@code@arc@len,
leftrule = \tutodoc@code@left@rule@len,
rightrule = \tutodoc@code@right@rule@len,
bottomrule = \tutodoc@code@bottom@rule@len,
toprule = \tutodoc@code@top@rule@len,
% Separating line.
segmentation style = {
tutodoc@code@segment@color,
dash pattern = {on 5pt off 2.5pt},
line width = .75pt
},
listing only,
% Extra minted otpions.
minted options = {#1},
% Extra tcolorbox styles.
#2
},
}
%%%
% prototype::
% #1 : (minted-like-options)
% :see: macro.tdoccodein
% #2 : (tcolorbox-styling-commands)
% :see: \tcbset{tutodoc-full-listing-style}
% #3 : (coding-lang)
% :see: macro.tdoccodein
%
% note::
% See the \doc of the macro ''\NewTCBListing'' from the package
% \tcolorbox to have \infos about the environment ''tdoccode''.
%%%
\NewTCBListing{tdoccode}{ O{} D<>{} m }{%
tutodoc-full-listing-style = {#1}{#2}{#3}
}
% -------------------------------------- %
% -- TCOLORBOX IMPORTED LISTING MACRO -- %
% -------------------------------------- %
%%%
% prototype::
% #1 : (minted-like-options)
% :see: macro.tdoccodein
% #2 : (tcolorbox-styling-commands)
% :see: \tcbset{tutodoc-full-listing-style}
% #3 : (coding-lang)
% :see: macro.tdoccodein
% #4 : (file path)
% 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 ''\tdoccodeinput''.
%%%
\NewTCBInputListing{\tdoccodeinput}{ O{} D<>{} m m }{
listing file = {#4},
tutodoc-full-listing-style = {#1}{#2}{#3}
}
% == CHANGES - WHEN? --%
\ExplSyntaxOn
\msg_set:nnnn { tutodoc ~ (version-n-change) }
{ version-n-change : date-bad-format }
{ Bad ~ format ~ for ~ a ~ date. }
{ Use ~ YYYY-MM-DD. }
% ----------------- %
% -- MARGIN NOTE -- %
% ----------------- %
\reversemarginpar{}
%%%
% prototype::
% #1 : (color)
% the color of the margin note
% #2 : (up-text)
% the first material (a version number or nothing)
% #3 : (down-text)
% the second material (a date or nothing)
% #4 : (spacing)
% the last negative vertical spacing for the 2nd rule
% #5 : (vertical offset)
% algebraic distance to move vertically the material
%
% :action: this macro factorizes the printing of the changes
% in the left margin.
%
% :see: \__tutodoc_translate_date:n
%%%
\NewDocumentCommand{\tutodoc@new@change@margin}{ m m m m m }{
\marginnote{
\color{#1}
\scriptsize
\normalfont
\centering
\vspace{0pt}
\rule{1.65cm}{.95pt}
\vspace{-2.9pt}
\IfBlankTF{#2}{}{
\par
#2\vphantom{Mp}
\par
}
\IfBlankTF{#3}{}{
\IfBlankTF{#2}{}{
\vspace{1pt}
}
\par
\__tutodoc_translate_date:n { #3 }
\vphantom{Mp}
\par
}
\vspace{#4}
\rule{1.65cm}{.95pt}
}[#5]
}
%%%
% prototype::
% #1 : (EN-num-date)
% a content that should have the numerical English date
% format ''YYYY-MM-DD''.
%
% :action: this function checks if we have something like
% ''YYYY-MM-DD'', and then it calls the function
% ''\__tutodoc_translate_date_process:w'' to
% activate the transformation to the locale format.
%
% :see: \__tutodoc_translate_date_process:w
%%%
\cs_new:Nn \__tutodoc_translate_date:n {
\regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{
\__tutodoc_translate_date_process:w #1 \q_stop
}{
\msg_error:nn { tutodoc ~ (version-n-change) }
{ version-n-change : date-bad-format }
}
}
%%%
% prototype::
% #1 : (year-extracted)
% a 1 to 4 digits integer
% #2 : (month-extracted)
% a 2 digits integer
% #3 : (day-extracted)
% a 2 digits integer
%
% :action: this function extracts year, month and day in something
% like ''YYYY-MM-DD'' and then it calls ''\tutodoc@trans@date''
% to use the format expected for a "localised" date.
%%%
\cs_new:Npn \__tutodoc_translate_date_process:w #1 - #2 - #3 \q_stop {
\tutodoc@trans@date{#1}{#2}{#3}
}
\ExplSyntaxOff
% ---------------------- %
% -- VERSION AND DATE -- %
% ---------------------- %
\newlength{\tutodoc@version@date@vertical@sep@len}
\setlength{\tutodoc@version@date@vertical@sep@len}{-4.25pt}
\newlength{\tutodoc@version@date@vertical@offset@len}
\setlength{\tutodoc@version@date@vertical@offset@len}{-8pt}
%%%
% prototype::
% #1 : (color)
% the color of the margin note
% #2 : (version)
% a version number
% #3 : (date)
% a date ''YYYY-MM-DD''
% #4 : (vertical offset)
% algebraic distance to move vertically the material
%
% :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{\tutodoc@changes@when@color} %
m %
O{} %
D<>{\tutodoc@version@date@vertical@offset@len}%
}{
\tutodoc@new@change@margin%
{#1} % Color
{#2} % Version
{#3} % Date
{\tutodoc@version@date@vertical@sep@len} % Last negative vertical spacing
{#4} % Vertical offset
}
% ---------- %
% -- DATE -- %
% ---------- %
%%%
% prototype::
% #1 : (color)
% the color of the margin note
% #2 : (date)
% a date ''YYYY-MM-DD''
% #3 : (vertical offset)
% algebraic distance to move vertically the material
%
% :action: this macro is similar to ''\tdocversion'' except that it just
% prints a date.
%%%
\NewDocumentCommand{\tdocdate}{
O{\tutodoc@changes@when@color}
m
D<>{\tutodoc@version@date@vertical@offset@len}
}{
\tutodoc@new@change@margin%
{#1} % Color
{} % Version
{#2} % Date
{\tutodoc@version@date@vertical@sep@len} % Last negative spacing
{#3} % Vertical offset
}
% ===================== %
% == CHANGES - WHAT? == %
% ===================== %
\ExplSyntaxOn
\msg_set:nnnn { tutodoc ~ (version-n-change) }
{ version-n-change : topic-missing-title }
{ Missing ~ title. }
{ One ~ single ~ title ~ must ~ be ~ indicated. }
% ------------------- %
% -- GENERIC TOPIC -- %
% ------------------- %
\tl_new:N \l_tutodoc_topic_what_color_tl
\tl_new:N \l_tutodoc_topic_when_color_tl
\tl_new:N \l_tutodoc_topic_date_tl
\tl_new:N \l_tutodoc_topic_version_tl
%%%
% prototype::
% col : the color of the full content of a topic \env
% col-chges : the color of the material for changes for a topic \env
% date : the date of the changes a topic \env
% version : the number version of the changes a topic \env
%%%
\keys_define:nn { tutodoc / version-n-change / topic / options } {
% Colors.
col .tl_set:N = \l_tutodoc_topic_what_color_tl,
col .initial:n = tutodoc@text@color,
col-chges .tl_set:N = \l_tutodoc_topic_when_color_tl,
col-chges .initial:n = \tutodoc@changes@when@color,
% Date.
date .tl_set:N = \l_tutodoc_topic_date_tl,
date .initial:n = \c_empty_tl,
% Version.
version .tl_set:N = \l_tutodoc_topic_version_tl,
version .initial:n = \c_empty_tl,
}
\tl_new:N \l__tutodoc_topic_all_user_options_tl
%%%
% For themes using icons, we need a specific paragraph with less vertical
% space consuming.
%%%
\ifcsundef{g__tutodoc_topic_change_seq}{
\newcommand{\tutodoc@what@change@paragraph}{%
\@startsection{paragraph} %
{4} % Level 4 (after section and co)
{\z@} % No indentation before the title
{1.25ex \@plus 1ex \@minus .2ex} % Vertical space before:
% 2ex with flexibility (+1ex / -0.2ex)
{-1em} % Negative spacing after
% ==> Title slightly aligned to the left.
{\normalfont\normalsize % Title style
\bfseries\sffamily} %
}
}{}
%%%
% prototype::
% #1 : (title)
% a title that will be followed by a colon.
% #2 : (aws-icon)
% one material that expects to be an icon command from the
% ''fontawsome5'' \pack
% #3 : (key-val options)
% :see: l3keys(tutodoc / version-n-change / topic / options)
%
% :action: this environment prints some \infos about specific changes
% achieved in a new version (no special formatting is applied).
% Key-val options allow to add a date \andor a \nbver with
% a specific color if needed.
%%%
\NewDocumentEnvironment{tdoctopic}{ m D<>{} O{} }{
\IfBlankT{#1}{
\msg_fatal:nn { tutodoc ~ (version-n-change) }
{ version-n-change : topic-missing-title }
}
\keys_set:nn { tutodoc / version-n-change / topic / options } { #3 }
\tl_clear:N \l__tutodoc_topic_all_user_options_tl
\tl_set_eq:NN \l__tutodoc_topic_all_user_options_tl \l_tutodoc_topic_version_tl
\tl_put_right:Nn \l__tutodoc_topic_all_user_options_tl { \l_tutodoc_topic_date_tl }
\group_begin:
\color{\tl_use:N \l_tutodoc_topic_what_color_tl}
\ifcsundef{g__tutodoc_topic_change_seq}{{}
% Icon used by the theme.
\tutodoc@what@change@paragraph{
\color{\tl_use:N \l_tutodoc_topic_what_color_tl}
\IfBlankF{#2}{\tdocicon{#2}}
\textsc{#1.}
}
}{
% No icon used by the theme.
\smallskip
{
\normalfont\normalsize\bfseries\sffamily
\textsc{#1.}
}
}
% A date and/or a version.
\exp_args:Ne \IfBlankF{\l__tutodoc_topic_all_user_options_tl}{
\exp_args:NNee \tutodoc@new@change@margin
{\l_tutodoc_topic_when_color_tl}
{\l_tutodoc_topic_version_tl}
{\l_tutodoc_topic_date_tl}
{\tutodoc@version@date@vertical@sep@len}
{\tutodoc@version@date@vertical@offset@len}
}
\begin{itemize}
}{
\end{itemize}
\group_end:
}
% ---------------------- %
% -- CLASSICAL TOPICS -- %
% ---------------------- %
%%%
% prototype::
% :see: env.tdoctopic
%
% :action: ''key/value'' iteration over ''\g__tutodoc_topic_change_prop''
% to build topic-like \envs using the \env ''tdoctopic''
% (the title respects the locale settings).
%%%
\ifcsundef{g__tutodoc_topic_change_seq}{
\prop_map_inline:Nn \g__tutodoc_topic_change_prop {
\NewDocumentEnvironment{ tdoc#1 } { O{} } {
\begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } < #2 > [##1]
}{
\end{tdoctopic}
}
}
}{
\seq_map_inline:Nn \g__tutodoc_topic_change_seq {
\NewDocumentEnvironment{ tdoc#1 } { O{} } {
\begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } [##1]
}{
\end{tdoctopic}
}
}
}
%%%
% prototype::
% #1 : (color-content)
% the color of the full content
% #2 : (short-desc)
% a short text expected to indicate the very first version of a project.
%
% :action: the short text printed will be preceded by a pretty anchor icon.
%%%
\NewDocumentCommand{ \tdocstartproj }{
O{tutodoc@text@color}
m
} {
\group_begin:
\color{#1}
\ifcsundef{g__tutodoc_topic_change_seq}{
% Icon used.
\tdocicon{\tutodoc@changes@start@project@icon}
}{
% No icon used.
\raisebox{4pt}{\normalfont\tiny\bfseries\sffamily[Init]}\kern2pt
}
#2
\group_end:
}
\ExplSyntaxOff
% ================ %
% == DECORATION == %
% ================ %
% refs::
% + https://tex.stackexchange.com/a/130529/6880
% (for the leaders trick)
% + https://tex.stackexchange.com/a/269887/6880
% (for the \hrule width)
% + https://tex.stackexchange.com/a/729710/6880
% (centering the \hrule)
\newlength{\tutodoc@vertical@space@deco@len}
\setlength{\tutodoc@vertical@space@deco@len}{\dimeval{2\medskipamount+1.25pt}}
%%%
% 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, and extra vertical spaces are added above and
% below the rule.
%
% :see: len.tutodoc@vertical@space@deco@len
%%%
\newcommand{\tdocsep}{
\par
\cleaders
\vbox to \tutodoc@vertical@space@deco@len{
\vfill\centerline{\vrule width 0.5\hsize height 0.75pt}\vfill
}\vskip\tutodoc@vertical@space@deco@len
}