You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
The text was updated successfully, but these errors were encountered:
Hope my chiming in here is OK. I definitely think option 1 is the most clunky and we tend to stay away from it. Very often you would only have 1 option you want to specify and then you need to write 3 extra lines to do it, also it's just ticks, hyphens, colons everywhere at some point, which is confusing. I like the attribute syntax for "native markdown code blocks" which you just implemented, but not sure about using them for all the other attributes... but maybe?
Currently there are two ways of specifying options within a directive:
(option 1) enclosing in
----
(option 2) prepending all lines by
:
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:
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)
(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)
It is of note, that the only place where we definitely need a direct mapping of
options <-> JSON
is incode-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.The text was updated successfully, but these errors were encountered: