From 23b4e8623e0d4344d6addd5017faf1123b67b375 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 1 Mar 2025 19:26:31 +0100 Subject: [PATCH 1/2] feat: Use SILE's 0.15.10 "cites" for multiple bibliography citations --- examples/biblio.dj | 3 +++ examples/lightweight-markup.dj | 2 +- examples/markdown-djot.bib | 7 ++++++ examples/sile-and-markdown-manual-styles.yml | 2 -- examples/sile-and-markdown-manual.silm | 23 +++++++++++--------- examples/toc.dj | 4 +++- packages/markdown/commands.lua | 6 ----- packages/markdown/utils.lua | 9 +++++++- 8 files changed, 35 insertions(+), 21 deletions(-) create mode 100644 examples/biblio.dj diff --git a/examples/biblio.dj b/examples/biblio.dj new file mode 100644 index 0000000..620150a --- /dev/null +++ b/examples/biblio.dj @@ -0,0 +1,3 @@ +# Selected bibliography + +:_BIBLIOGRAPHY_: diff --git a/examples/lightweight-markup.dj b/examples/lightweight-markup.dj index 6a6005e..032dab5 100644 --- a/examples/lightweight-markup.dj +++ b/examples/lightweight-markup.dj @@ -63,7 +63,7 @@ Beyond technical considerations, it's also worth examining the functionality of Markdown can be intricate, with subtle nuances where even a single space can trigger unexpected effects. It exhibits non-intuitive behaviors, such as the use of indentation to denote code blocks. There are inconsistent outcomes with lists, emphases, headings... - See John MacFarlane's ["Beyond Markdown"](https://johnmacfarlane.net/beyond-markdown.html) essay for some more examples, and the reasons that led him propose Djot. + See John MacFarlane's ["Beyond Markdown"](https://johnmacfarlane.net/beyond-markdown.html) essay for some more examples, and the reasons that led him propose Djot [@djot:macfarlane2018]. : Extensibility diff --git a/examples/markdown-djot.bib b/examples/markdown-djot.bib index 4fd3bf5..207eee1 100644 --- a/examples/markdown-djot.bib +++ b/examples/markdown-djot.bib @@ -21,3 +21,10 @@ @book{sile:willis2024 author = {Willis, Didier}, year = {2024}, } + +@article{djot:macfarlane2018, + author = {MacFarlane, John}, + title = {Beyond Markdown}, + year = {2018}, + url = {https://talk.commonmark.org/t/beyond-markdown/2787}, +} diff --git a/examples/sile-and-markdown-manual-styles.yml b/examples/sile-and-markdown-manual-styles.yml index 88283fb..7f5940a 100644 --- a/examples/sile-and-markdown-manual-styles.yml +++ b/examples/sile-and-markdown-manual-styles.yml @@ -982,8 +982,6 @@ sectioning-appendix-main-number: origin: "resilient.book" style: numbering: - before: - text: "Appendix " display: "ALPHA" sectioning-appendix-ref-number: diff --git a/examples/sile-and-markdown-manual.silm b/examples/sile-and-markdown-manual.silm index 960ac0d..343721b 100644 --- a/examples/sile-and-markdown-manual.silm +++ b/examples/sile-and-markdown-manual.silm @@ -46,13 +46,16 @@ sile: - dropcaps - resilient.defn - resilient.poetry -chapters: - - toc.dj - - extra-styles.dj - - introduction.dj - - lightweight-markup.dj - - sile-and-djot.dj - - sile-and-markdown.md - - sile-and-pandoc.dj - - pandoc-tables.pandoc - - final-notes.dj +content: + chapters: + - toc.dj + - extra-styles.dj + - introduction.dj + - lightweight-markup.dj + - sile-and-djot.dj + - sile-and-markdown.md + - sile-and-pandoc.dj + - pandoc-tables.pandoc + - file: final-notes.dj + content: + - biblio.dj diff --git a/examples/toc.dj b/examples/toc.dj index 6503853..0d8b17d 100644 --- a/examples/toc.dj +++ b/examples/toc.dj @@ -1,6 +1,8 @@ ```=sile-lua SILE.call("open-on-odd-page") -SILE.call("noheaders") ``` +{.unnumbered .notoc} +# Contents + :_TOC_: diff --git a/packages/markdown/commands.lua b/packages/markdown/commands.lua index 0a37057..ff43521 100644 --- a/packages/markdown/commands.lua +++ b/packages/markdown/commands.lua @@ -840,12 +840,6 @@ Please consider using a resilient-compatible class!]]) end end, "Symbol in Djot (internal)") - self:registerCommand("markdown:internal:citations", function (_, content) - -- We cannot handle multiple citations yet in a single call. - -- See https://github.com/sile-typesetter/sile/issues/2196 - SILE.process(content) - end, "Citations (internal)") - -- B. Fallback commands self:registerCommand("markdown:fallback:blockquote", function (_, content) diff --git a/packages/markdown/utils.lua b/packages/markdown/utils.lua index 4009a09..1646c89 100644 --- a/packages/markdown/utils.lua +++ b/packages/markdown/utils.lua @@ -133,7 +133,14 @@ local function naiveCitations (str, pos) end return createCommand("cite", { key = key }, nil, pos) end, refs) - return createStructuredCommand("markdown:internal:citations", {}, refs, pos) + if #refs == 0 then + SU.warn("No valid citation reference found in '" .. str .. "'") + return {} + end + if #refs == 1 then + return refs[1] + end + return createStructuredCommand("cites", {}, refs, pos) end --- @export From 4ea14c4ba1ea4e6df24b8ace9d0bb923736272d9 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Fri, 21 Mar 2025 20:43:40 +0100 Subject: [PATCH 2/2] docs: User manual review for 2.4.0 --- README.md | 4 ++-- examples/introduction.dj | 6 +++--- examples/markdown-djot.bib | 8 +++++--- examples/sile-and-djot.dj | 11 ++++++----- examples/sile-and-markdown-manual.silm | 8 ++++---- examples/sile-and-markdown.md | 19 +++++++++---------- examples/sile-and-pandoc.dj | 2 +- packages/markdown/commands.lua | 2 +- rockspecs/markdown.sile-2.4.0-1.rockspec | 2 +- 9 files changed, 32 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 600ce5e..1242efd 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ For casual readers, this collection notably aims at easily converting Djot or Ma ## Installation -This module collection requires SILE v0.14 or upper. +This module collection requires SILE v0.14 or upper (recommended: v0.15.10). Installation relies on the **luarocks** package manager. @@ -153,7 +153,7 @@ This is but an overview. For more details, please refer to the provided example - Raw inline HTML convenience subset in Markdown - Advanced use of symbols in Djot (variable substitution ,and templating) - Advanced configuration (e.g. Markdown variants, headings shifting, etc.) -- Bibliography citations (when appropriate support is enabled) +- Bibliography citations ## Use with the resilient collection diff --git a/examples/introduction.dj b/examples/introduction.dj index 60ac854..83ab6c9 100644 --- a/examples/introduction.dj +++ b/examples/introduction.dj @@ -28,7 +28,7 @@ Yet, these options remain available under the hood for those seeking a blend of ### Standard installation -This module collection requires SILE v0.14 or upper. +This module collection requires SILE v0.14 (recommended: v0.15.10 or upper). Installation relies on the *luarocks* package manager. To install the latest version, you may use the provided “rockspec”: @@ -148,7 +148,7 @@ Let's illustrate this for Djot, but the same applies to Markdown. {custom-style=CodeBlock} ::: -``` +```sil \use[module=packages.djot] \include[src=somefile.dj] ``` @@ -159,7 +159,7 @@ Again, the same applies to Markdown. {custom-style=CodeBlock} ::: -``` +```sil \begin[type=djot]{raw} Some *Djot* content \end{raw} diff --git a/examples/markdown-djot.bib b/examples/markdown-djot.bib index 207eee1..897c9bc 100644 --- a/examples/markdown-djot.bib +++ b/examples/markdown-djot.bib @@ -1,19 +1,21 @@ @book{sile, title = {The SILE Book}, author = {Cozens, Simon and Maclennan, Caleb and Nicole, Olivier and Willis, Didier}, - year = {2014–202X}, + year = {2025}, + edition = {version 0.15.10}, } @book{sile:willis2021, title = {The re·sil·ient collection of classes & packages for SILE: User Guide}, author = {Willis, Didier}, - year = {2021–}, + year = {2025}, } @book{sile:willis2022, title = {Markdown and Djot to PDF with SILE: Ultimate Guide & Showcase Document}, author = {Willis, Didier}, - year = {2022–}, + origdate = {2022}, + year = {2025}, } @book{sile:willis2024, diff --git a/examples/sile-and-djot.dj b/examples/sile-and-djot.dj index 43cb601..09e00f4 100644 --- a/examples/sile-and-djot.dj +++ b/examples/sile-and-djot.dj @@ -524,16 +524,17 @@ This implementation, however, recognizes a simplified subset of the Pandoc citat ::: ``` I wrote a whole book on mathematics with SILE [@sile:willis2024]. +... also supported [@sile:willis2024; @sile:willis2022]. ... a "master document" [@sile:willis2021, part 1]. -... _The SILE Book_ for more information [@sile, chapter 5]. ``` ::: I wrote whole book on mathematics with SILE [@sile:willis2024]. +Note that multiple citations are also supported [@sile:willis2024; @sile:willis2022]. How to load bibliographies and configure citation styles is beyond the scope of this manual. -If you are using the resilient collection, the most natural way to do this is a "master document" [@sile:willis2021, part 1]. -Note that support for biblibraphies in SILE is an experimental feature, so you may also want to check _The SILE Book_ for more information [@sile, chapter 5]. +With the resilient collection, the most natural way to do this is a "master document" [@sile:willis2021, part 1]. +For more information, you may also want to check _The SILE Book_ [@sile, chapter 5]. {#djot-symbols} ### Symbols @@ -1422,7 +1423,7 @@ For instance, you can include a Djot file with shifted headings like this: {custom-style=CodeBlock} ::: -``` +```sil \include[src=somefile.dj, shift_headings=1] ``` ::: @@ -1431,7 +1432,7 @@ For document classes supporting it (in particular, the *resilient* book class), {custom-style=CodeBlock} ::: -``` +```sil \include[src=somefile.dj, shift_headings=-1] ``` ::: diff --git a/examples/sile-and-markdown-manual.silm b/examples/sile-and-markdown-manual.silm index 343721b..ddb6298 100644 --- a/examples/sile-and-markdown-manual.silm +++ b/examples/sile-and-markdown-manual.silm @@ -10,9 +10,9 @@ metadata: - Pandoc authors: Didier Willis publisher: Omikhleia - pubdate: 2024-03-01 + pubdate: 2025-03-21 url: https://github.com/Omikhleia/markdown.sile - copyright: © 2022–2024, Didier Willis. + copyright: © 2022–2025, Didier Willis. legal: | This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution, Share-Alike License, @@ -37,10 +37,10 @@ sile: layout: division 9 resolution: 300 settings: - textsubsuper.fake: false + textsubsuper.fake: true autodoc.highlighting: true document.baselineskip: 1.2em - # typesetter.italicCorrection: true # Not yet available in SILE 0.14.x + typesetter.italicCorrection: true packages: - autodoc-resilient # REQUIRED FOR RESILIENT, do not use regular autodoc - dropcaps diff --git a/examples/sile-and-markdown.md b/examples/sile-and-markdown.md index fdad2f6..0cc0132 100644 --- a/examples/sile-and-markdown.md +++ b/examples/sile-and-markdown.md @@ -512,16 +512,17 @@ This implementation recognizes a simplified subset of the Pandoc citation syntax ::: {custom-style=CodeBlock} ``` I wrote a whole book on mathematics with SILE [@sile:willis2024]. +... also supported [@sile:willis2024; @sile:willis2022]. ... a "master document" [@sile:willis2021, part 1]. -... _The SILE Book_ for more information [@sile, chapter 5]. ``` ::: I wrote whole book on mathematics with SILE [@sile:willis2024]. +Note that multiple citations are also supported [@sile:willis2024; @sile:willis2022]. How to load bibliographies and configure citation styles is beyond the scope of this manual. -If you are using the resilient collection, the most natural way to do this is a "master document" [@sile:willis2021, part 1]. -Note that support for biblibraphies in SILE is an experimental feature, so you may also want to check _The SILE Book_ for more information [@sile, chapter 5]. +With the resilient collection, the most natural way to do this is a "master document" [@sile:willis2021, part 1]. +For more information, you may also want to check _The SILE Book_ [@sile, chapter 5]. ### Symbols @@ -895,15 +896,13 @@ In most cases, the content is rendered as verbatim text, with some exceptions de Erm... Markdown supports yet another syntax for loosely defined verbatim code blocks, which is the "indented code block" syntax. This author would rather not recommend using it, and frow upon the indentation ambiguities it introduces in some cases. -::: {custom-style=CodeBlock} - This is an indented code block. -::: + This is a code block. This is obtained by indenting the content by at least four spaces... ::: {custom-style=CodeBlock} ``` - This is an indented code block. + This is a code block. ``` ::: @@ -1326,7 +1325,7 @@ In SIL documents, you can pass such options to the `\include` command or the `ra For instance, you can include a Markdown file with shifted headings like this: ::: {custom-style=CodeBlock} -``` +```sil \include[src=somefile.md, shift_headings=1] ``` ::: @@ -1334,7 +1333,7 @@ For instance, you can include a Markdown file with shifted headings like this: For document classes supporting it (in particular, the **resilient** book class), this feature also allows you to access levels above the default scheme, such as "parts". ::: {custom-style=CodeBlock} -``` +```sil \include[src=somefile.md, shift_headings=-1] ``` ::: @@ -1356,7 +1355,7 @@ Available options are: `smart`, `smart_primes`, `strikeout`, `mark`, `subscript` For instance, to disable the smart typography feature: ::: {custom-style=CodeBlock} -``` +```sil \include[src=somefile.md, smart=false] ``` ::: diff --git a/examples/sile-and-pandoc.dj b/examples/sile-and-pandoc.dj index 23ffc38..9243400 100644 --- a/examples/sile-and-pandoc.dj +++ b/examples/sile-and-pandoc.dj @@ -46,7 +46,7 @@ Once the package is loaded, the `\autodoc:command{\include[src=]}`{=sile} {custom-style=CodeBlock} ::: -``` +```sil \use[module=packages.pandocast] \include[src=somefile.pandoc] ``` diff --git a/packages/markdown/commands.lua b/packages/markdown/commands.lua index ff43521..b4e28e9 100644 --- a/packages/markdown/commands.lua +++ b/packages/markdown/commands.lua @@ -132,7 +132,7 @@ function package:_init (_) -- The class should be responsible for loading the appropriate higher-level -- constructs, see fallback commands further below for more details. self:loadPackage("bibtex") - SILE.settings:set("bibtex.style", "csl") -- The future is CSL + SILE.settings:set("bibtex.style", "csl") -- The future is CSL (active by default with SILE 0.15.10) self:loadPackage("color") self:loadPackage("embedders") self:loadPackage("highlighter") diff --git a/rockspecs/markdown.sile-2.4.0-1.rockspec b/rockspecs/markdown.sile-2.4.0-1.rockspec index ac3c7fd..5e27313 100644 --- a/rockspecs/markdown.sile-2.4.0-1.rockspec +++ b/rockspecs/markdown.sile-2.4.0-1.rockspec @@ -18,7 +18,7 @@ description = { dependencies = { "lua >= 5.1", "embedders.sile >= 0.2.0", - "highlighter.sile >= 0.2.0", + "highlighter.sile >= 0.2.1", "labelrefs.sile >= 0.1.0", "ptable.sile >= 3.2.0", "smartquotes.sile >= 1.0.0",