Using Emacs Org-Mode as a Living Notebook for Magik Development

Australian Magik developers working on Smallworld GIS platforms often juggle notes, code, and REPL output across separate tools. The Emacs editor combined with Org-Mode offers a unified environment for capturing all of this in one place. From a downtown Sydney consultancy to a remote operator in Kalgoorlie, the notebook approach has been quietly gaining traction among practitioners who value a single source of truth.

Org-Mode is far more than a to-do list. It is a structured plain-text system that handles everything from project planning to executable source code, all stored in files that travel well across machines and teams. For Magik programmers, this means the same file can contain meeting notes, design sketches, runnable code blocks, and embedded SQL queries, then render itself as HTML, PDF, or markdown for sharing with both technical and non-technical readers.

This article walks through practical ways Magik developers in Australia can adopt Org-Mode as their primary notebook, covering capture workflows, literate programming with babel, REPL integration, and team collaboration patterns. Whether you are based in Melbourne's CBD, working from a coworking space in Brisbane, or maintaining a Smallworld instance for a regional council in regional Queensland, the techniques below should slot into your existing Emacs setup.

Capturing Magik Ideas Without Breaking Flow

Org-Mode's capture system is one of its most underestimated features. A single key binding drops whatever is on your mind into a structured entry, timestamped and filed under the right heading, without forcing you to switch windows. For a Magik developer in the middle of debugging a collection iterator, this is invaluable when the phone is ringing and a colleague is waiting on a fix.

Most Smallworld teams set up capture templates for daily work logs, code review notes, and method signatures. A typical configuration might route magik-bug to a ~/notes/bugs.org file with a template that prompts for severity, affected module, and a free-form description. Over a week, these entries build into a searchable log that becomes far more useful than scattered sticky notes on a Sydney office whiteboard.

Captures can also include links directly into Emacs buffers. A note about a problematic .magik file can capture the file path and an excerpt, then be revisited later with C-c C-o to jump straight to the source. For Australian developers coordinating across AEST and AWST, this kind of contextual recall saves real time during early-morning handovers with Perth-based colleagues who often start their day before the eastern states are online.

Literate Programming Through Source Blocks

Org-Mode's babel system turns any source block into an executable artefact. A block starting with #+BEGIN_SRC magik can be evaluated directly from the buffer, sending the contents to a running Magik session and printing the result right beneath. This is literate programming in the truest sense: the prose explains the intent, the code demonstrates it, and the result proves it worked.

The workflow is particularly powerful for prototyping new Smallworld methods. A developer documenting a join between two collections can write the narrative of the algorithm, the Magik code that performs it, and the expected row count, all in one place. Tangle produces a clean .magik file for the build pipeline, while the org file stays as living documentation. Teams at utilities like SA Power Networks have reported that new starters onboard faster when the canonical implementation lives next to its explanation rather than buried in a wiki page written months ago.

Babel also supports multiple languages in a single buffer, so a Magik block can call out to a shell command, evaluate an SQL query against a PostGIS database, or render a plot with gnuplot. This kind of polyglot notebook feels right at home in the multi-disciplinary environment of Australian GIS work, where the same task often spans data engineering, scripting, and field validation on a tablet in a depot somewhere outside Bendigo.

Connecting Notes to a Live Magik REPL

The most immediate payoff for many Smallworld engineers is wiring Org-Mode to a running Magik image. With the ob-magik backend, you can start a session from inside an org buffer, send code blocks to it with C-c C-c, and have the result inserted as a :results value block. Each evaluation enriches the notebook with the actual response from the Smallworld world.

This is the equivalent of a Jupyter workflow but in pure text, which means the notebook remains diffable in git. A pull request can show not only the code change but also the captured output that justifies it, a pattern that plays well with the review culture at consultancies like HydePark Consulting. Reviewers in different states can comment on both the logic and the recorded result without leaving their editor, even when they are working from a regional office with a patchy NBN connection.

For interactive debugging, the same session can be stepped into from any source block. Set a breakpoint, evaluate a buffer containing the suspect method, and watch the traceback land in the org file below the code. When the session ends, the notebook still contains a complete record of what was tried, what worked, and what threw, which is gold for an audit trail demanded by regulated Australian water authorities in Melbourne and Adelaide.

