-
Notifications
You must be signed in to change notification settings - Fork 7
Description
Currently there are two ways of specifying options within a directive:
(option 1) enclosing in ----
```{name}
---
option1: value
option2: value
---
```
(option 2) prepending all lines by :
```{name}
:option1: value
:option2: value
```
Firstly, there should be one clear way of doing things, and so it would be ideal to remove one of these.
Secondly, the following logic proceeds for converting them to the "final" input options for the directive:
- identifying the full block of text
- parse it with YAML (and abort if the result is not a dictionary)
- convert all the values back to strings
- convert the values back to specific value types (and validate) by "converters" specified by the directive implementation
Clearly here the YAML value parsing is unnecessary, and worse can lead to discrepancies, such as a:
becomes {"a": null}
as opposed to {"a": ""}
.
YAML is also quite complex (see e.g. here) and not really necessary for the more simple requirements of option parsing.
If we accept that it is the directive implementation's responsibility to do any conversions from strings,
then we simply need a syntax/format that maps string keys to string values.
There are two ways to do this that come to mind:
-
Something like field lists (see the rST spec, and mdit-py implementation), i.e. very similar to the current (option2)
```{name} :name: x :class: y :other: z ```
(It is of note that in the field list spec, keys are parsed as Markdown, that is not what we want here though)
-
Block attributes before the directive (see here)
{#x .y other=z} ```{name} ```
It is of note, that the only place where we definitely need a direct mapping of options <-> JSON
is in code-cell
, whereby the options actually map to the metadata of a Jupyter Notebook code cell.
In this case though, code-cell
can be viewed as a "pseudo-directive" and perhaps should have a different syntax, so as not to be confusing.