From 3d0ea08476ee244df57392821a667b92780e2b59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Tue, 17 Dec 2024 13:46:57 +0100 Subject: [PATCH 1/5] Add version `v1` of the built-in theme `witiko/diagrams` --- markdown.dtx | 95 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 86 insertions(+), 9 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 8269a66b..540ec707 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -90,7 +90,7 @@ ]{markdown} \markdownSetup{ import = { - witiko/dot, + witiko/diagrams@v1, witiko/graphicx/http, witiko/markdown/techdoc = { options as lua-options @@ -1415,8 +1415,8 @@ soft amsfonts % \pkg{graphicx} % %: A package that provides extended support for graphics. It is used in -% the `witiko/dot` and `witiko/graphicx/http` plain \TeX{} themes, see -% Section <#sec:themes>. +% the `witiko/diagrams`, and `witiko/graphicx/http` plain \TeX{} themes, +% see Section <#sec:themes>. % % \end{markdown} % \begin{macrocode} @@ -12951,14 +12951,14 @@ a specific look and other high-level goals without low-level programming. Built-in plain \TeX{} themes provided with the Markdown package include: -\pkg{witiko/dot} +\pkg{witiko/diagrams@v1} : A theme that typesets fenced code blocks with the `dot …` infostring as images of directed graphs rendered by the Graphviz tools. The right tail of the infostring is used as the image title. % ```` tex % \documentclass{article} -% \usepackage[import=witiko/dot]{markdown} +% \usepackage[import=witiko/diagrams@v1]{markdown} % \setkeys{Gin}{ % width = \columnwidth, % height = 0.65\paperheight, @@ -12993,8 +12993,8 @@ Built-in plain \TeX{} themes provided with the Markdown package include: % \end{document} % ```````` % Typesetting the above document produces the output shown in -% Figure <#fig:witiko/dot>. -% ``` dot Various formats of mathemathical formulae \label{fig:witiko/dot} +% Figure <#fig:witiko/diagrams@v1>. +% ``` dot Various formats of mathemathical formulae \label{fig:witiko/diagrams@v1} % digraph tree { % margin = 0; % rankdir = "LR"; @@ -13022,6 +13022,12 @@ Built-in plain \TeX{} themes provided with the Markdown package include: Graphviz installed. The theme also requires shell access unless the \Opt{frozenCache} plain \TeX{} option is enabled. + The above example loads version `v1` of the theme, which is an alias for + an earlier theme named `witiko/dot`. Future versions of the theme may have + backwards-incompatible syntax and behavior. Therefore, you are encouraged + to always specify the version `v1` to keep your documents from suddenly + breaking. + % \markdownEnd % \iffalse @@ -13031,7 +13037,7 @@ Using a text editor, create a text document named `document.tex` with the following content: ```` tex \documentclass{article} -\usepackage[import=witiko/dot]{markdown} +\usepackage[import=witiko/diagrams@v1]{markdown} \setkeys{Gin}{ width=\columnwidth, height=0.65\paperheight, @@ -35198,7 +35204,8 @@ end % \end{macrocode} % \begin{markdown} % -% The `witiko/dot` theme enables the \Opt{fencedCode} Lua option: +% The `witiko/dot` theme nags users that they should use the name +% `witiko/diagrams@v1` instead. % % \end{markdown} % \begin{macrocode} @@ -35206,6 +35213,23 @@ end \g_@@_plain_tex_built_in_themes_prop { witiko / dot } { + \str_if_eq:enF + { \markdownThemeVersion } + { silent } + { + \markdownWarning + { + The~theme~name~"witiko/dot"~has~been~soft-deprecated. \iow_newline: + Consider~changing~the~name~to~"witiko/diagrams@v1". + } + } +% \end{macrocode} +% \begin{markdown} +% +% We enable the \Opt{fencedCode} Lua option. +% +% \end{markdown} +% \begin{macrocode} \markdownSetup{fencedCode} % \end{macrocode} % \begin{markdown} @@ -35295,6 +35319,59 @@ end % \end{macrocode} % \begin{markdown} % +% The `witiko/diagrams` loads the theme `witiko/dot`. +% +% \end{markdown} +% \begin{macrocode} +\prop_gput:Nnn + \g_@@_plain_tex_built_in_themes_prop + { witiko / diagrams } + { + \str_case:enF + { \markdownThemeVersion } + { + { latest } + { + \markdownWarning + { + Write~"witiko/diagrams@v1"~to~pin~version~"v1"~of~the~theme~ + "witiko/diagrams".~This~will~keep~your~documents~from~suddenly~ + breaking~when~we~have~released~future~versions~of~the~theme~with~ + backwards-incompatible~syntax~and~behavior. + } + \markdownSetup + { + import = witiko/dot@silent, + } + } + { v1 } + { + \markdownSetup + { + import = witiko/dot@silent, + } + } + } + { + \msg_error:nnVen + { markdown } + { unknown-theme-version } + \g_@@_current_theme_tl + { \markdownThemeVersion } + { v1 } + } + } +\cs_generate_variant:Nn + \msg_error:nnnnn + { nnVen } +\msg_new:nnnn + { markdown } + { unknown-theme-version } + { Unknown~version~"#2"~of~theme~"#1"~has~been~requested. } + { Known~versions~are:~#3 } +% \end{macrocode} +% \begin{markdown} +% % We locally change the category code of percent signs, so that we % can use them in the shell code: % From a913b6ac1f0f91b28e4b53b58e2e54e6eac0dd9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Tue, 17 Dec 2024 13:47:17 +0100 Subject: [PATCH 2/5] Add example themes `witiko/example/foo` and `witiko/example/bar` --- markdown.dtx | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 540ec707..ddc20df0 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -22904,24 +22904,21 @@ developers can load the `.tex` theme file from the `.sty` theme file using the % specified in the `\usepackage` macro, the loading of the theme(s) will be % postponed in first-in-first-out order until after the Markdown \LaTeX{} % package has been loaded. Otherwise, the theme(s) will be loaded immediately. -% For example, there is a theme named `witiko/dot`, which typesets fenced code -% blocks with the `dot` infostring as images of directed graphs rendered by the -% Graphviz tools. The following code would first load the Markdown package, -% then the `markdownthemewitiko_beamer_MU.sty` \LaTeX{} package, and finally -% the `markdownthemewitiko_dot.sty` \LaTeX{} package: +% For example, the following code would first load the Markdown package, then +% the theme `witiko/example/foo`, and finally the theme `witiko/example/bar`: % \end{markdown} % \iffalse -For example, to load themes named `witiko/beamer/MU` and `witiko/dot`, you -would use the following code in the preamble of your document: +For example, to load themes named `witiko/example/foo` and `witiko/example/bar`, +you would use the following code in the preamble of your document: % \fi % \begin{markdown} ``` tex \usepackage[ - import=witiko/beamer/MU, - import=witiko/dot, + import=witiko/example/foo, + import=witiko/example/bar, ]{markdown} ``````` @@ -35560,6 +35557,29 @@ end }, } } +% \end{macrocode} +% \begin{markdown} +% +% The themes `witiko/example/foo` and `witiko/example/bar` are supposed to be +% used in code examples. They don't do anything. +% +% \end{markdown} +% \begin{macrocode} +\clist_map_inline:nn + { foo, bar } + { + \prop_gput:Nnn + \g_@@_plain_tex_built_in_themes_prop + { witiko / example / #1 } + { + \markdownWarning + { + The~theme~witiko/example/#1~is~supposed~to~be~used~in~code~examples.~ + Using~it~in~actual~code~has~no~effect,~except~this~warning~message,~ + and~is~usually~a~mistake. + } + } + } \ExplSyntaxOff % \end{macrocode} % \iffalse From b79bc52c118b2551dee9b955534796de2abee9fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Tue, 17 Dec 2024 14:00:13 +0100 Subject: [PATCH 3/5] Fix overlong lines --- .github/workflows/main.yml | 2 +- markdown.dtx | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 57fc79cd..4caa5e07 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -122,7 +122,7 @@ jobs: - name: Extract TeX files run: make base - name: Run explcheck - run: explcheck --warnings-are-errors -- *.tex *.sty + run: explcheck --warnings-are-errors --max-line-length=72 -- *.tex *.sty markdownlint: name: Style check (Markdown) runs-on: ubuntu-latest diff --git a/markdown.dtx b/markdown.dtx index ddc20df0..5e97ae3a 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -35216,7 +35216,8 @@ end { \markdownWarning { - The~theme~name~"witiko/dot"~has~been~soft-deprecated. \iow_newline: + The~theme~name~"witiko/dot"~has~been~soft-deprecated. + \iow_newline: Consider~changing~the~name~to~"witiko/diagrams@v1". } } @@ -35331,10 +35332,11 @@ end { \markdownWarning { - Write~"witiko/diagrams@v1"~to~pin~version~"v1"~of~the~theme~ - "witiko/diagrams".~This~will~keep~your~documents~from~suddenly~ - breaking~when~we~have~released~future~versions~of~the~theme~with~ - backwards-incompatible~syntax~and~behavior. + Write~"witiko/diagrams@v1"~to~pin~version~"v1"~of~the~ + theme~"witiko/diagrams".~This~will~keep~your~documents~ + from~suddenly~breaking~when~we~have~released~future~ + versions~of~the~theme~with~backwards-incompatible~ + syntax~and~behavior. } \markdownSetup { @@ -35574,9 +35576,9 @@ end { \markdownWarning { - The~theme~witiko/example/#1~is~supposed~to~be~used~in~code~examples.~ - Using~it~in~actual~code~has~no~effect,~except~this~warning~message,~ - and~is~usually~a~mistake. + The~theme~witiko/example/#1~is~supposed~to~be~used~in~code~ + examples.~Using~it~in~actual~code~has~no~effect,~except~ + this~warning~message,~and~is~usually~a~mistake. } } } From 5a9a6f788ae021d1a97a504a1b542b7f79d3b7cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Tue, 17 Dec 2024 14:09:24 +0100 Subject: [PATCH 4/5] Update `CHANGES.md` --- CHANGES.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index f56dbc95..16821750 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,17 @@ ## 3.9.1 +Development: + +- Add version `v1` of the new built-in theme `witiko/diagrams`. + (#514, #531, #538) + + This version is an alias for an earlier theme named `witiko/dot`. Future + versions of the theme may have backwards-incompatible syntax and behavior, + see the discussion in #514 and #531. Therefore, you are encouraged to always + specify the version `v1` to keep your documents from suddenly breaking. The + Markdown package will warn you if you don't. + Fixes: - Make option `eagerCache` safe to use with plain LuaTeX. @@ -12,6 +23,11 @@ Continuous Integration: - Use explcheck to check expl3 code in the continuous integration. (#535, #536, b4e3bfcd) +Deprecation: + +- Soft-deprecate the name of the built-in theme `witiko/dot` in favor of + the new built-in theme `witiko/diagrams@v1`. (#514, #531, #538) + Distribution: - Make `markdown-cli` executable and symlink it to system directories. From 0e42322a3abafaf1d4db118ef820a9aed59dc23d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Tue, 17 Dec 2024 14:17:36 +0100 Subject: [PATCH 5/5] Prevent printing extra trailing slash in error message --- markdown.dtx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 5e97ae3a..d6659030 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -35352,17 +35352,17 @@ end } } { - \msg_error:nnVen + \msg_error:nnnen { markdown } { unknown-theme-version } - \g_@@_current_theme_tl + { witiko/diagrams } { \markdownThemeVersion } { v1 } } } \cs_generate_variant:Nn \msg_error:nnnnn - { nnVen } + { nnnen } \msg_new:nnnn { markdown } { unknown-theme-version }