diff options
author | Karl Berry <karl@freefriends.org> | 2024-09-25 19:28:01 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2024-09-25 19:28:01 +0000 |
commit | b1b42380a3ed8256d0f52ccd26447d2cf53bc297 (patch) | |
tree | b79b92514c4018e5125adc36e6892af7fe3ee065 /Master/texmf-dist/tex | |
parent | c5bd64cc7d23f1cc5fb941489c9940551cb127e3 (diff) |
tutodoc (25sep24)
git-svn-id: svn://tug.org/texlive/trunk@72384 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/tex')
3 files changed, 244 insertions, 154 deletions
diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty index 339f10240c6..a9bb8d7bdfb 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-english.cfg.sty @@ -4,13 +4,13 @@ \NewDocumentCommand{\tutodoc@trans@latex@show@start}{}{Start ~ of ~ the ~ real ~ output} \NewDocumentCommand{\tutodoc@trans@latex@show@end}{}{End ~ of ~ the ~ real ~ output} \NewDocumentCommand{\tutodoc@trans@exa@title}{}{Example} -\NewDocumentCommand{\tutodoc@trans@rmk@title}{}{Remark} +\NewDocumentCommand{\tutodoc@trans@rem@title}{}{Remark} \NewDocumentCommand{\tutodoc@trans@note@title}{}{Note} \NewDocumentCommand{\tutodoc@trans@tip@title}{}{Tip} -\NewDocumentCommand{\tutodoc@trans@important@title}{}{Important} +\NewDocumentCommand{\tutodoc@trans@imp@title}{}{Important} \NewDocumentCommand{\tutodoc@trans@caution@title}{}{Caution} \NewDocumentCommand{\tutodoc@trans@warn@title}{}{Warning} -\NewDocumentCommand{\tutodoc@trans@chges@pb}{}{Problem} +\NewDocumentCommand{\tutodoc@trans@chges@prob}{}{Problem} \NewDocumentCommand{\tutodoc@trans@chges@break}{}{Break} \NewDocumentCommand{\tutodoc@trans@chges@fix}{}{Fix} \NewDocumentCommand{\tutodoc@trans@chges@new}{}{New} diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty index 5c97cb2f180..91bdbab5f46 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc-locale-main-french.cfg.sty @@ -4,13 +4,13 @@ \NewDocumentCommand{\tutodoc@trans@latex@show@start}{}{Début ~ du ~ rendu ~ réel} \NewDocumentCommand{\tutodoc@trans@latex@show@end}{}{Fin ~ du ~ rendu ~ réel} \NewDocumentCommand{\tutodoc@trans@exa@title}{}{Exemple} -\NewDocumentCommand{\tutodoc@trans@rmk@title}{}{Remarque} +\NewDocumentCommand{\tutodoc@trans@rem@title}{}{Remarque} \NewDocumentCommand{\tutodoc@trans@note@title}{}{Note} \NewDocumentCommand{\tutodoc@trans@tip@title}{}{Astuce} -\NewDocumentCommand{\tutodoc@trans@important@title}{}{Important} +\NewDocumentCommand{\tutodoc@trans@imp@title}{}{Important} \NewDocumentCommand{\tutodoc@trans@caution@title}{}{Mise ~ en ~ garde} \NewDocumentCommand{\tutodoc@trans@warn@title}{}{Avertissement} -\NewDocumentCommand{\tutodoc@trans@chges@pb}{}{Problème} +\NewDocumentCommand{\tutodoc@trans@chges@prob}{}{Problème} \NewDocumentCommand{\tutodoc@trans@chges@break}{}{Bifurcation} \NewDocumentCommand{\tutodoc@trans@chges@fix}{}{Réparation} \NewDocumentCommand{\tutodoc@trans@chges@new}{}{Nouveau} diff --git a/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty b/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty index a1e0acdd130..b32d98df354 100644 --- a/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty +++ b/Master/texmf-dist/tex/latex/tutodoc/tutodoc.sty @@ -1,17 +1,22 @@ -% ------------------------------------------------------- % -% - This is file `tutodoc.sty' 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. - % -% ------------------------------------------------------- % +% ********************************************************* % +% ** This is file `tutodoc.sty' 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. ** % +% ********************************************************* % \ProvidesExplPackage - {tutodoc} - {2024-08-23} % Creation: 2023-11-29 - {1.2.0-a} - {This package proposes tools for writing "human friendly" documentations of LaTeX packages.} + {tutodoc} + {2024-09-25} % Creation: 2023-11-29 + {1.3.0} + {This package proposes tools for writing "human friendly" documentations of LaTeX packages.} + + +% =================== % +% == PACKAGES USED == % +% =================== % \RequirePackage[ top = 2.5cm, @@ -43,34 +48,63 @@ [2022-09-14] -\RequirePackage{amsthm}% - [2017/09] +\RequirePackage{fontawesome5}% + [2022-05-02] + +\RequirePackage{keytheorems}% + [2024/09/19] + +\RequirePackage[svgnames]% + {xcolor}% + [2023/11/15] + +\RequirePackage{tcolorbox}% + [2024/07/10] + +\tcbuselibrary{breakable, skins} \RequirePackage{clrstrip}% [2021-08-28] -\RequirePackage{tcolorbox}[2023/06/19] +\RequirePackage{minted2}% Temporary patch? minted3 seems very slow8 + +\RequirePackage{tcolorbox}% + [2024/07/10] + \tcbuselibrary{minted, breakable, skins} +\RequirePackage{fontawesome5}% + [2022-05-02] + \RequirePackage{marginnote}% [2023-09-07] +% ======================= % +% == AVAILABLE OPTIONS == % +% ======================= % + +% ----------------- % % -- 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 @@ -97,7 +131,13 @@ \ExplSyntaxOff +% =============== % +% == MAIN CODE == % +% =============== % + +% --------------------- % % -- LOCALE SETTINGS -- % +% --------------------- % \NewDocumentCommand{\tutodoc@colon}{}{:} @@ -115,12 +155,16 @@ \ExplSyntaxOff +% ---------------------- % % -- GENERAL SETTINGS -- % +% ---------------------- % \setlength{\parindent}{0cm} +% ----------- % % -- LINKS -- % +% ----------- % \hypersetup{ colorlinks, @@ -131,7 +175,9 @@ } +% --------------- % % -- TOC & Co. -- % +% --------------- % \ifcsundef{chapter}% {}% @@ -173,7 +219,35 @@ \DeclareTOCStyleEntry[indentfollows = chapter]{tocline}{section} +% --------------------------- % +% -- 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% +} + + +% ------------- % % -- QUOTING -- % +% ------------- % %%% % prototype:: @@ -186,7 +260,9 @@ } +% ------------------------------ % % -- EXPLAINING ENGLISH NAMES -- % +% ------------------------------ % %%% % prototype:: @@ -215,9 +291,13 @@ } -% -- FOCUS ON SOME CONTENT -- % +% ----------------------------------- % +% -- SOBER HIGHLIGHTING OF CONTENT -- % +% ----------------------------------- % +% ::::::::::::::::::::::::::::::: % % :: EXAMPLE - HIDDEN VERSIONS :: % +% ::::::::::::::::::::::::::::::: % %%% % See the \doc of the macro ''\newtheorem'' from the package ''amsthm'' @@ -240,7 +320,9 @@ \newtheorem*{@@tdocexa@no@nb}{\tutodoc@trans@exa@title} +% :::::::::::::::::::::::::::::: % % :: EXAMPLE - PUBLIC VERSION :: % +% :::::::::::::::::::::::::::::: % \ExplSyntaxOn @@ -248,7 +330,7 @@ { Unknown ~ rafters ~ option. } { See ~ the ~ documentation ~ for ~ the ~ supported ~ options. } -\NewDocumentEnvironment{tdocexa}{D<>{nb} O{}}{ +\NewDocumentEnvironment{ tdocexa } { D<>{nb} O{} } { \str_case:nnF { #1 } { { nb } { \begin{@@tdocexa@nb}[#2] @@ -261,7 +343,7 @@ } }{ \str_case:nnF { #1 } { - { nb } { + { nb } { \end{@@tdocexa@nb} } { nonb } { @@ -273,61 +355,85 @@ \ExplSyntaxOff +% :::::::::::: % % :: REMARK :: % +% :::::::::::: % %%% % See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' % to have \infos about the environment ''tdocrem''. %%% -\newtheorem*{tdocrem}{\tutodoc@trans@rmk@title} +\newtheorem*{tdocrem}{\tutodoc@trans@rem@title} -% :: IMPORTANT :: % +% -------------------------------------- % +% -- COLORFUL HIGHLIGHTING OF CONTENT -- % +% -------------------------------------- % -%%% -% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' -% to have \infos about the environment ''tdocimportant''. -%%% -\newtheorem*{tdocimportant}{\tutodoc@trans@important@title} - - -% :: NOTE :: % - -%%% -% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' -% to have \infos about the environment ''tdocnote''. -%%% -\newtheorem*{tdocnote}{\tutodoc@trans@note@title} +% ::::::::::::::::: % +% :: ABSTRACTION :: % +% ::::::::::::::::: % +% Sources used. +% + https://tex.stackexchange.com/a/727022/6880 +% + https://tex.stackexchange.com/a/682332/6880 -% :: TIP :: % +\tcbset{ + tutodoc-focus-color-style/.style = { + breakable, + enhanced, +% fonttitle = \itshape, +% halign title = center, + fontupper = \color{\tdocdarkcolor{#1}}, + colback = \tdoclightcolor{#1}, + colframe = #1!75!black!45, + shadow = {.75mm}{-.75mm}{0mm}{black!30}, +% We want to use the same color for the footnotes in the frame. + before upper = {\let\default@color\current@color}, + } +} -%%% -% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' -% to have \infos about the environment ''tdoctip''. -%%% -\newtheorem*{tdoctip}{\tutodoc@trans@tip@title} +% ::::::::::::::::::::::::::::::::::::: % +% :: LET'S GO BACK TO THE REAL WORLD :: % +% ::::::::::::::::::::::::::::::::::::: % -% :: CUATION :: % +\ExplSyntaxOn -%%% -% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' -% to have \infos about the environment ''tdoccaution''. -%%% -\newtheorem*{tdoccaution}{\tutodoc@trans@caution@title} +\prop_set_from_keyval:Nn \__g_tutodoc_focus_color_prop { + note = cyan, + tip = ForestGreen,%lime, + imp = orange, + caution = violet, + warn = red, +} +\prop_set_from_keyval:Nn \__g_tutodoc_focus_icon_prop { + note = \faInfoCircle, + tip = \faLightbulb, + imp = \faHighlighter, + caution = \faBiohazard, + warn = \faSkullCrossbones, +} -% :: WARNING :: % +\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 = { + \prop_item:Nn \__g_tutodoc_focus_icon_prop { #1 } \kern3.5pt + \use:c { tutodoc@trans@#1@title } + }, + ] +} -%%% -% See the \doc of the macro ''\newtheorem*'' from the package ''amsthm'' -% to have \infos about the environment ''tdocwarn''. -%%% -\newtheorem*{tdocwarn}{\tutodoc@trans@warn@title} +\ExplSyntaxOff +% ---------------------------------------------- % % -- NAMES OF PACKAGES, MACROS & ENVIRONMENTS -- % +% ---------------------------------------------- % %%% % prototype:: @@ -380,18 +486,24 @@ } +% ------------------------- % % -- 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:: @@ -421,7 +533,9 @@ \ExplSyntaxOff +% ::::::::::::::::::::: % % :: JUST ONE PREFIX :: % +% ::::::::::::::::::::: % %%% % prototype:: @@ -438,9 +552,13 @@ } +% ------------------------ % % -- GENERAL FORMATTING -- % +% ------------------------ % +% :::::::::::::::::::::::: % % :: TEXT INSIDE A RULE :: % +% :::::::::::::::::::::::: % \ExplSyntaxOn @@ -483,31 +601,9 @@ \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:: @@ -556,7 +652,9 @@ \ExplSyntaxOn +% ::::::::::::::::::::::: % % :: SETTING SOME KEYS :: % +% ::::::::::::::::::::::: % \tl_new:N \l_tdoc_showcase_before_tl \tl_new:N \l_tdoc_showcase_after_tl @@ -585,7 +683,9 @@ } +% :::::::::::::::::::::::::::::: % % :: SHOWCASE FROM TYPED CODE :: % +% :::::::::::::::::::::::::::::: % % prototype:: % #1 : the key-value options. @@ -625,7 +725,9 @@ } +% :::::::::::::::::::::::: % % :: SHOWCASE FROM FILE :: % +% :::::::::::::::::::::::: % %%% % prototype:: @@ -647,9 +749,13 @@ \ExplSyntaxOff +% -------------------- % % -- LATEX EXAMPLES -- % +% -------------------- % +% ::::::::::::::::::::::::::::: % % :: INLINE SHORT LATEX CODE :: % +% ::::::::::::::::::::::::::::: % %%% % See the \doc of the macro ''\newmintinline'' from the package ''minted'' @@ -658,7 +764,9 @@ \newmintinline[tdocinlatex]{latex}{bgcolor = yellow!4} +% ::::::::::::::::::::::::::::::::::::::::::::::: % % :: SHORTCUTS FOR TCOLORBOX LISTING FORMATING :: % +% ::::::::::::::::::::::::::::::::::::::::::::::: % \ExplSyntaxOn @@ -684,7 +792,9 @@ \ExplSyntaxOff +% ::::::::::::::::::::::::::::::::: % % :: THE TCOLORBOX LISTING STYLE :: % +% ::::::::::::::::::::::::::::::::: % %%% % note:: @@ -696,6 +806,7 @@ tdoclatex_tcbstyle/.style = { minted language = latex, breakable, + enhanced, % Code and output colback = yellow!5, % Frame @@ -707,7 +818,6 @@ % We can use ''sharp corners'' to obtain an "old school" style. % % Separating line - enhanced, segmentation style = { gray, dash pattern = {on 5pt off 2.5pt}, @@ -718,7 +828,9 @@ } +% ::::::::::::::::::::::::::::::::::: % % :: TCOLORBOX LISTING ENVIRONMENT :: % +% ::::::::::::::::::::::::::::::::::: % %%% % prototype:: @@ -736,7 +848,9 @@ } +% :::::::::::::::::::::::::::::::::::::: % % :: TCOLORBOX IMPORTED LISTING MACRO :: % +% :::::::::::::::::::::::::::::::::::::: % %%% % prototype:: @@ -753,11 +867,15 @@ } +% -------------------------- % % -- LATEX REAL USE CASES -- % +% -------------------------- % \ExplSyntaxOn +% ::::::::::::::::::::::: % % :: SETTING SOME KEYS :: % +% ::::::::::::::::::::::: % \tl_new:N \l_tdoc_listing_explain_tl @@ -773,7 +891,9 @@ } +% ::::::::::::::::::::: % % :: LATEXSHOW MACRO :: % +% ::::::::::::::::::::: % %%% % prototype:: @@ -805,14 +925,18 @@ \ExplSyntaxOn +% :::::::::::::: % % :: MESSAGES :: % +% :::::::::::::: % \msg_set:nnnn { tdoc } { date-bad-format } { Bad ~ format ~ for ~ a ~ date. } { Use ~ YYYY-MM-DD. } +% ::::::::::::::::: % % :: MARGIN NOTE :: % +% ::::::::::::::::: % \reversemarginpar{} @@ -890,8 +1014,12 @@ {#3} } +\ExplSyntaxOff + +% :::::::::::::::::::::: % % :: VERSION AND DATE :: % +% :::::::::::::::::::::: % %%% % prototype:: @@ -916,7 +1044,9 @@ } +% :::::::::: % % :: DATE :: % +% :::::::::: % %%% % prototype:: @@ -928,22 +1058,30 @@ %%% \NewDocumentCommand{\tdocdate}{O{blue} m}{ \tutodoc@new@change@margin{#1} % Color - {#2} % Date - {} % Version - {-5.35pt} % Last negative spacing + {#2} % Date + {} % Version + {-5.35pt} % Last negative spacing } +% --------------------- % % -- CHANGES - WHAT? -- % +% --------------------- % +\ExplSyntaxOn + +% :::::::::::::: % % :: MESSAGES :: % +% :::::::::::::: % \msg_set:nnnn { tdoc } { changes-topic-missing-title } { Missing ~ title. } { One ~ single ~ title ~ must ~ be ~ indicated. } +% ::::::::::::::::::::: % % :: CHANGES - TOPIC :: % +% ::::::::::::::::::::: % %%% % prototype:: @@ -952,12 +1090,13 @@ % :action: this environment prints some ¨infos about specific changes % achieved in a new version (no special formatting is applied). %%% -\NewDocumentEnvironment{tdoctopic}{ m }{ +\NewDocumentEnvironment{tdoctopic}{ m O{} }{ \IfBlankT{#1}{ \msg_fatal:nn { tdoc } { changes-topic-missing-title } } \textbf{ + \IfBlankF{#2}{#2\kern3.5pt}% \textsc{#1.} } @@ -967,89 +1106,40 @@ } +% :::::::::::::::::::::::::: % % :: 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}{\tutodoc@trans@chges@new} -}{ - \end{tdoctopic} +% :::::::::::::::::::::::::: % + +\prop_set_from_keyval:Nn \__g_tutodoc_topic_change_prop { + break = \faCodeBranch, + fix = \faWrench, + new = \faGem, + prob = \faFire*, + update = \faMagic, } -% :: 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}{\tutodoc@trans@chges@update} -}{ - \end{tdoctopic} -} - - -% :: CHANGES - BREAK :: % - -%%% -% prototype:: -% :see: env.tdoctopic -% -% :action: similar to the \env ''tdoctopic'' with the title "Break" -% translated into the good language. -%%% -\NewDocumentEnvironment{tdocbreak}{}{ - \begin{tdoctopic}{\tutodoc@trans@chges@break} -}{ - \end{tdoctopic} -} - - -% :: CHANGES - PROBLEM :: % - -%%% -% prototype:: -% :see: env.tdoctopic -% -% :action: similar to the \env ''tdoctopic'' with the title "Problem" -% translated into the good language. -%%% -\NewDocumentEnvironment{tdocprob}{}{ - \begin{tdoctopic}{\tutodoc@trans@chges@pb} -}{ - \end{tdoctopic} -} - - -% :: CHANGES - FIX :: % - -%%% -% prototype:: -% :see: env.tdoctopic -% -% :action: similar to the \env ''tdoctopic'' with the title "Fix" +% :action: similar to the \env ''tdoctopic'' with the title "New" % translated into the good language. %%% -\NewDocumentEnvironment{tdocfix}{}{ - \begin{tdoctopic}{\tutodoc@trans@chges@fix} -}{ - \end{tdoctopic} +\prop_map_inline:Nn \__g_tutodoc_topic_change_prop { + \NewDocumentEnvironment{ tdoc#1 } {} { + \begin{tdoctopic}{ \use:c { tutodoc@trans@chges@#1 } } [ #2 ] + }{ + \end{tdoctopic} + } } \ExplSyntaxOff +% ----------------- % % -- DECORATIONS -- % +% ----------------- % % Source for \addvspace{\medskipamount} instead of \medskip. % * https://tex.stackexchange.com/a/705938/6880 |