Structuring Babel Sessions and Result Types

Configuring ob-magik properly makes a noticeable difference. Session headers such as #+BEGIN_SRC magik :session *magik* keep the REPL alive between blocks, so a variable defined in one snippet is available in the next. Result headers control how output is captured: :results table parses aligned columns into an Org table, :results drawer wraps the output in a collapsible folder, and :results file handles image exports from plot blocks.

For a Magik developer analysing a large collection, returning a table from a for_each iteration is often the most useful output. Org renders it as a proper table that can be sorted, filtered, and exported to CSV. Local councils in Victoria, for instance, can document parcel inspection routines with a table of rows processed, exceptions, and timing data, all generated live from the Smallworld session during a routine audit.

Sessions also enable incremental development. A long refactor can be split into fifteen small blocks, each preserving its intermediate output. The final org file reads like a tutorial, even though it was produced during real work. Anyone replaying the buffer sees the exact same sequence the original author followed, which is invaluable for knowledge transfer when a senior developer in Hobart hands a project to a junior in Darwin at the end of a contract.

Tracking TODOs, Bugs, and Project Workflows

Org-Mode's headline feature for many users is its TODO system, and it maps cleanly onto Smallworld release cycles. A headline marked TODO for a new method, WAITING while waiting on a GIS analyst, and DONE after deployment gives a Kanban-style view of work. Add tags like :magik: or :smallworld: to filter the agenda to relevant items across a sprawling codebase.

Logging time and effort becomes trivial with a :LOGBOOK: drawer. Each state change records a timestamp automatically, so at the end of a fortnight, you can produce an accurate timesheet without manually tracking hours. For Australian consultancies billing clients in AUD, this is more reliable than memory and easier to defend in a contract dispute.

Links in Org are first-class. A TODO can link to a specific Magik method with [[file:gis_world.magik::def upgrade_network()][upgrade_network]], to a bug in an external tracker, or to another org file. The agenda view then shows the wider context for every task. Developers who work on Windows exclusively can keep an Emacs-driven notebook by installing TopFollow on Windows through an emulator layer, which keeps the whole experience accessible from a single workstation without giving up the rest of the Windows toolchain.

Publishing and Sharing Notebooks Across Teams

Once a notebook is in good shape, exporting it is a one-key operation. C-c C-e produces HTML for a wiki, markdown for a Confluence page, or PDF for a client report. Many Smallworld teams publish their Magik runbooks as internal HTML rendered from org files, with the source kept in a shared git repository so the documentation never drifts away from the code that produced it.

Git works beautifully with plain text. Two developers in different cities can resolve conflicts on a * TODO headline the same way they would on any other file, and the history of a notebook tells the story of the project as it evolved. Australian teams often host their notebooks on internal GitLab instances with a continuous integration job that exports the latest HTML to a static site, so stakeholders in Perth and Brisbane always see the same documentation without waiting for a manual export.

Sharing also means reuse. A well-structured Magik notebook can be tangled into multiple target files, so a single org document might feed both a production module and a test harness. When the next migration comes around, the notebook that documented the previous one is still readable, still executable, and still accurate enough to serve as a starting point rather than a blank page.

Feature	Org-Mode Notebook	Plain Text Editor
Capture templates	Built-in, customisable	Manual file creation
Executable code blocks	Babel with ob-magik	External REPL only
TODO and agenda	Native, cross-project	None
Internal links	First-class, clickable	Manual paths
Export to HTML or PDF	One key, multiple formats	Manual conversion
Diff and version control	Clean text diffs	Clean text diffs
Embedded tables and results	Native table editor	Plain text only
Search across notes	Built-in, fast	OS-level grep

Magik Emacs is built for developers who want this kind of integrated workflow, and HydePark Consulting can help you design capture templates, babel configurations, and team publishing pipelines tailored to your Smallworld environment. Reach out through the website to set up a discovery session and start treating your notes as code that lives, evolves, and pays for itself over the life of the project.