ATS Tutorials Tooling Support
Our toolset provides you with a plugin and supporting files on top of a regular pandoc
workflow: writing markdown, and getting webpages. You gain all the benefits of markdown and all the power of pandoc
, and you can easily wirte ATS programming language tutorials that embeds editable/runnable ATS code with proper highlighting.
All the tools you need is in the released lib
folder. It contains
- a python filter
ats_tutorialize.py
forpandoc
, which processes incomingpandoc
parse tree, and transform it in some way to produce interactive tutorials.
- a template
ats_template.html
- a javascript file
ats_service.js
(compiled from coffeescript) that provides the interactive part of the webpage. - several stylesheets
- and an example with proper makefile.
Before we can start, we need to ensure that we have the following software installed.
- python3, pip3, and virtualenv
- pandoc (latest)
Contribution
Please head to https://github.com/steinwaywhw/ats-tutorials. Issues, pull requests are welcomed.
Installation
Installation is easy, just download the release.tar.gz, and install necessary softwares. Requested python packages can be setup by the following steps.
make -f example.make setup_venv # setup virtual env and install python packages
source .venv/bin/activate # enter the virtual env
Then you can start working on the tutorials. After finished, remeber to deactivate the virtual environment by
deactivate
Getting Start
With example.make
and example.md
, we just type
make -f example.make
and the output will be in example.md
. This example file mainly demonstrats how a regular markdown file looks like, with features like * YAML front matter, where you can configure the behavior of both pandoc
and our filter. For pandoc
parameters, see its user guide. * basic formattings of elements, e.g. headings, paragraghs, lists, inline code, etc. See pandoc
user guide for full references. See here for a quick look. * fenced code blocks with options, see followings for details. The code blocks with .ats
option will be processed by our filter. Others will be processed by pandoc
as usual.
Using Code Blocks
Let's take a fully equipped example as follows.
```{#assignment1 .ats .dynamic}
extern fun hello (): string
implement main0 () = ()
```
extern fun hello (): string
implement main0 () = ()
Here, after the opening fence, a curly brace is used to provide options. #assignment1
is the id of this code block, which will be the id of corresponding html element in the output. .ats
and .dynamic
are classes of the code, specifying that this is dynamic ATS code that needs to be highlighted. You can add more classes, they will be passed unchanged to the resulting html elements as their classes. If you are writing static ATS code, just change .dynamic
to .static
.
If you have a longer file, that you don't want to compose in-place, use the option include=file.ext
as below.
```{#assignment1 .ats .dynamic include="example.dats"}
```
extern fun hello (): string
implement hello () = "world"
implement main0 () = () where {
val _ = println! (hello ())
}
If you want the code to be editable, just add .editable
as below.
```{#assignment1 .ats .dynamic .editable include="example.dats"}
```
The resulting page will provide a group of buttons, for editing the code, as well as type-checking, compiling to c, and compiling to javascript.
Other Options
As you can see, in the YAML front matter (the beginning of the raw content of this markdown file), we have several options to set. They are as follows.
hljs
: usehighlight.js
if set to true. use default styling iffalse
.true
by default.hljs-style
: choose a theme forhighlight.js
, see github for a complete list of styles.ace-style
: choose a theme for theace
editor, see github for a complete list. Default tosolarized_dark
.title
: Title of the document. This is part of the options provided bypandoc
, see theats_template.html
for a full list of options. Just look for template variables enclosed in$
.