# Using the Literate Markdown Tangler Quarto Extension

## The Literate Markdown Tangler

The Literate Markdown Tangler (LMT) is a Quarto Extension that provides users with a Pandoc Lua filter to write code in the literate programming framework.

### Installation

If you use Quarto, you can install the extension with `add_lmt()` in R:

    library(speakr)
    add_lmt()

See below to learn how to use the extension with Quarto documents.

The LMT extension can be used even if you don’t use Quarto. Download the `_extension/lmt/` directory from the extension repo and save the `lmt` directory with its content where pandoc can find it. Then you can just pass `lmt/lmt.lua` as a Lua script to pandoc when rendering the source file (for example if you want to use it with R Markdown files).

You can use the Praat syntax highlighting definition to highlight the Praat code in the rendered file. Get the syntax definition `praat.xml` here. (This vignette uses the tango syntax highlighting theme.)

## Use

Create a new `.qmd` file and add the following in the YAML header of the Quarto document:

    filters:
      - lmt

When you render the document, the Pandoc filter will be run to create the Praat scripts defined in the document (see the following sections to learn how to define scripts).

## `hello.praat`

To initialise a file (in this case our first script), use a code block and specify the file name, like so:

    ```{.praat file="hello.praat"}
    # hello.praat
    writeInfoLine: "Hello Praat!"

    <<<append>>>

    <<<fin>>>
    ```

This will create a file `hello.praat` with the code in the code block and it will embed code from the referenced code blocks (i.e. `append` and `fin`).

Let’s define the `append` block. We can do so with a code block for which we specify the `ref` name:

    ```{.praat ref="append"}
    # append
    appendInfoLine: "Heya!"

    for i from 1 to 5
        <<<loop>>>
    endfor
    ```

You will see that this code block has a referenced block too! Referencing works recursively. The `loop` code block is defined below.

    ```{.praat ref="loop"}
    # loop
    appendInfoLine: i
    ```

## `second.praat`

Now let’s make a new script.

    ```{.praat file="second.praat"}
    # second.praat
    x$ = "a"
    writeInfoLine: x$

    <<<fin>>>
    ```

## `fin`

Of course, code blocks can be reused! Also note that the order in which the code blocks are specified does not matter.

    ```{.praat ref="fin"}
    # fin
    appendInfoLine: "That's all!"
    ```

## Render

Now you can just render the source file (the `.qmd` file) to generate the defined scripts in the same directory as the source file and get an HTML/PDF version of the source file that can be used as documentation of the scripts!