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

Remove YAML dependency from directive option parsing #51

Open
chrisjsewell opened this issue Oct 11, 2022 · 1 comment
Open

Remove YAML dependency from directive option parsing #51

chrisjsewell opened this issue Oct 11, 2022 · 1 comment

Comments

@chrisjsewell
Copy link
Contributor

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:

  1. identifying the full block of text
  2. parse it with YAML (and abort if the result is not a dictionary)
  3. convert all the values back to strings
  4. 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:

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

  2. 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.

@mgielda
Copy link

mgielda commented Feb 24, 2023

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants