Better Markdown syntax for code cells


#1

Idea Overview

Change the Markdown syntax of code cells so that it is more compatible with other Markdown parsers.

External language cells

The current syntax for R, Python etc cells is:

```z=call(x,y){py}
 return x * y
```

Problems:

  • the z=call(x,y){py} bit is not recognised as a language and so the code doesn’t get highlighted properly by other Markdown rendering tools e.g Github
  • spaces in the z=call(x,y){py} bit cause parsing problems!
  • the z=call(x,y){py} bit is not visible when rendered by other Markdown rendering tools so it’s not obvious that it’s an executed code cell!

Alternative syntax for a call cell with two inputs and an output

```py
#! z=x,y
x * y
```

A call cell with no inputs but an output

```py
#! z=
math.pi
```

A call cell with no output (result is displayed in the document, not assigned to a variable)

```py
#!
math.pi
```

A run cell (i.e. in the global scope of the execution context) would use double exclamation marks:

```py
#!!
z = x * y
```

Notes:

  • The fenced codeblock annotation is just the conventional language code, meaning that it will get highlighted correctly by tools such as Github or Pandoc.

  • Use a shebang to indicate a cell is to be executed. This is consistent with the use of shebangs in scripts indicating how it should be executed. It’s also visible when rendered using other tools.

  • More terse - no need to write run and call - it’s implied by whether there is an output to the cell.

  • Dropping the use of return statements as this can be confusing.

Mini language cells

The current syntax for Mini cells is:

```.
z = x * y
```

Problems with this:

  • not very explicit
  • not consistent with the alternative syntax above

Alternative syntax:

```mini
#!
z = x * y
```

Notes:

  • more verbose, but more consistent and explicit
  • allows for non-executed, codeblocks of mini in the document (i.e. without shebang, consistent with other languages)

Audience

Authors and readers of Markdown files. Most ‘consumers’ of Stencila documents will read them via a WYSIWYG interface so this is of little relevance to them.

Benefits

Better compatability with existing Markdown editing and rendering tools. More consistency between Mini and External language cells.


#2

With @michael and Oliver we designed a new syntax for use in the UI which does away with run and call and instead introduces the language as keywords (e.g. r, js) and a global keyword.

UI

In the UI instead of

z = call(x,y)                            [R]

it will be

z = r(x,y)

Instead of

run()                                   [Python]

it will be

global py()

Markdown

To be consistent in Markdown:

```r
#! z = x,y
...
```

and

```py
#! global
...
```

#3

Nice! Is this something you are working on?


#4

Yes, we got this into the 0.27 release :tada:!