Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Support bare percentage in width and height options #114

Merged
merged 3 commits into from
Mar 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions examples/final-notes.dj
Original file line number Diff line number Diff line change
@@ -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`.)
11 changes: 4 additions & 7 deletions examples/sile-and-djot.dj
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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

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

Expand Down
1 change: 1 addition & 0 deletions examples/sile-and-markdown-manual.silm
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,4 @@ chapters:
- sile-and-markdown.md
- sile-and-pandoc.dj
- pandoc-tables.pandoc
- final-notes.dj
6 changes: 3 additions & 3 deletions examples/sile-and-markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down Expand Up @@ -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%"}
```
:::

Expand Down
2 changes: 1 addition & 1 deletion packages/djot/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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\}
Expand Down
17 changes: 17 additions & 0 deletions packages/markdown/cmbase.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion packages/markdown/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -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\}
Expand Down