diff options
Diffstat (limited to 'macros/latex/contrib/tutodoc/code/tutodoc.sty')
-rw-r--r-- | macros/latex/contrib/tutodoc/code/tutodoc.sty | 1026 |
1 files changed, 1026 insertions, 0 deletions
diff --git a/macros/latex/contrib/tutodoc/code/tutodoc.sty b/macros/latex/contrib/tutodoc/code/tutodoc.sty new file mode 100644 index 0000000000..83b6c88433 --- /dev/null +++ b/macros/latex/contrib/tutodoc/code/tutodoc.sty @@ -0,0 +1,1026 @@ +% ------------------------------------------------------- % +% - This is file `tutodoc.sty' generated automatically. - % +% - - % +% - Copyright (C) 2023 by Christophe BAL - % +% - - % +% - This file may be distributed and/or modified under - % +% - the conditions of the GNU 3 License. - % +% ------------------------------------------------------- % + +\ProvidesExplPackage + {tutodoc} + {2023-11-29} % Creation: 2023-11-29 + {1.0.0} + {This package proposes tools for writing "human friendly" documentations of LaTeX packages.} + +\RequirePackage[ + top = 2.5cm, + bottom = 2.5cm, + left = 2.5cm, + right = 2.5cm, + marginparwidth = 2cm, + marginparsep = 2mm, + heightrounded +]{geometry}[2020-01-02] + +\RequirePackage[raggedright]{titlesec}[2021/07/05] +\RequirePackage{tocbasic} + +\RequirePackage{xcolor}[2022/06/12] +\RequirePackage{hyperref}[2023-02-07] + + +% We delegate the management of quoting to the `csquotes' package, +% which takes care of the linguistic parameters. +\RequirePackage{csquotes}[2022-09-14] + + +\RequirePackage{amsthm}[2017/09] + + +\RequirePackage{clrstrip}[2021-08-28] + + +\RequirePackage{tcolorbox}[2023/06/19] +\tcbuselibrary{minted, breakable, skins} + + +\RequirePackage{marginnote}[2023-09-07] + + +% -- LOCALE LANG -- % + +\ExplSyntaxOn + +% :: SOME MESSAGES :: % + +\msg_set:nnnn { tdoc } { package-option-lang-unknown } + { Unknown ~ language. } + { See ~ the ~ documentation ~ for ~ the ~ supported ~ languages. } + + +% :: SETTING SOME KEYS :: % + +\str_new:N \l_tdoc_opt_lang_str + +%%% +% We define the key-val options that will be exposed by the package. +%%% +\keys_define:nn { tdoc } { + lang .choices:nn = + { french, english } + { + \tl_set:Nn \l_tdoc_opt_lang_str + { \tl_use:N \l_keys_choice_tl } + }, + lang .initial:n = english, + lang / unknown .code:n = + \msg_error:nnxxx { tdoc } { package-option-lang-unknown } + { lang } % Name of choice key + { french, english } % Valid choices + { \exp_not:n {#1} } % Invalid choice given +} + +\ProcessKeyOptions[tdoc] + +\ExplSyntaxOff + + +% -- LOCALE SETTINGS -- % + +\NewDocumentCommand{\tdoc@colon}{}{:} + +% We must take care of the colons, babel and spacing. +\@ifpackageloaded{babel}{ + \iflanguage{french}{ + \RenewDocumentCommand{\tdoc@colon}{}{\babelshorthand{:}} + }{} +}{} + +\ExplSyntaxOn + +\input{tdoc-locale-\l_tdoc_opt_lang_str.cfg.sty} + +\ExplSyntaxOff + + +% -- GENERAL SETTINGS -- % + +\setlength{\parindent}{0cm} + + +% -- LINKS -- % + +\hypersetup{ + colorlinks, + citecolor = orange!75!black, + filecolor = orange!75!black, + linkcolor = orange!75!black, + urlcolor = orange!75!black +} + + +% -- TOC & Co. -- % + +\ifcsundef{chapter}% + {}% + {\renewcommand\thechapter{\Alph{chapter}.}} + +\renewcommand\thesection{\Roman{section}.} +\renewcommand\thesubsection{\arabic{subsection}.} +\renewcommand\thesubsubsection{\roman{subsubsection}.} + +\titleformat{\paragraph}[hang]% + {\normalfont\normalsize\bfseries}% + {\theparagraph}{1em}% + {} + +\titlespacing*{\paragraph}% + {0pt}% + {3.25ex plus 1ex minus .2ex}% + {0.5em} + +% Source +% * https://tex.stackexchange.com/a/558025/6880 +\DeclareTOCStyleEntries[ + raggedentrytext, + linefill = \hfill, + indent = 0pt, + dynindent, + numwidth = 0pt, + numsep = 1ex, + dynnumwidth +]{tocline}{ + chapter, + section, + subsection, + subsubsection, + paragraph, + subparagraph +} + +\DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section} + + +% -- QUOTING -- % + +%%% +% prototype:: +% #1 : a text to quote. +% +% For example, ''\tdocquote{Something}'' prints something like **"Something"**. +%%% +\NewDocumentCommand{\tdocquote}{m}{% + \enquote{\emph{#1}}% +} + + +% -- EXPLAINING ENGLISH NAMES -- % + +%%% +% prototype:: +% #1 : an english text to explain in another language. +% +% :extra: this macro has a star version. +% +% For example, if the language chosen is ''french'', we have +% the following outputs. +% +% 1) ''\tdocinEN{Something}'' prints +% **"Something" en anglais**. +% +% 2) ''\tdocinEN*{Something}'' just prints +% **"Something"**. +% This can be useful in a case like +% ''\tdocinEN*{Something} et \tdocinEN{Another thing}'' +% which gives +% **"Something" et "Another thing" en anglais**. +%%% +\NewDocumentCommand{\tdocinEN}{s m}{% + \tdocquote{#2}% + \IfBooleanF{#1}{% No star used. + \ \tdoc@trans@in@EN{}% + }% +} + + +% -- FOCUS ON SOME CONTENT -- % + +% :: EXAMPLE - HIDDEN VERSIONS :: % + +%%% +% See the \doc of the macro ''\newtheorem'' from the package ''amsthm'' +% to have \infos about the environment ''@@tdocexa@nb''. +%%% +\newtheorem{@@tdocexa@nb}{\tdoc@trans@exa@title}% + [subsubsection] + +%%% +% We redefine the counter associated to the environment ''@@tdocexa@nb'' +% to obtain only one single arabic number. +%%% +\renewcommand{\the@@tdocexa@nb}{\arabic{@@tdocexa@nb}} + + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''@@tdocexa@no@nb''. +%%% +\newtheorem*{@@tdocexa@no@nb}{\tdoc@trans@exa@title} + + +% :: EXAMPLE - PUBLIC VERSION :: % + +\ExplSyntaxOn + +\msg_set:nnnn { tdoc } { env-tdocexa-unknown-option } + { Unknown ~ rafters ~ option. } + { See ~ the ~ documentation ~ for ~ the ~ supported ~ options. } + +\NewDocumentEnvironment{tdocexa}{D<>{nb} O{}}{ + \str_case:nnF { #1 } { + { nb } { + \begin{@@tdocexa@nb}[#2] + } + { nonb } { + \begin{@@tdocexa@no@nb}[#2] + } + }{ + \msg_error:nn { tdoc } { env-tdocexa-unknown-option } + } +}{ + \str_case:nnF { #1 } { + { nb } { + \end{@@tdocexa@nb} + } + { nonb } { + \end{@@tdocexa@no@nb} + } + }{} +} + +\ExplSyntaxOff + + +% :: REMARK :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdocrem''. +%%% +\newtheorem*{tdocrem}{\tdoc@trans@rmk@title} + + +% :: IMPORTANT :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdocimportant''. +%%% +\newtheorem*{tdocimportant}{\tdoc@trans@important@title} + + +% :: NOTE :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdocnote''. +%%% +\newtheorem*{tdocnote}{\tdoc@trans@note@title} + + +% :: TIP :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdoctip''. +%%% +\newtheorem*{tdoctip}{\tdoc@trans@tip@title} + + +% :: CUATION :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdoccaution''. +%%% +\newtheorem*{tdoccaution}{\tdoc@trans@caution@title} + + +% :: WARNING :: % + +%%% +% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' +% to have \infos about the environment ''tdocwarn''. +%%% +\newtheorem*{tdocwarn}{\tdoc@trans@warn@title} + + +% -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- % + +%%% +% prototype:: +% #1 : the name of a class +% +% :action: ''\tdoccls{myclass}'' prints verb::''myclass''. +%%% +\NewDocumentCommand{\tdoccls}{m}{% + \texttt{#1}% +} + + +%%% +% prototype:: +% #1 : the name of a package +% +% :action:''\tdocpack{mypack}'' prints verb::''mypack''. +%%% +\NewDocumentCommand{\tdocpack}{m}{% + \texttt{#1}% +} + + +%%% +% prototype:: +% #1 : the name of a macro +% +% :action: ''\tdocenv{mymacro}'' prints verb::''\mymacro''. +%%% +\NewDocumentCommand{\tdocmacro}{m}{% + \texttt{\textbackslash{}#1}% +} + + +%%% +% prototype:: +% #1 : hard typed options with the good delimiters +% #2 : the name of an environment +% +% :action: ''\tdocenv{myenv}'' prints verb::''\begin{myenv} ... \end{myenv}'' +% or something like verb::''\begin{myenv}<opt1> ... \end{myenv}'', +% the spaces being secable. +%%% +\NewDocumentCommand{\tdocenv}{O{}m}{% + \texttt{\textbackslash{}begin\{#2\}#1 % + \!...\! % + \textbackslash{}end\{#2\}}% +} + + +% -- EXPLAINING PREFIXES -- % + +\ExplSyntaxOn + +% :: MESSAGES :: % + +\msg_set:nnnn { bdoc } { prefixwhy-bad-format } +{ Bad ~ format, ~ something ~ like ~ ''pre.fix'' ~ expected. } +{ You ~ must ~ use ~ one ~ single ~ point. } + + +% :: PREFIX FROM... :: % + +%%% +% prototype:: +% #1 : a prefix and a suffix separated by one colon. +% +% :action: ''\tdocprewhy{pre.fix}'' prints verb::''pre''.fix. +%%% +\NewDocumentCommand{\tdocprewhy}{m}{% +% Do we have 2 parts? + \seq_set_split:Nnn \l_tmpa_seq { . } { #1 } + + \int_set:Nn \l_tmpa_int + {\int_eval:n {\seq_count:N \l_tmpa_seq}} + + \if_int_compare:w \l_tmpa_int = 2 + \else: + \msg_error:nn { bdoc } { prefixwhy-bad-format } + \fi: + +% Let's go. + \seq_pop:NN \l_tmpa_seq \l_tmpa_tl + \seq_pop:NN \l_tmpa_seq \l_tmpb_tl + + \textbf{\tdocpre{\tl_use:N \l_tmpa_tl}\kern.5pt\textperiodcentered\kern.5pt{\tl_use:N \l_tmpb_tl}} +} + +\ExplSyntaxOff + + +% :: JUST ONE PREFIX :: % + +%%% +% prototype:: +% #1 : just a prefix +% +% :action: ''\tdocpre{pre}'' only prints verb::''pre''. +% This can be useful in a case like +% ''\tdocpre{pre} comes from \tdocprewhy{pre}{fix}'' +% which prints: +% verb::''pre'' comes from verb::''pre''-fix. +%%% +\NewDocumentCommand{\tdocpre}{m}{% + \texttt{#1}% +} + + +% -- GENERAL FORMATTING -- % + +% :: TEXT INSIDE A RULE :: % + +\ExplSyntaxOn + +%%% +% prototype:: +% #1 : a text +% #2 : a color +% +% :action: this macro adds two horizontal lines on either side of the text. +% The final output is centered. +% +% note:: +% The code used comes from +% cf::''this post ; +% https://tex.stackexchange.com/a/604708/6880''. +%%% +\NewDocumentCommand{\tdocruler}{m m}{ + \par + { + \centering + \scriptsize + \itshape + \bfseries + \color{#2} + + \hbox_set:Nn \l_tmpa_box { \,\, #1 \,\, } + \dim_set:Nn \l_tmpa_dim { + .35 \linewidth - .5 \box_wd:N \l_tmpa_box + } + + \rule[.75pt] { \dim_use:N \l_tmpa_dim } + { 2.5pt } + \box_use:N \l_tmpa_box + \rule[.75pt] { \dim_use:N \l_tmpa_dim } + { 2.5pt } + \par + } +} + +\ExplSyntaxOff + + +% :: COLOR TRANSFORMATIONS :: % + +%%% +% prototype:: +% #1 : one color following the ''xcolor'' format. +% +% :return: a "darker" version of the color ''#1''. +%%% +\NewExpandableDocumentCommand{\tdocdarkcolor}{m}{% + #1!50!black% +} + + +%%% +% prototype:: +% #1 : one color following the ''xcolor'' format. +% +% :return: a "transparent" version of the color `#1`. +%%% +\NewExpandableDocumentCommand{\tdoclightcolor}{m}{% + #1!5% +} + + +% :: INTERNAL ENVIRONMENTS :: % + +%%% +% prototype:: +% #1 : the text before the real output +% #2 : the text after the real output +% #3 : one color following the ''xcolor'' format. +% This color is used to set the one for the decorated texts printed +% corresponding to the two first arguments. +% +% :action: this environment just adds its content processed by \latex +% between centered materials produced by the macro ''\tdocruler'' +% such as to stress the start and the end of the content. +%%% +\NewDocumentEnvironment{tdoc@showcase@basic}{m m m}{ + \tdocruler{#1}{\tdocdarkcolor{#3}} + \medskip +}{ + \medskip + \tdocruler{#2}{\tdocdarkcolor{#3}} +} + + +%%% +% prototype:: +% #1 : the text before the real output +% #2 : the text after the real output +% #3 : the color following the ''xcolor'' format. +% This color is used to set the ones of the stripe and the decorated +% texts printed (see the two first arguments). +% +% :action: this environment adds a page-width colored stripe in the +% background of the environment content processed by \latex. +% This stripe is preceded and followed by centered materials +% produced by the macro ''\tdocruler'' such as to stress the +% start and the end of the content. +%%% + +\NewDocumentEnvironment{tdoc@showcase@colorstrip}{m m m}{ + \begin{colorstrip}{\tdoclightcolor{#3}} + \begin{tdoc@showcase@basic}{#1}{#2}{#3} +}{ + \end{tdoc@showcase@basic} + \end{colorstrip} +} + + +\ExplSyntaxOn + +% :: SETTING SOME KEYS :: % + +\tl_new:N \l_tdoc_showcase_before_tl +\tl_new:N \l_tdoc_showcase_after_tl +\tl_new:N \l_tdoc_showcase_color_tl +\bool_new:N \l_tdoc_showcase_nostripe_bool + + +%%% +% prototype:: +% :see: env.tdocshowcase +% +% We define the key-val options that will be exposed by the \env +% ''tdocshowcase''. +%%% +\keys_define:nn { tdoc/showcase } { +% Texts. + before .tl_set:N = \l_tdoc_showcase_before_tl, + before .initial:n = \tdoc@trans@latex@show@start, + after .tl_set:N = \l_tdoc_showcase_after_tl, + after .initial:n = \tdoc@trans@latex@show@end, +% Decorations. + color .tl_set:N = \l_tdoc_showcase_color_tl, + color .initial:n = cyan, + nostripe .bool_set:N = \l_tdoc_showcase_nostripe_bool, + nostripe .initial:n = false, +} + + +% :: SHOWCASE FROM TYPED CODE :: % + +% prototype:: +% #1 : the key-value options. +% +% :action: this \env formats \latex code, given as an argument, +% by framing it with texts decorated by ''\tdocruler'', +% in order to clearly identify a rendering used as an +% example. +% It is also possible to have a coloured strip of the width +% of the page in the background of the content. +% +% :see: env.tdoc@showcase@basic , +% env.tdoc@showcase@colorstrip +%%% +\NewDocumentEnvironment{tdocshowcase}{O{}}{ + \group_begin: + \keys_set:nn { tdoc/showcase } { #1 } + + \bool_if:NTF \l_tdoc_showcase_nostripe_bool { + \begin{tdoc@showcase@basic}% + { \tl_use:N \l_tdoc_showcase_before_tl }% + { \tl_use:N \l_tdoc_showcase_after_tl }% + { \tl_use:N \l_tdoc_showcase_color_tl } + }{ + \begin{tdoc@showcase@colorstrip}% + { \tl_use:N \l_tdoc_showcase_before_tl }% + { \tl_use:N \l_tdoc_showcase_after_tl }% + { \tl_use:N \l_tdoc_showcase_color_tl } + } +}{ + \bool_if:NTF \l_tdoc_showcase_nostripe_bool { + \end{tdoc@showcase@basic} + }{ + \end{tdoc@showcase@colorstrip} + } + \group_end: +} + + +% :: SHOWCASE FROM FILE :: % + +%%% +% prototype:: +% #1 : the key-value options supported by the ''tdocshowcase'' \env. +% #2 : the path of a file +% +% :see: env.tdocshowcase +%%% +\NewDocumentCommand{\tdocshowcaseinput}{O{} m}{ + \group_begin: + \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl + + \exp_last_unbraced:NNV \tdocshowcase [\l_tmpa_tl] + \input{#2} + \endtdocshowcase + \group_end: +} + +\ExplSyntaxOff + + +% -- LATEX EXAMPLES -- % + +% :: INLINE SHORT LATEX CODE :: % + +%%% +% See the \doc of the macro ''\newmintinline'' from the package ''minted'' +% to have \infos about the macro ''tdocinlatex''. +%%% +\newmintinline[tdocinlatex]{latex}{} + + +% :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: % + +\ExplSyntaxOn + +%%% +% In the following easy-to-understand macro, we use one fictive ''tcolorbox'' +% style such as to indicate an unknown ''tdoc'' style to the user. +% For example, this can give one message similar to the following one. +% +% term:: +% Package pgfkeys Error: I do not know the key '/tcb/tdoclatex bad option +% "NOT-A-STYLE"' and I am going to ignore it. Perhaps you misspelled it. +% +% See the pgfkeys package documentation for explanation. +%%% +\NewExpandableDocumentCommand{\tdoc@latex@listing@formating}{ m }{ + \str_case:nnF { #1 } { + { sbs } { listing ~ side ~ text } + { code } { listing ~ only } + { std } { listing ~ and ~ text } + } { tdoclatex ~ bad ~ option ~ "#1" } +} + +\ExplSyntaxOff + + +% :: THE TCOLORBOX LISTING STYLE :: % + +%%% +% note:: +% The settings used come from the following sources. +% * https://tex.stackexchange.com/a/604821/6880 +% * https://tex.stackexchange.com/a/327983/6880 +%%% +\tcbset{ + tdoclatex_tcbstyle/.style = { + minted language = latex, + breakable, +% Code and output + colback = yellow!5, +% Frame + colframe = darkgray, + shadow = {.75mm}{-.75mm}{0mm}{black!30}, + arc = .75mm, + left = 1mm, right = 1mm, + bottom = 1mm, top = 1mm, +% We can use ''sharp corners'' to obtain an "old school" style. +% +% Separating line + enhanced, + segmentation style = { + gray, + dash pattern = {on 5pt off 2.5pt}, + line width = 1.25pt + }, + #1 + }, +} + + +% :: TCOLORBOX LISTING ENVIRONMENT :: % + +%%% +% prototype:: +% #1 : the style to be used (code only, code and output side by side, +% or the standard style corresponding to the code followed by +% its output) +% @ #1 in [code, sbs, std] +% +% note:: +% See the \doc of the macro ''\newtcblisting'' from the package +% ''tcolorbox'' to have \infos about the environment ''tdoclatex''. +%%% +\newtcblisting{tdoclatex}[1][std]{% + tdoclatex_tcbstyle = \tdoc@latex@listing@formating{#1} +} + + +% :: TCOLORBOX IMPORTED LISTING MACRO :: % + +%%% +% prototype:: +% #1 : :see: \newtcblisting{tdoclatex}. +% #2 : the path of the file to input and format. +% +% note:: +% See the \doc of the macro ''\newtcbinputlisting'' from the package +% ''tcolorbox'' to have more \infos about the macro ''\tdoclatexinput''. +%%% +\newtcbinputlisting{\tdoclatexinput}[2][std]{ + listing file = {#2}, + tdoclatex_tcbstyle = \tdoc@latex@listing@formating{#1} +} + + +% -- LATEX REAL USE CASES -- % + +\ExplSyntaxOn + +% :: SETTING SOME KEYS :: % + +\tl_new:N \l_tdoc_listing_explain_tl + +%%% +% prototype:: +% :see: macro.tdoclatexshow +% +% We define the key-val options that will be exposed by ''\tdoclatexshow''. +%%% +\keys_define:nn { tdoc/latexshow } { + explain .tl_set:N = \l_tdoc_listing_explain_tl, + explain .initial:n = { \tdoc@trans@this@gives \tdoc@colon }, +} + + +% :: LATEXSHOW MACRO :: % + +%%% +% prototype:: +% #1 : the key-value options supported by the ''tdocshowcase'' \env, +% plus one allowing you to change the description of a line +% printed between the code and its focused output. +% #2 : the path of a file +% +% :see: env.tdocshowcase , +% macro.tdoclatexinput +%%% +\NewDocumentCommand{\tdoclatexshow}{O{} m}{ + \group_begin: + \keys_set_known:nnN { tdoc/latexshow } { #1 } \l_tmpa_tl + + \tdoclatexinput[code]{#2} + + \tl_use:N \l_tdoc_listing_explain_tl + +% Source: https://tex.stackexchange.com/a/696700/6880 + \exp_last_unbraced:NNV \tdocshowcaseinput [\l_tmpa_tl] {#2} + \group_end: +} + +\ExplSyntaxOff + + +% -- CHANGES - WHEN? --% + +\ExplSyntaxOn + +% :: MESSAGES :: % + +\msg_set:nnnn { tdoc } { date-bad-format } + { Bad ~ format ~ for ~ a ~ date. } + { Use ~ YYYY-MM-DD. } + + +% :: MARGIN NOTE :: % + +\reversemarginpar{} + +%%% +% prototype:: +% #1 : the color of the margin note +% #2 : the first material (a date or nothing) +% #3 : the second material (a version number or nothing) +% #4 : the last negative vertical spacing for the 2nd rule +% +% :action: this macro factorizes the printing of the changes +% in the left margin. +% +% :see: \__tdoc_translate_date:n +%%% +\NewDocumentCommand{\tdoc@new@change@margin}{m m m m}{ + \marginnote{ + \color{#1} + \scriptsize + \centering + + \vspace{0pt} + \rule{1.65cm}{.95pt} + \vspace{-2.9pt} + + \IfBlankTF{#2}{}{ + \par + \__tdoc_translate_date:n { #2 } + \par + } + + \vspace{1pt} + + \par + #3 + \par + + \vspace{#4} + \rule{1.65cm}{.95pt} + }[-.345cm] +} + + +%%% +% prototype:: +% :action: this function checks if we have something like +% ''YYYY-MM-DD'' and then it calls the function +% ''\__tdoc_translate_date_process:w'' to finish +% the job. +% +% :see: \__tdoc_translate_date_process:w +%%% +\cs_new:Nn \__tdoc_translate_date:n { + \regex_match:nnTF { \A \d{1,4} \- \d{2} \- \d{2} \Z } { #1 }{ + \__tdoc_translate_date_process:w #1 \q_stop + }{ + \msg_error:nn { tdoc } { date-bad-format } + } +} + + +%%% +% prototype:: +% :action: this function extracts year, month and day in something +% like ''YYYY-MM-DD'' and then it calls ''\tdoc@trans@date'' +% to use the format expected for a "localised" date. +%%% +\cs_new:Npn \__tdoc_translate_date_process:w #1 - #2 - #3 \q_stop { + \tdoc@trans@date{#1} + {#2} + {#3} +} + + +% :: VERSION AND DATE :: % + +%%% +% prototype:: +% #1 : the color of the margin note +% #2 : a version number +% #3 : a date ''YYYY-MM-DD'' +% +% :action: this macro prints a margin note showing a version number +% below a date, and the optional argument is used to colorize +% all this text. +% +% warning:: +% The date must use an english formatting like ''2021-07-14''. This allows +% to parse the date such as to display it following the standard convention +% of the language chosen when loading the package. +%%% +\NewDocumentCommand{\tdocversion}{O{blue} m O{}}{ + \tdoc@new@change@margin{#1} % Color + {#3} % Date + {#2} % Version + {-4.25pt} % Last negative vertical spacing +} + + +% :: DATE :: % + +%%% +% prototype:: +% #1 : the color of the margin note +% #2 : a date ''YYYY-MM-DD'' +% +% :action: this macro is similar to ''\tdocversion'' except that it just +% prints a date. +%%% +\NewDocumentCommand{\tdocdate}{O{blue} m}{ + \tdoc@new@change@margin{#1} % Color + {#2} % Date + {} % Version + {-5.35pt} % Last negative spacing +} + + +% -- CHANGES - WHAT? + +% :: MESSAGES :: % + +\msg_set:nnnn { tdoc } { changes-topic-missing-title } + { Missing ~ title. } + { One ~ single ~ title ~ must ~ be ~ indicated. } + + +% :: CHANGES - TOPIC :: % + +%%% +% prototype:: +% #1 : a title that will be followed by a colon. +% +% :action: this environment prints some ¨infos about specific changes +% achieved in a new version (no special formatting is applied). +%%% +\NewDocumentEnvironment{tdoctopic}{ m }{ + \IfBlankT{#1}{ + \msg_fatal:nn { tdoc } { changes-topic-missing-title } + } + + \textbf{ + \textsc{#1.} + } + + \begin{itemize} +}{ + \end{itemize} +} + + +% :: CHANGES - NEW THINGS :: % + +%%% +% prototype:: +% :see: env.tdoctopic +% +% :action: similar to the \env ''tdoctopic'' with the title "New" +% translated into the good language. +%%% +\NewDocumentEnvironment{tdocnew}{}{ + \begin{tdoctopic}{\tdoc@trans@chges@new} +}{ + \end{tdoctopic} +} + + +% :: CHANGES - UPDATE :: % + +%%% +% prototype:: +% :see: env.tdoctopic +% +% :action: similar to the \env ''tdoctopic'' with the title "Update" +% translated into the good language. +%%% +\NewDocumentEnvironment{tdocupdate}{}{ + \begin{tdoctopic}{\tdoc@trans@chges@update} +}{ + \end{tdoctopic} +} + + +% :: CHANGES - FIX :: % + +%%% +% prototype:: +% :see: env.tdoctopic +% +% :action: similar to the \env ''tdoctopic'' with the title "Fix" +% translated into the good language. +%%% +\NewDocumentEnvironment{tdocfix}{}{ + \begin{tdoctopic}{\tdoc@trans@chges@fix} +}{ + \end{tdoctopic} +} + +\ExplSyntaxOff + + +% -- DECORATIONS -- % + +%%% +% prototype:: +% :action: this macro draws a centered horizontal rule with a height +% of qty::''0.75 pt'', and a width equal to half of the current +% text width. +% Extra vertical spaces are added above and below the rule. +%%% +\NewDocumentCommand{\tdocsep}{}{ + \medskip + \hfill\rule{0.5\textwidth}{0.75pt}\hfill + \medskip + \smallskip +} + + +%%% +% prototype:: +% :action: this macro adds a tiny vertical spacing. +%%% +\NewDocumentCommand{\tdocxspace}{}{ + \vspace{0.25em} +} |