✅ Benefits of Literate Programming

• Documentation and code stay synchronized - Your explanations live alongside

• Better understanding - Force yourself to explain your reasoning

• Reproducible research - Combine analysis, code, and results in one document

• Exploratory programming - Test ideas interactively like a notebook

• Multiple outputs from one source - Tangle code files and export documentation

✅ Literate Programming in Org-Mode

Org-mode's Babel system brings literate programming to org documents:

• Write code in source blocks with full syntax highlighting

• Execute blocks and capture results inline

• Pass data between blocks in different languages

• Extract (tangle) code to external files

• Include or exclude code/results in exports

✅ Basic Structure

A source block begins with #+BEGIN_SRC and ends with #+END_SRC:

print("Hello, world!")

Hello, world!

✅ Language Declaration

The language comes immediately after #+BEGIN_SRC:

# Python code here

// JavaScript code here

# Shell commands here

✅ Header Arguments

Header arguments control block behavior and appear after the language:

# This block prints results and uses a persistent session

✅ Results Section

When you execute a block, results appear immediately below in a #+RESULTS: section:

print(2 + 2)

4

✅ Execution Keybindings

✅ Execution Commands

✅ Execution Flow

1. Place cursor inside a source block

2. Press C- (or s- on Mac)

3. Code executes using the appropriate language interpreter

4. Results appear below the block in a #+RESULTS: section

5. Previous results are replaced automatically

✅ Example

import math
result = math.sqrt(16)
print(f"The square root of 16 is {result}")

The square root of 16 is 4.0

✅ Direct Execution Languages

These languages execute directly without requiring Jupyter:

✅ Jupyter Kernel Languages

For enhanced interactive features, use Jupyter kernels by prefixing the language with jupyter- or relying on automatic Jupyter detection:

✅ Jupyter Benefits

Using Jupyter kernels provides:

• Persistent state - Variables persist between executions in the same session

• Rich output - Display plots, images, HTML, and LaTeX

• Interactive widgets - Use ipywidgets and similar libraries

• Automatic display - Images from matplotlib, plots, etc. appear automatically

✅ Example: Mixing Languages

echo "System: $(uname -s)"

System: Darwin

import platform
print(f"Python version: {platform.python_version()}")

Python version: 3.12.11

console.log(`Node version: ${process.version}`);

Node version: v25.2.1

✅ Syntax

print(arg1, arg2)

value1 5

✅ Results Arguments

print("Line 1")
print("Line 2")

Line 1
Line 2

42

print("Name,Age,City")
print("Alice,30,NYC")
print("Bob,25,Boston")

import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])

✅ Export Arguments

# Only this code appears in PDF/HTML export
print("Secret result")

✅ Variable Arguments

print(f"{name} is {age} years old")

Alice is 30 years old

result = x + y
print(f"{x} + {y} = {result}")

40 + 20 = 60

for row in data:
    print(f"{row[0]}: {row[1]}")

✅ Session Arguments

x = 42
print("x defined")

x defined

print(f"x = {x}")

x = 42

✅ Directory Arguments

pwd

/private/tmp

import os
print(os.getcwd())

/Users/jkitchin/Dropbox/projects/scimax_vscode/.github

✅ Tangling Arguments

def helper_function():
    """This function will be extracted to utils.py"""
    return "helper"

from utils import helper_function

def main():
    print(helper_function())

if __name__ == "__main__":
    main()

✅ Cache Arguments

import time
time.sleep(5)  # Expensive operation
result = 42
print(result)

42

✅ Other Useful Arguments

ls | head -n2

_minted
_static

ls | head -n2

print("This will be wrapped in a quote block")

print(sys.version)

3.12.11 (main, Jun 12 2025, 12:22:42) [Clang 20.1.4 ]
Done

# Shell script runs with -x flag (print commands)
echo "Hello"

Hello

✅ Combining Arguments

Arguments can be combined:

import pandas as pd
df = pd.read_csv('data.csv')
print(df.head())

1  2  3
0  4  5  6

✅ Automatic Result Insertion

When you execute a block, results automatically appear below it in a

✅ Result Types by Language

print("Hello")
print("World")

Hello
World

data = [['Alice', 30], ['Bob', 25], ['Carol', 35]]
return data

import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9]);

html = "<h1>Title</h1><p>Paragraph</p>"
print(html)

for i in range(20):
    print(f"Line {i}")

✅ Error Handling

When execution fails, error messages appear in results:

undefined_variable

Traceback (most recent call last):
  File "<string>", line 50, in <module>
  File "<string>", line 1, in <module>
NameError: name 'undefined_variable' is not defined

✅ Clearing Results

✅ What Are Sessions?

Sessions maintain a persistent interpreter process that preserves state between executions. This is similar to how Jupyter notebooks work - variables, functions, and imports persist.

✅ Enabling Sessions

Add :session header argument:

x = 42
y = 10

result = x + y
print(result)

52

✅ Named Sessions

Use different session names to maintain separate contexts:

import pandas as pd
df = pd.read_csv('data.csv')

import unittest
# Separate session for tests

# Can still access df here
print(df.head())

✅ Session Scope

• Sessions are per-language and per-name

• Default session name (when you just use :session) is language-specific

• Use :session none to explicitly disable session for a block

• Sessions persist for the duration of the VS Code window

✅ Jupyter Sessions

When using Jupyter kernels (e.g., jupyter-python), sessions automatically use Jupyter kernel instances:

import numpy as np
data = np.random.randn(100)

import matplotlib.pyplot as plt
plt.hist(data, bins=20);

✅ Benefits of Sessions

