Merge pull request #114 from Omikhleia/feat-known-percentage-options

feat: Support bare percentage in width and height options

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`.)

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
@@ -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
 
@@ -346,14 +343,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%"}
 ```
 :::
 

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

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**
@@ -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%"}
 ```
 :::
 

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\}

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)

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\}