diff --git a/README.md b/README.md index c2f8089..992e053 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ This collection of modules for the [SILE](https://github.com/sile-typesetter/sile) typesetting system provides a complete redesign of its former native Markdown support, with a great set of Pandoc-like extensions and plenty of extra goodies. -- **markdown** inputter and package: native support of Markdown files. - **djot** inputter and package: native support of Djot files. +- **markdown** inputter and package: native support of Markdown files. - **pandocast** inputter and package: native support of Pandoc JSON AST files. -For casual readers, this collection notably aims at easily converting Markdown or Djot documents to print-quality PDFs. +For casual readers, this collection notably aims at easily converting Djot or Markdown documents to print-quality PDFs. ## Installation diff --git a/examples/introduction.dj b/examples/introduction.dj index ac2edb9..60ac854 100644 --- a/examples/introduction.dj +++ b/examples/introduction.dj @@ -3,11 +3,11 @@ [T]{custom-style=Initial}[his]{.smallcaps} collection of modules for the [SILE](https://github.com/sile-typesetter/sile) typesetting system provides a complete redesign of its former native Markdown support. Most of the content you are reading right now is written in either Djot or Markdown, and processed using the converters offered by this collection: - - *markdown* inputter and package: native Markdown support, - *djot* inputter and package: native Djot support, + - *markdown* inputter and package: native Markdown support, - *pandocast* package: native support of Pandoc JSON AST files. -For casual readers, this collection notably aims at easily converting Markdown or Djot documents to print-quality PDFs. +For casual readers, this collection notably aims at easily converting Djot or Markdown documents to print-quality PDFs. With Djot and Markdown being made first-class citizens in SILE, you can now write your documents in these lightweight markup languages. There is actually more than one solution to achieve great results in that direction: @@ -61,7 +61,7 @@ luarocks install piecharts.sile ``` ::: -Also recommended is the *resilient.sile* collection, which provides a set of classes and packages for a more advanced usage. +Also recommended is the [*resilient.sile*](https://github.com/Omikhleia/resilient.sile) collection, which provides a set of classes and packages for a more advanced usage. It is described below in §[](#usage-with-the-resilient-collection). Note that it takes care of installing the above collections as well, so you don't have to install them separately if you go the "resilient" way. diff --git a/examples/lightweight-markup.dj b/examples/lightweight-markup.dj index 3c41252..f8a2748 100644 --- a/examples/lightweight-markup.dj +++ b/examples/lightweight-markup.dj @@ -33,12 +33,12 @@ But for most content, it's not the best approach... What if I could get rid of SIL, and any similar custom language, and use a lightweight markup language instead? Hold on, SILE is actually agnostic to the input format. Since every bit of its Lua code is exposed to the user, it's possible to extend it to support other input formats, potentially leading to wider community adoption, and independent tooling. -Enter Markdown. -Actually, enter a serious contender, Djot. +Enters Markdown. +Actually, enters a serious contender, Djot. ## On Djot over Markdown -Should you pick Djot over Markdown, as hinted by this author in the following chapters? +Should you pick Djot over Markdown, as hinted by this author here and in the following chapters? Several reasons are purely technical and relate to how the languages are implemented within this module. : Easier debugging @@ -78,3 +78,30 @@ Beyond technical considerations, it's also worth examining the functionality of However, its utility is somewhat diminished by the proliferation of dialects and extensions developed over the years. The Pandoc software adeptly handles a vast array of these variations, making it an excellent tool for converting between different flavors of Markdown. Nevertheless, since version 3.1.12, Pandoc has extended its support to Djot, rendering the distinction between Markdown and Djot less significant. + + +## On the book document class + +The converters included in this module try to play fair with SILE's *book* document class, via the provision of a set of "fallback" commands and environments. +Theses serve as wrappers, using those provided by the document class whenever possible, or implementing simpler and more basic versions as fallbacks, when not available. + +In simpler terms, by installing the _re·sil·ient_ collection, users gain access to more comprehensive and enhanced versions. +The degraded fallbacks ensure that users still have access to functional alternatives when using other document classes that lack these features. + +As stated, while we encourage the use of the *resilient.book* document class for optimal functionality and flexibility, we did not want to force people interested in using Djot or Markdown to also use it. +Nevertheless, I believe that the default SILE book class, in its current state as of 2024, may not be the most practical choice for serious projects. +The advantages of the resilient collection include: + + - A cohesive and comprehensive approach to styling decisions, simplifying complexity. + - A robust "book" class, featuring: + + - A diverse selection of page layouts, spanning from traditional to contemporary designs. + - Comprehensive support for essential book elements, including parts, chapters, sections, subsections, and subsubsections. + - Extensive customization options for table of contents, headers, footers, footnotes, and sectioning environments. + - Advanced captioned figure and table environments, among other features. + + - A versatile "master document" format, + + - Facilitating the seamless assembly of content files written in Djot, Markdown, or SIL into a cohesive work. + - Providing a structured framework for organizing your book, encompassing its front cover, half-title page, title page, endpapers, and back cover. + diff --git a/markdown.sile-1.4.1-1.rockspec b/rockspecs/markdown.sile-1.4.1-1.rockspec similarity index 100% rename from markdown.sile-1.4.1-1.rockspec rename to rockspecs/markdown.sile-1.4.1-1.rockspec diff --git a/markdown.sile-1.4.2-1.rockspec b/rockspecs/markdown.sile-1.4.2-1.rockspec similarity index 100% rename from markdown.sile-1.4.2-1.rockspec rename to rockspecs/markdown.sile-1.4.2-1.rockspec diff --git a/markdown.sile-1.5.0-1.rockspec b/rockspecs/markdown.sile-1.5.0-1.rockspec similarity index 100% rename from markdown.sile-1.5.0-1.rockspec rename to rockspecs/markdown.sile-1.5.0-1.rockspec diff --git a/markdown.sile-1.5.1-1.rockspec b/rockspecs/markdown.sile-1.5.1-1.rockspec similarity index 100% rename from markdown.sile-1.5.1-1.rockspec rename to rockspecs/markdown.sile-1.5.1-1.rockspec diff --git a/markdown.sile-1.5.2-1.rockspec b/rockspecs/markdown.sile-1.5.2-1.rockspec similarity index 100% rename from markdown.sile-1.5.2-1.rockspec rename to rockspecs/markdown.sile-1.5.2-1.rockspec diff --git a/rockspecs/markdown.sile-2.0.0-1.rockspec b/rockspecs/markdown.sile-2.0.0-1.rockspec new file mode 100644 index 0000000..486a979 --- /dev/null +++ b/rockspecs/markdown.sile-2.0.0-1.rockspec @@ -0,0 +1,61 @@ +rockspec_format = "3.0" +package = "markdown.sile" +version = "2.0.0-1" +source = { + url = "git+https://github.com/Omikhleia/markdown.sile.git", + tag = "v2.0.0", +} +description = { + summary = "Native Markdown support for the SILE typesetting system.", + detailed = [[ + This package set for the SILE typesetting system provides a complete redesign + of the native Markdown support for SILE, with a great set of Pandoc-like + extensions and plenty of extra goodies. + ]], + homepage = "https://github.com/Omikhleia/markdown.sile", + license = "MIT", +} +dependencies = { + "lua >= 5.1", + "embedders.sile >= 0.1.0", + "labelrefs.sile >= 0.1.0", + "ptable.sile >= 3.0.0", + "smartquotes.sile >= 1.0.0", + "textsubsuper.sile >= 1.1.1", + "silex.sile >= 0.5.0", +} + +build = { + type = "builtin", + modules = { + ["sile.classes.markdown"] = "classes/markdown.lua", + ["sile.inputters.markdown"] = "inputters/markdown.lua", + ["sile.inputters.pandocast"] = "inputters/pandocast.lua", + ["sile.inputters.djot"] = "inputters/djot.lua", + ["sile.packages.markdown"] = "packages/markdown/init.lua", + ["sile.packages.markdown.cmbase"] = "packages/markdown/cmbase.lua", + ["sile.packages.markdown.commands"] = "packages/markdown/commands.lua", + ["sile.packages.markdown.utils"] = "packages/markdown/utils.lua", + ["sile.packages.pandocast"] = "packages/pandocast/init.lua", + ["sile.packages.djot"] = "packages/djot/init.lua", + + ["sile.lunamark"] = "lua-libraries/lunamark.lua", + ["sile.lunamark.entities"] = "lua-libraries/lunamark/entities.lua", + ["sile.lunamark.reader"] = "lua-libraries/lunamark/reader.lua", + ["sile.lunamark.reader.markdown"] = "lua-libraries/lunamark/reader/markdown.lua", + ["sile.lunamark.util"] = "lua-libraries/lunamark/util.lua", + ["sile.lunamark.writer"] = "lua-libraries/lunamark/writer.lua", + ["sile.lunamark.writer.generic"] = "lua-libraries/lunamark/writer/generic.lua", + ["sile.lunamark.writer.html"] = "lua-libraries/lunamark/writer/html.lua", + ["sile.lunamark.writer.html5"] = "lua-libraries/lunamark/writer/html5.lua", + + ["sile.djot"] = "lua-libraries/djot.lua", + ["sile.djot.attributes"] = "lua-libraries/djot/attributes.lua", + ["sile.djot.json"] = "lua-libraries/djot/json.lua", + ["sile.djot.block"] = "lua-libraries/djot/block.lua", + ["sile.djot.inline"] = "lua-libraries/djot/inline.lua", + ["sile.djot.html"] = "lua-libraries/djot/html.lua", + ["sile.djot.ast"] = "lua-libraries/djot/ast.lua", + ["sile.djot.filter"] = "lua-libraries/djot/filter.lua", + } +} diff --git a/markdown.sile-dev-1.rockspec b/rockspecs/markdown.sile-dev-1.rockspec similarity index 99% rename from markdown.sile-dev-1.rockspec rename to rockspecs/markdown.sile-dev-1.rockspec index 295a059..e13bf07 100644 --- a/markdown.sile-dev-1.rockspec +++ b/rockspecs/markdown.sile-dev-1.rockspec @@ -1,3 +1,4 @@ +rockspec_format = "3.0" package = "markdown.sile" version = "dev-1" source = {