Better literate programming

[amitu]

https://axleos.com/writing-about-writing-about-programming/

What would better literate programming look like with fastn?

A fastn document can contain one or more code blocks. We can create an option to download all the code blocks in that document.

The code blocks source code can be a template, e.g.:

-- ftd.code:
lang: ftd
string foo: hello
filename: ${foo}.ftd

\-- $foo:

Which will download a file hello.ftd, -- hello:` in the editor. And this is what will be downloaded.

fastn build?

How to handle this on build time is tricky, since the template variable can be read from query params etc, and we do not know if all documents must be contain such "embedded" literate program or not.

Splitting Code Across Multiple Blocks

Further literate programming typically allows you to split a code block into multiple blocks, so you focus on each item at a time, so we need a meta language to refer to other code blocks defined in this document, eg

-- ds.heading-medium: Init

We are going to call `init()` function to initialise things.

-- ftd.code:
id: init
lang: py

init()

-- ds.heading-medium: main

The main program looks like this:


-- ftd.code:
lang: py
filename: hello.pt

def main():
    @init@
    print("this is the rest of main")

if __name__ == "__main__":
    main()

Here we have two code blocks, one with filename and other with id. filename ones will be included in generated zip, and they can refer to other code blocks in the current file via @<id>@ syntax (not finalised, open for suggestions).

We should also support @<path>:<id>@ so blocks defined in other documents can be included.

Splitting Things Over Multiple Files

Since we may want to split the whole literate programming thing in multiple blocks, how do we tell fastn that this set of files are to be parsed when the zip file is being computed? One option is we use sitemap somehow.

Other option we include allow explicit ftd.literate kernel, which when present will act like ftd.json etc, so you can download the zip even without fastn doing something magical, the logic of when to return zip can be in your hand.

And you can include the other files from other docs:

-- ftd.literate-zip:
filename: hello-world.zip ;; the name of the zip file used when storing in the Downloads folder
include: /tutorial-part-1/
include: /tutorial-part-2/

We have explicitly passed include, which will look for code snippets in all the included files, when generating hello-world.zip.