From daa458b38cdb091f47b94ee90d2c810b52aec9f2 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Wed, 13 Mar 2024 23:57:34 +0100 Subject: [PATCH 1/3] feat: Support bare percentage in width and height options --- examples/sile-and-djot.dj | 6 +++--- examples/sile-and-markdown.md | 4 ++-- packages/markdown/cmbase.lua | 17 +++++++++++++++++ 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/examples/sile-and-djot.dj b/examples/sile-and-djot.dj index ef0ac8a..9a22118 100644 --- a/examples/sile-and-djot.dj +++ b/examples/sile-and-djot.dj @@ -56,7 +56,7 @@ The core concepts in Djot mirror those of Markdown, featuring inline and block e Attributes are additional properties or metadata that can be associated with certain elements, allowing for more fine-grained control over the appearance and behavior of elements. -![Djot concepts at a glance.](./djot-concept-simplified.svg){width="75%lw"} +![Djot concepts at a glance.](./djot-concept-simplified.svg){width="75%"} ## Attributes @@ -346,14 +346,14 @@ This inline "manicule" is obtained with: Files in Graphviz DOT graph language (`.dot`) are supported and rendered as images, when the *embedders.sile* collection is properly configured. -![The *markdown.sile* ecosystem (simplified).](./markdown-sile-schema.dot){width="90%lw"} +![The *markdown.sile* ecosystem (simplified).](./markdown-sile-schema.dot){width="90%"} This image is obtained with the following syntax. {custom-style=CodeBlock} ::: ``` -![The *markdown.sile* ecosystem (simplified).](./markdown-sile-schema.dot){width="90%lw"} +![The *markdown.sile* ecosystem (simplified).](./markdown-sile-schema.dot){width="90%"} ``` ::: diff --git a/examples/sile-and-markdown.md b/examples/sile-and-markdown.md index e3933e2..40c3f84 100644 --- a/examples/sile-and-markdown.md +++ b/examples/sile-and-markdown.md @@ -323,13 +323,13 @@ This inline "manicule" is obtained with: Files in Graphviz DOT graph language (`.dot`) are supported and rendered as images, when the **embedders.sile** collection is properly configured. -![The **markdown.sile** ecosystem (simplified).](./markdown-sile-schema.dot){width="90%lw"} +![The **markdown.sile** ecosystem (simplified).](./markdown-sile-schema.dot){width="90%"} This image is obtained with the following syntax. ::: {custom-style=CodeBlock} ``` -![The **markdown.sile** ecosystem (simplified).](./markdown-sile-schema.dot){width="90%lw"} +![The **markdown.sile** ecosystem (simplified).](./markdown-sile-schema.dot){width="90%"} ``` ::: diff --git a/packages/markdown/cmbase.lua b/packages/markdown/cmbase.lua index 11f4336..20ecf2b 100644 --- a/packages/markdown/cmbase.lua +++ b/packages/markdown/cmbase.lua @@ -115,6 +115,23 @@ function package:_init (_) end) end +function package:registerCommand(name, func, help, pack) + local tweakCommandWithKnownOptions = function (options, content) + options = options or {} + -- Tweak known options to be compatible with SILE units. + -- width and height in percentage are replaced by line and frame relative + -- units, respectively. + if options.width and type(options.width) == "string" then + options.width = options.width:gsub("%%$", "%%lw") + end + if options.height and type(options.height) == "string" then + options.height = options.height:gsub("%%$", "%%fh") + end + return func(options, content) + end + base.registerCommand(self, name, tweakCommandWithKnownOptions, help, pack) +end + --- Register a style (as in resilient packages). function package:registerStyle (name, opts, styledef) return self.styles:defineStyle(name, opts, styledef, self._name) From 5260ea6a10c7144a155d5280ce16dc6d55c2bbab Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Thu, 14 Mar 2024 00:32:14 +0100 Subject: [PATCH 2/3] docs: Add final chapter with notes on width and height in percents --- examples/final-notes.dj | 13 +++++++++++++ examples/sile-and-djot.dj | 5 +---- examples/sile-and-markdown-manual.silm | 1 + examples/sile-and-markdown.md | 2 +- 4 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 examples/final-notes.dj diff --git a/examples/final-notes.dj b/examples/final-notes.dj new file mode 100644 index 0000000..aac9111 --- /dev/null +++ b/examples/final-notes.dj @@ -0,0 +1,13 @@ +# Miscellaneous notes + +[T]{custom-style=Initial}[his section]{.smallcaps} contains some tips and tricks to help you get the most out of the converter. +It is the place where some less obvious features are documented. +It also intends at answering some frequently asked questions, so feel free to ask for more information if you feel something is missing. + +{#final-notes-units} +## Regarding width and height attributes + +Most of the time, the converter does not check the validity of the key-value attributes passed to the SILE underlying commands, and it is their responsibility to do so. + +However, for convenience, width and height attributes can be expressed in percentages, and the converter will automatically convert them to SILE's line and frame relative units, respectively. +(E.g., `width=50%` becomes `width=0.5%lw`, and `height=50%` becomes `height=0.5%fh`.) diff --git a/examples/sile-and-djot.dj b/examples/sile-and-djot.dj index 9a22118..88138df 100644 --- a/examples/sile-and-djot.dj +++ b/examples/sile-and-djot.dj @@ -300,8 +300,7 @@ This is obtained with the following syntax: ::: Attributes are optional, and are passed through to the underlying SILE package. -You can notably specify the required image width and/or height, as done just above, by appending the `{width=... height=...}` attributes --- Note that any unit system supported by SILE is accepted.[^djot-img-attributes] - +You can notably specify the required image width and/or height, as done just above, by appending the `{width=... height=...}` attributes --- Note that any unit system supported by SILE is accepted, as well as percentages (see §[](#final-notes-units)). There are actually two kinds of image syntax: (direct) inline images and (indirect) reference images. Above, we used the former kind. The reference images are defined elsewhere in the document, and are referenced by their label: @@ -319,8 +318,6 @@ The reference images are defined elsewhere in the document, and are referenced b Note that attributes are specified before the reference label (considered as a block element). Direct (inline) link's attributes override reference's attributes. -[^djot-img-attributes]: The converter does not check the validity of the attributes, and it is the responsibility of the underlying package to do so. - {#djot-captioned-images} #### Implicit captioned figures diff --git a/examples/sile-and-markdown-manual.silm b/examples/sile-and-markdown-manual.silm index 5ee6849..960ac0d 100644 --- a/examples/sile-and-markdown-manual.silm +++ b/examples/sile-and-markdown-manual.silm @@ -55,3 +55,4 @@ chapters: - sile-and-markdown.md - sile-and-pandoc.dj - pandoc-tables.pandoc + - final-notes.dj diff --git a/examples/sile-and-markdown.md b/examples/sile-and-markdown.md index 40c3f84..9de8033 100644 --- a/examples/sile-and-markdown.md +++ b/examples/sile-and-markdown.md @@ -283,7 +283,7 @@ Here is an image: ![](./gutenberg.jpg){width=1.5cm} ::: Attributes are optional, and are passed through to the underlying SILE package. -You can notably specify the required image width and/or height, as done just above, by appending the `{width=... height=...}` attributes --- Note that any unit system supported by SILE is accepted. +You can notably specify the required image width and/or height, as done just above, by appending the `{width=... height=...}` attributes --- Note that any unit system supported by SILE is accepted, as well as percentages (see §[](#final-notes-units)). ::: {custom-style=Difference} ![](./examples/manicule.svg){height=1.3ex} **Main differences with Djot** From 7458d281529d6085ff328dd0fdf567a0e62d2a01 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Thu, 14 Mar 2024 00:42:15 +0100 Subject: [PATCH 3/3] docs: Replace SILE document by SIL markup in package documentations --- packages/djot/init.lua | 2 +- packages/markdown/init.lua | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/djot/init.lua b/packages/djot/init.lua index b376891..9bb7d5a 100644 --- a/packages/djot/init.lua +++ b/packages/djot/init.lua @@ -53,7 +53,7 @@ Other possibilities exist (such as setting \autodoc:parameter{format=djot} on th \autodoc:command{\include} command, if the file extension cannot be one of the supported variants, etc.). Refer to the SILE manual for more details on inputters and their usage. -Embedding raw Djot content from within a SILE document is also possible: +Embedding raw Djot content from within a document in SIL markup is also possible: \begin{verbatim} \\begin[type=djot]\{raw\} diff --git a/packages/markdown/init.lua b/packages/markdown/init.lua index b3334aa..a6727f0 100644 --- a/packages/markdown/init.lua +++ b/packages/markdown/init.lua @@ -52,7 +52,7 @@ Other possibilities exist (such as setting \autodoc:parameter{format=markdown} o \autodoc:command{\include} command, if the file extension cannot be one of the supported variants, etc.). Refer to the SILE manual for more details on inputters and their usage. -Embedding raw Markdown content from within a SILE document is also possible: +Embedding raw Markdown content from within a document in SIL markup is also possible: \begin{verbatim} \\begin[type=markdown]\{raw\}