Add a new built-in theme witiko/diagrams

.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

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.

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,
@@ -22898,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}
 ```````
 
@@ -35198,14 +35201,33 @@ 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}
 \prop_gput:Nnn
   \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 +35317,60 @@ 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:nnnen
+          { markdown }
+          { unknown-theme-version }
+          { witiko/diagrams }
+          { \markdownThemeVersion }
+          { v1 }
+      }
+  }
+\cs_generate_variant:Nn
+  \msg_error:nnnnn
+  { nnnen }
+\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:
 %
@@ -35483,6 +35559,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