From 4fe2194c0df14e9242c2f394c358aa04e657282f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Novotn=C3=BD?= Date: Wed, 22 Nov 2023 13:30:28 +0100 Subject: [PATCH] Move theme docs from plain TeX to LaTeX, document macro `\markdownSuper` --- markdown.dtx | 109 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 65 insertions(+), 44 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 40cf7eb9..a9c832e0 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -769,12 +769,6 @@ abbr { volume = {B}, location = {Reading, MA}, publisher = {Addison-Wesley}} -@online{novotny21, - author = {Novotný, Vít}, - title = {\Hologo{LaTeX2e} no longer keys packages by pathnames}, - date = {2021-02-20}, - url = {https://github.com/latex3/latex2e/issues/510}, - urldate = {2021-02-21}} @book{eijkhout92, author = {Victor Eijkhout}, title = {\TeX{} by Topic}, @@ -11843,6 +11837,41 @@ A PDF document named `document.pdf` should be produced and contain the text % \end{macrocode} % \iffalse % +%<*manual-options> +% \fi +% \begin{markdown} + +#### Themes {#themes} + +User-defined themes for the Markdown package provide a domain-specific +interpretation of Markdown tokens. Themes allow the authors to achieve +a specific look and other high-level goals without low-level programming. + +% The key-values `theme`=\meta{theme name} and `import`=\meta{theme name} load +% a \TeX{} document (further referred to as *a theme*) named +% `markdowntheme`\meta{munged theme name}`.tex`, where the *munged theme name* +% is the *theme name* after the substitution of all forward slashes (`/`) for +% an underscore (`_`). The theme name is *qualified* and contains no +% underscores. A theme name is qualified if and only if it contains at least +% one forward slash. Themes are inspired by the Beamer \LaTeX{} package, which +% provides similar functionality with its `\usetheme` macro [@tantau21, Section +% 15.1]. +% +% Theme names must be qualified to minimize naming conflicts between different +% themes with a similar purpose. The preferred format of a theme name is +% \meta{theme author}`/`\meta{theme purpose}`/`\meta{private naming +% scheme}, where the *private naming scheme* may contain additional forward +% slashes. For example, a theme by a user `witiko` for the MU theme of the +% Beamer document class may have the name `witiko/beamer/MU`. +% +% Theme names are munged to allow structure inside theme names without +% dictating where the themes should be located inside the \TeX{} directory +% structure. For example, loading a theme named `witiko/beamer/MU` would +% load a \TeX{} document package named `markdownthemewitiko_beamer_MU.tex`. +% +% \end{markdown} +% \iffalse +% %<*manual-tokens> ## Markdown Tokens @@ -20327,46 +20356,38 @@ package. Setting the option after loading the package will have no effect. % \fi % \begin{markdown} -#### \LaTeX{} themes {#latexthemes} +#### Themes {#latexthemes} -User-defined \LaTeX{} themes for the Markdown package provide a domain-specific -interpretation of Markdown tokens. Similarly to \LaTeX{} packages, themes -allow the authors to achieve a specific look and other high-level goals -without low-level programming. +% In Section~\ref{sec:themes}, we described the concept of themes. +In \LaTeX{}, we expand on the concept of +% themes +% \iffalse +[themes](#themes) +% \fi +by allowing a theme to be a full-blown \LaTeX{} package. Specifically, the +key-values `theme`=\meta{theme name} and `import`=\meta{theme name} load a +\LaTeX{} package named `markdowntheme`\meta{munged theme name}`.sty` if it +exists and a \TeX{} document named `markdowntheme`\meta{munged theme +name}`.tex` otherwise. -% The \LaTeX{} option `import`=\meta{theme name} loads a \LaTeX{} package -% (further referred to as *a theme*) named `markdowntheme`\meta{munged theme -% name}`.sty`, where the *munged theme name* is the *theme name* after the -% substitution of all forward slashes (`/`) for an underscore (`_`), the theme -% *name* is *qualified* and contains no underscores, and a value is qualified -% if and only if it contains at least one forward slash. Themes are inspired -% by the Beamer \LaTeX{} package, which provides similar functionality with -% its `\usetheme` macro [@tantau21, Section 15.1]. -% -% Theme names must be qualified to minimize naming conflicts between different -% themes intended for a single \LaTeX{} document class or for a single \LaTeX{} -% package. The preferred format of a theme name is \meta{theme author}`/`\meta{target \LaTeX{} document class or package}`/`\meta{private naming -% scheme}, where the *private naming scheme* may contain additional forward -% slashes. For example, a theme by a user `witiko` for the MU theme of the -% Beamer document class may have the name `witiko/beamer/MU`. -% -% Theme names are munged, because \LaTeX{} packages are identified only by -% their filenames, not by their pathnames. [@novotny21] Therefore, we can't -% store the qualified theme names directly using directories, but we must -% encode the individual segments of the qualified theme in the filename. For -% example, loading a theme named `witiko/beamer/MU` would load a \LaTeX{} -% package named `markdownthemewitiko_beamer_MU.sty`. -% -% If the \LaTeX{} option with key `theme` is (repeatedly) 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: +Having the Markdown package automatically load either the generic `.tex` +*theme file* or the \LaTeX-specific `.sty` theme file allows developers +to have a single *theme file*, when the theme is small or the difference +between \TeX{} formats is unimportant, and scale up to separate theme files +native to different \TeX{} formats for large multi-format themes, where +different code is needed for different \TeX{} formats. To enable code reuse, +developers can load the `.tex` theme file from the `.sty` theme file using the +\mdef{markdownSuper} command. + +% If the \LaTeX{} option with keys `theme` or `import` is (repeatedly) +% 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: % \end{markdown} % \iffalse