Shortcodes #17
Merged
Shortcodes #17
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The styles functions (`long-short`, `short-long`, and so on) determined whether this was a first occurrence directly by calling the method on the acronym object. This did not allow to override this behaviour for a specific instance (a feature that can be added thanks to Quarto shortcodes' keyworded-arguments). This commit thus adds a new parameter `is_first_use` for most of these styles functions (except those that do not differentiate between first and next uses), as well as for the "public API" `replaceWithStyle` function. For this function, the parameter can be set to `nil`, in which case the correct value will be determined by a call to `acronym:isFirstUse`, just like before. The commit thus keeps consistency with previous versions (no breaking changes), but prepares for a new feature.
In order to identify more errors when developing: - added an assert to ensure that the acronym is not `nil` when adding a new acronym; - fixed an existing error message by using `tostring` to avoid errors when the faulty value is not a string.
Previously, the `parse-acronyms.lua` script was responsible for setting the acronyms' usage order, when an acronym appears. This feature is now moved to the `Acronyms` table, so that the necessary variables are grouped together (rather than relying on script-local variables), although it is still invoked from `parse-acronyms.lua`. This change will allow to re-use the same functionality when using shortcodes, without repeating the code between several scripts.
This commit prepares the future "shortcodes" feature. Quarto Shortcodes and Pandoc Filters will share common functionalities, namely generating Pandoc elements (acronyms, list of acronyms) when invoked. However, the way they are invoked differs: Filters have to parse each element, and react to the element itself only; Shortcodes use a special syntax with a name that determines which function to call, and have arguments and keyworded arguments. The following functions have been moved from the "parse-acronyms.lua" script to the new "acronyms_pandoc.lua" script: - `replaceNonExistingAcronym` (replacing an acronym that is not found); - `replaceExistingAcronym` (replacing an acronym that is found); - `generateLoA` (generating a List Of Acronyms). In addition, these functions now take additional parameters that will allow to customize the behaviour, if necessary (instead of relying directly on the `Options` table, which is parsed from metadata). Shortcodes will have the ability to override these parameters (based on keyworded arguments), whereas Filters still use the values in `Options` (because it would be harder to parse arguments and keyworded arguments).
Historically (because this extension was initially a RMarkdown package),
**acronyms** used a Lua filter that replaces a specific markup of text.
Quarto extensions may provide such filters, but may also provide
"shortcodes" that use a clearer markup (`{{< name args >}}`, instead
of providing our own markup and regex-ing our way in the Pandoc AST).
In addition, Quarto shortcodes natively support arguments and keyworded
arguments (again, instead of regex-ing our way through the filtered
text).
This commit adds the new "shortcodes_acronyms.lua" file, which defines
the same features as the existing Pandoc filter, but using the new
Quarto shortcode syntax, by relyiong on functions that were refactored
in previous commits into the common `acronyms_pandoc.lua` helper script.
Specifically, the following shortcodes are added:
- `{{< acronym KEY >}}`: replaces an acronym identified by its `KEY`.
- `{{< acr key >}}`: same but shorter for convenience.
- `{{< print-acronyms >}}`: generates the List Of Acronyms.
WARNING: shortcodes do not seem to load (`require`) other files in the
same way as filters. Because we have helper files, this means that we must
either:
- change the `package.path` variable; however, we already know that this
does not work on Windows!
- upgrade our requirements to Quarto v1.4.0, which changed the way files
are required, and in particular added support for relative path.
We chose to continue supporting Windows, and to upgrade requirements,
especially because Quarto v1.4.0 is now officially released and
available. Users with a previous version of Quarto may still download a
previous version of **acronyms**.
Future commits will extend functionalities.
This allows shortcodes to override the parameters defined in the `Options` table, which is parsed from the metadata. For example, a specific acronym can be replaced with a style that differs from the others acronyms, by specifying the `style=...` keyword argument when using the shortcode. Strangely, the keyworded arguments return an empty Inlines when they are not specified, rather than `nil`. When they are specified, they return a non-empty Inlines. This means that we must take care when handling them, first to check whether they were specified or not, and secondly to return their string representation if they exist.
- `22-shortcode-simple` simply tests for replacing an acronym using a shortcode. - `23-shortcode-specific-style` replaces an acronym and overrides the default style (the one specified in the `Options` table, from the metadata). - `24-shortcode-listofacronyms` tests the generation of the LoA using a shortcode.
We also have to tell Quarto that our `README.md` file contains emojis, otherwise they are printed as-is (for example, `:fire:`).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Added support for Quarto shortcodes, a different syntax (
{{< acr KEY >}}) than the legacy one, inherited from filters.