Maintaining the CAL SNOBOL examples
==================================

The page reads examples/index.json, then fetches the selected .sno file.
A static web browser cannot enumerate a directory, so regenerate the index
when adding, removing or renaming examples:

    python3 update_examples.py

Run that command beside index.html, or pass the examples directory explicitly:

    python3 path/to/update_examples.py path/to/examples

Upload the examples directory, including its new index.json. No engine build
or page-code edit is required. Edits to an existing .sno are fetched when it
is next selected; regenerate the index too if its title/description changes.

Filenames may contain ASCII letters, digits, hyphens and underscores and must
end in .sno. Titles default to filenames with hyphens/underscores replaced by
spaces. Optional source comments provide metadata, for example:

* @title: A small pattern example
* @description: Replace CAT with DOG.
* @versions: original,revised
     TEXT = 'THE CAT SAT'
     TEXT 'CAT' = 'DOG'
     OUTPUT = TEXT
END

Metadata comments are still source cards: use supported ASCII characters,
keep them within 80 columns, and keep executable source within columns 1-72.
Use a sidecar JSON file for long descriptions or Unicode titles.

A matching .json sidecar is optional, for example pattern.json:

{
  "label": "Pattern replacement",
  "description": "Replace one word in a string.",
  "versions": ["original", "revised"],
  "order": 0,
  "input": "",
  "interactive": false,
  "mounts": []
}

Sidecar metadata overrides source-comment metadata. "title" takes precedence
above "label". Default order is 100, then alphabetical by title; the bundled
pattern example has order 0. Missing versions defaults to both. Version
metadata is advisory: choosing an example never switches implementations or
prevents trying it on the other one.

For named files, mounts uses entries such as:
  {"name":"WORDS","text":"ALPHA\nBETA\n"}
  {"name":"RESULT","write":true}
The bundled files.json demonstrates this. Interactive examples use
"interactive": true, with optional initial "input" text.

Choosing an example replaces the editor and its initial-input/file settings,
but first checkpoints the previous nonempty draft. Changing implementation
alone never replaces your program. Draft recovery remains best effort and
local to a browser/site address: keep your own .sno files as the master copies.

PROTOTYPE belongs to the revised implementation, not the earlier one. Include
END for examples intended for both versions; the earlier compiler can compile
without END but reports a lexical end-of-program error if execution falls off
the end. CLOCK/TIME bindings also differ: see the page's execution notes.