• Avoid re-computation - Load data once, use in multiple blocks

• Interactive development - Build up code incrementally

• Shared context - Split long workflows into logical chunks

• Testing - Set up fixtures in one block, test in others

✅ Session Limitations

• Sessions consume memory until VS Code closes

• Long-running sessions can accumulate stale state

• Restart VS Code to clear all sessions

• Session state is not saved to disk

✅ Block Navigation Keybindings

✅ Navigation Commands

✅ Quick Block Selection

Use scimax.ob.jumpToBlock to see a searchable list of all source blocks:

• Shows language and block name

• Displays first line as preview

• Filter by language or content

• Jump instantly to any block

✅ Example Workflow

1. Write code in first block

2. Press S- to execute and move to next block

3. Write code that depends on previous block

4. Press S- again

5. Continue building up your analysis sequentially

✅ Creating Blocks

✅ Splitting Blocks

x = 1
y = 2
z = x + y
print(z)

#+BEGIN_SRC python
x = 1
y = 2

z = x + y
print(z)

✅ Merging Blocks

✅ Copying and Killing

✅ Moving Blocks

✅ Typical Workflows

✅ Syntax

src_LANGUAGE{CODE}
src_LANGUAGE[HEADERS]{CODE}

✅ Examples

The answer is 4 which equals 4.

total = 100
tax_rate = 0.08

✅ Use Cases

• Embedding calculations in text

• Showing dates/times

• Inserting computed values into sentences

• Quick one-liners that don't need a full block

✅ Limitations

• No syntax highlighting

• Results replace the inline block (can't keep both)

• Less suitable for multi-line code

• Harder to debug than regular blocks

✅ What Is Tangling?

Tangling extracts code from source blocks marked with :tangle into external files:

• Write narrative documentation with embedded code blocks

• Extract all code to build/run your project

• Keep docs and code in perfect sync

✅ Enabling Tangling

Add :tangle filename.ext to source blocks:

#!/usr/bin/env python3

def main():
    print("Hello from tangled code!")

if __name__ == "__main__":
    main()

✅ Tangling Commands

✅ Tangling Modes

# Not tangled by default

def utility_function():
    return "useful"

def another_utility():
    return "also useful"

# Tangles to default file (based on org filename)

✅ Advanced Tangling

import sys
import os

def helper():
    return "help"

<<imports>>
<<helpers>>

def main():
    print(helper())

echo "This will be executable"

# [[file:literate.org::*Section Name][Section Name:1]]
# code here
# Section Name:1 ends here

✅ Use Cases

* Database Configuration
We use PostgreSQL with connection pooling.

#+BEGIN_SRC toml :tangle tangled/config.toml
[database]
host = "localhost"
port = 5432
pool_size = 10

✅ Named Blocks

Give blocks names using #+NAME: so they can be referenced:

print(x * x)

✅ Calling Named Blocks

Use #+CALL: to invoke a named block with arguments:

25

100

return x * x

✅ Inline Call Syntax

You can also call blocks inline:

The square of 7 is call_square(x7) {{{results(49=)}}}.

Reference named blocks as variables:

total = sum(row[1] for row in data[1:])  # Skip header
print(f"Total: {total}")

Total: 450

✅ Call with Headers

Override headers when calling:

121

✅ Library of Functions

Build a library of reusable code blocks:

import numpy as np
return np.mean(numbers)

import numpy as np
return np.median(numbers)

np.float64(30.0)

np.float64(30.0)

✅ Best Practices

• Use descriptive names: load-data, calculate-statistics, generate-plot

• Document block parameters in preceding text

• Keep blocks focused and reusable

• Use #+CALL: for parameterized re-execution

• Consider blocks as functions in your literate program

✅ Essential Keybindings

✅ Common Header Arguments

✅ Supported Languages

Direct: python, javascript, typescript, shell, bash, sql

Jupyter: jupyter-python, jupyter-r, jupyter-julia, jupyter-ruby, and many more

✅ Example Templates

# Your code here

# Code with persistent state

# Process data
return processed

def my_function():
    """Documented function"""
    pass

✅ Organization

• Use headings to group related blocks

• Name important blocks with #+NAME:

• Add #+CAPTION: to blocks that produce key results

• Use sessions to connect related blocks

✅ Performance

• Use :cache yes for expensive computations

• Close unnecessary sessions to free memory

• Use :results silent when you don't need output

• Limit output size for large datasets

✅ Reproducibility

• Specify exact versions in documentation

• Use :dir to set working directory explicitly

• Document all dependencies in requirements/environment

• Include data loading steps in the document

✅ Debugging

• Execute blocks one at a time with C-

• Check session state in separate test blocks

• Use :results output to see print statements

• Clear results and re-execute from top to verify

✅ Collaboration

• Export to HTML/PDF for non-technical readers (:exports results)

• Tangle to source files for developers (:tangle yes)

• Use meaningful block names for #+CALL: references

• Document assumptions and requirements in text

✅ Common Pitfalls

• Forgetting to enable sessions when blocks depend on each other

• Using :results value when you want printed output

• Not clearing stale results before sharing

• Referencing blocks that haven't executed yet

• Mixing session names unintentionally

✅ Emacs Org-Mode Documentation

While Scimax VS Code implements its own version, the Emacs org-mode documentation is valuable for understanding concepts:

• Working with Source Code

• Babel Introduction

• Babel Language Reference

✅ Scimax VS Code Docs

• Getting Started Guide

• Document Structure

• Tables

✅ Related Topics

• Jupyter integration for rich interactive notebooks

• Export system for generating documents

• Database integration for storing and searching code blocks

• Project notebooks for organizing research