Documenting Magik examples with Org-Babel

Emacs’ Org-Babel for documenting Magik code examples turns an ordinary source block into a document that can explain intent, show output and optionally execute the code. For Smallworld developers, that combination is valuable because a Magik method often depends on domain objects, collection state and an environment that prose alone cannot make clear.

Org separates narrative from executable source without forcing the two apart. A notebook can place a method beside its business purpose, expected result, known limitations and links to the real repository. Readers can scan the explanation, while maintainers retain one versionable source for the example.

The important distinction is that Org-Babel does not make Smallworld run by itself. Execution requires a Magik-aware backend that can reach the appropriate Smallworld environment; without one, the same block remains a structured documentation artefact. This makes documentation-first adoption practical and lets teams postpone risky evaluation plumbing.

Australian teams gain from a portable notebook format. Examples can use Australian English, DD/MM/YYYY dates, AUD values and familiar place names while remaining valid in the wider Smallworld market. That matters for distributed support organisations working between Sydney, Melbourne, Brisbane and Perth, especially when daylight-saving changes complicate incident timelines.

Why Org-Babel suits Magik teams

A Magik example often has two audiences: the developer who needs to run it and the support engineer who needs to understand what it touches. Org-Babel keeps those needs together. The method remains visible as Magik, while the surrounding paragraphs record assumptions, permissions and expected Smallworld state.

Teams should treat the notebook as source-controlled documentation rather than a slide deck. A Git diff can reveal an altered example, an obsolete explanation or a newly authorised production call. Before building a custom evaluator, check the Emacs extensions library for an existing Magik integration and confirm which Smallworld transport and result formats it supports.

Register Magik as a source language

If your Emacs setup already provides magik-mode, register it with Org so source blocks receive the correct editing behaviour. This editing-side integration does not execute Smallworld code:

(require 'org)
(require 'org-babel)

(add-to-list 'org-babel-language-functions
             '("magik" . magik-mode))

Execution needs a separate backend definition. The following template shows the expected registration points; the functions named in it must be implemented in magik-babel.el or provided by a suitable extension.

(org-babel-define-language "magik"
  (org-babel-lang-funcs
   (org-babel-magik-eval
    (file "magik-babel.el")
    "Evaluate a Magik block."
    '(skeleton))
   (org-babel-magik-process-results
    (file "magik-babel.el")
    "Format a Magik evaluation result."
    '(scalar))))

The evaluator must establish a connection, send the Magik body to the correct Smallworld context and return either output or a value. The result processor then gives Org a predictable representation. A backend may also support named sessions, but none should be assumed until its behaviour has been tested against the Smallworld release used by the team.

If evaluation is not yet available, the block can remain documentation-only. Org still recognises the language for folding, copying and export, while :eval never prevents unsupported execution. This is a sound first stage: the team gains a consistent notebook format before any notebook is permitted to change a Smallworld collection.

Structure a documented example

A useful example states what the method does before showing its implementation. This Org fragment is deliberately non-executable and export-safe:

* Return a depot identifier

#+CAPTION: Canonical identifier for a depot object
#+BEGIN_SRC magik :eval never :results none :exports code
method canonical_identifier@depot
  _return _self.identifier
end_method
_
#+END_SRC

#+BEGIN_EXAMPLE
DEPOT-042
#+END_EXAMPLE

Here, :eval never prevents accidental execution, :results none suppresses captured output and :exports code includes the method when the document is published. The separate example block records expected output without pretending that Org verified it. The prose beside the block should identify the object type, required permissions and any read-only assumption.

Keep the snippet complete enough to copy without reconstruction. If a value must be supplied, name its type and example rather than inserting unexplained ellipses. For an Australian deployment, for example, a depot label may combine an internal identifier with a site such as Sydney or Melbourne; that business context belongs in the explanation, not in invented language syntax.

Keep commentary close to the point it explains. A short paragraph can cover why the method exists, while another can describe the example object and the expected side effects. Captions remain concise because they may be reused in exported tables or slides, and the body text supplies the qualifications that a caption cannot.

Keep evaluation out of published examples

Documentation blocks and runnable blocks should have different defaults. Published examples should normally carry :eval never, while an authorised test harness or working copy handles evaluation. A method that can alter a collection, commit a transaction or call an external service should never sit one keystroke away from execution in a shared document.

Use a sandbox with known Smallworld releases, restricted data and a named connection. The backend should display its target before sending code, and sensitive values should come from test fixtures rather than embedded secrets. This separation lets support staff learn a method safely while the same source remains testable in continuous integration.

Capture useful results and failures

The result adapter decides what Babel receives. :results output is suitable for text written by the method, while :results value asks the backend for a returned value. Verbatim mode can preserve a raw transcript, but a domain-aware processor is usually better for collections because it can apply stable field names, ordering and truncation.

Not every result should become a table. A scalar can be displayed as a labelled value, while a multi-field object needs deliberate field selection. The adapter should preserve Magik’s distinctions, such as a missing value versus an empty collection, because collapsing them can make a documented outcome misleading.

Errors need equal care. The processor should retain the Smallworld error type and message while identifying the example that failed. Do not publish credentials, customer names, host names or full stack traces from production. For collection analysis, query the smallest useful set and export selected fields as a compact table; an indiscriminate dump of a live collection is neither reviewable nor safe.

A backend can also translate a collection into CSV-like rows for Org, but the conversion belongs beside the evaluator, not in hand-written prose. That keeps formatting repeatable and lets a reviewer compare the same fields across releases. If the output changes, the diff belongs in the backend and its tests.

Publish and maintain the notebook

Store the notebook beside the code it explains, commit both and review changes as code. Org’s exporter can publish HTML, PDF or another configured format, while :exports code, results or both controls what readers receive. A useful review includes the Magik source, the stated environment and the effect of any result-format change.

Avoid maintaining two copies of an executable method. #+INCLUDE: can display a canonical file as literal Magik, while a file-aware backend or Org’s tangling facilities can extract executable source when supported. If either path is unsuitable, keep the notebook linked to the repository file and state clearly that the rendered snippet is not the execution source.

Timestamps and environment notes deserve the same precision as code. Write dates as DD/MM/YYYY, but include the timezone for operational events. Sydney and Melbourne move between AEST and AEDT, Brisbane remains on AEST and Perth uses AWST, so an incident note copied between teams can otherwise assign the wrong hour.

Make the workflow repeatable

A repeatable notebook template needs only a few deliberate fields: purpose, Smallworld version, connection class, permissions, expected result and evaluation policy. One method per example keeps review manageable. Give each notebook an owner and review it when the method, backend or Smallworld release changes, just as you would review production code.

For Australian organisations operating transport, utility or mining estates, this pattern also reduces handover friction. A shared template can preserve local naming, escalation contacts and data-classification rules while keeping examples portable between consulting teams and internal support groups. HydePark Consulting can use the same structure when documenting client-specific implementations without creating a separate documentation culture for every environment.

Open the Magik Emacs extension catalogue, install the Magik-aware tooling that matches your Smallworld environment, create magik-examples.org, and commit one reviewed example with its source, expected output and evaluation policy. That gives the team an immediately usable reference and a repeatable basis for the rest of the library.