saktumiva2-editor

Saktumiva editor

New to Saktumiva, TEI or GitHub? Start with the tutorial.

A local editing screen for critical editions in TEI, collated with Charles Li’s Saktumiva v.2. Saktumiva’s own collation code runs in the background; your decisions are written straight back into the TEI files. Everything runs on your own computer. The only outside traffic is your browser fetching manuscript images from the archives’ IIIF servers, and “Check for updates” asking GitHub for the latest release.

It was written for the Suśrutasaṃhitā and works for any project laid out as folders of TEI files, for example the Rasendramaṅgala.

Install

Ready-made program (no Python needed): download the file for your computer from the latest release, unzip it and run saktumiva-editor (saktumiva-editor.exe on Windows). A terminal window opens, and the editor opens in your web browser. Close the terminal window, or press Ctrl+C in it, to stop.

• macOS: the program is not signed by Apple. The first time, right-click it and choose Open, or run xattr -d com.apple.quarantine saktumiva-editor in a terminal. It is built for Apple silicon (M1 and later); on an Intel Mac, install it with Python (below).
• Windows: SmartScreen may warn about an unknown publisher: choose More info → Run anyway.

With Python (3.10 or later; for Intel Macs, or if you prefer), in its own virtual environment:

python3 -m venv ~/saktumiva-editor-env
~/saktumiva-editor-env/bin/pip install git+https://github.com/sushrutaproject/saktumiva2-editor.git

Then run ~/saktumiva-editor-env/bin/saktumiva-editor in a terminal.

Updating: Help → Check for updates in the editor (or saktumiva-editor --check-updates) tells you whether there is a newer release and gives the command or download link for the way you installed it.

Start

saktumiva-editor                      # choose a project; recently used ones are listed
saktumiva-editor ~/git/Rasendramangala      # choose one of the project's sections
saktumiva-editor ~/git/Sushrutasamhita_Saktumiva2/03-su.sa   # edit that section straight away

Options: --port 8800 (the next free port is used if it is taken), --no-browser, --version. The Projects button in the editor goes back to the chooser.

Projects and sections

A section is one folder with an edition file and the witness transcriptions collated with it. The files are TEI XML; their names may end in .xml, .txt or .tei (the editor looks inside to see whether a file is TEI). A project is a folder of sections, for example a git repository with one folder per chapter. Without further instructions, any folder (the project folder itself, or one level below it) with an editor.config.json, a saktumiva.config.json or at least two TEI files is offered as a section.

The first time you open a section, the editor proposes which file is the edition (a name containing “edition”) and which are the witnesses (the other TEI files; files that already contain a Saktumiva apparatus are taken to be published output, not witnesses). Check the proposal, change it if needed, and it is saved as editor.config.json in the section folder:

• edition: the working edition, the master text you edit (in the editor or in another XML editor).
• witnesses: the manuscript and printed-edition files. Corrections made in the editor are saved there.
• publishTo: the file Publish writes: the edition with a fresh apparatus (default <edition>_with-apparatus.xml).
• alignmentsDir (alignments), settingsFrom (an alignment file whose collation settings are used), collation, apparatus, extraIgnoreTags, scriptNoteRules: see Settings below.
• publishStylesheet / publishPolyfill: the <?xml-stylesheet?> and the XSLT polyfill script put at the top of the published file (both are used only if the section has an edition.xsl).
• idPrefix: the part of the passage ids left out in the passage list (by default the first part they all share, e.g. SS. or ch1.).

A project may have a saktumiva-project.json in its top folder. Every key is optional:

{
  "name": "Rasendramaṅgala",
  "sections": ["chapter*", "commentary"],
  "fileExtensions": [".xml", ".txt"],
  "editionPattern": "provisional[-_]edition",
  "defaults": {"extraIgnoreTags": ["trailer"], "apparatus": {"normlem": true, "mergerdgs": true}}
}

sections lists the section folders (patterns allowed); editionPattern is a regular expression for recognising the edition file; defaults are settings for every section, which a section’s own editor.config.json can override.

If the section is in a git repository, every save and every Publish is a git commit. Nothing goes online until you push. Work cycle: edit → Publish → check the published file → git push.

What it does

• Passage list (left): every lg, p and l with an xml:id. A dot marks unsaved changes.
• Text (centre): the passage as it stands in the edition file. Underlined words have variants. Click one to find its apparatus entry.
• Several passages at once: Shift-click a passage in the list to show the range from the one clicked last, Ctrl-click (⌘-click on a Mac) to add or remove one; Show several above the list gives each passage a tick box for the same. The passages are shown in document order, each under its xml:id, as continuous text; the apparatus, the notes and the witnesses’ texts are grouped under each passage’s id. Passages that must be collated are collated in the background, each showing its progress, and appear as each is ready. use / omit and editing an existing note work here too; for everything else (Edit text, TEI source, Add note, Correct alignment, a witness’s edit) click a passage’s id to open it alone, or press Show one passage (or Esc). A plain click in the list shows one passage as before. The choice is remembered for the browser session.
• Merge and split passages: with several passages shown that follow one another, Merge… makes one passage of them under the xml:id of the first, in the edition and in every witness file (only the tags between them are removed). Split…, with one passage shown, divides it in two: click in the edition’s text where the second passage begins; each witness is marked at the matching place, going by the alignment, for you to check and move; then give the two parts their ids. Notes follow their passage. Both are saved straight away to all the files as one git commit (save your other changes first), each file’s text is checked to be letter for letter what it was, and the passages are collated afresh. Ctrl+Z does not undo them: revert the commit in git.
• Apparatus: built by Saktumiva for this passage, from the alignment settings of your existing alignment files. Point at a reading and press use to put it in the text; the passage is collated again and the old lemma becomes a variant.
• Edit text: type in the verse lines. Grey boxes are markup (caesura, anchors, page breaks); they are protected but can be deleted. Tick “Record as emendation” to add an Emendation note. TEI source edits the passage as XML for anything else.
• Notes: select a word, press “Add note here”. The <anchor> and the <standOff> note are created together with matching ids (SS.3.1.4-n1, -n2 …). Edit or delete notes in the Notes panel.
• Correct alignment (button above the apparatus, or key A): shows how the witnesses are lined up, one column per apparatus entry. join merges a column with the next; click between two syllables of the edition row to split a column; ‹ › move one witness’s syllable into the neighbouring column. The apparatus follows as you work. Saving writes alignments/<passage>.xml (marked in its header as corrected by hand) with a git commit, and the editor uses that file from then on. No witness’s text can be changed here, and every column keeps some text of the edition.
• Layout: the ☰ button at the far left (or the [ key) hides and shows the passage list, the ☰ button at the far right (or ]) the witnesses; A− A A+ above the text (or Ctrl+−, Ctrl+0, Ctrl++) change its size. These choices are remembered.
• Witnesses (right): each witness’s text of the passage, with a button that opens the page image, and edit, which corrects the witness’s own transcription of the passage (as TEI). That is saved at once to the witness file, with a git commit, and the passage is collated again. Drag a witness by its handle (⠿) to reorder the list; the order is remembered. Witnesses that lack the passage are listed last. With several passages shown, each witness gives its text of each of them.
• Data export (top bar) → NEXUS for SplitsTree…: a character matrix of the aligned readings of the section (or one passage), as Saktumiva’s matrix editor exports it, to open in SplitsTree. Options: the witnesses, Kac or Kpc for corrected witnesses, normalized spellings, one character per word group, gaps significant; alignments brought up to date first, or the saved files as they are. The NeXML that SplitsTree saves can go into the teiHeader for the Stemma button.
• Stemma (top bar, shown only if the edition has one): draws the <stemma format="nexml"> of the edition’s teiHeader (in <xenoData>, as SplitsTree6 or Saktumiva write it) as a stemma codicum, sigla at the leaves. Branch lengths in proportion (with a scale bar) or one step per generation; straight or right-angled lines; a list when there are several stemmata or trees; Download SVG saves the drawing. Pointing at a branch gives its length, at a siglum the witness. A stemma inside an XML comment is not read (the dialog says so).
• Publish (top bar): writes the edition with the full apparatus to a separate file, by default <edition>_with-apparatus.xml in the section folder (set "publishTo" in editor.config.json to change it). It is your edition file exactly as written, plus the stylesheet header, the witnesses in <listWit> and, after </text>, one <standOff type="apparatus"> per passage, made by Saktumiva’s own code exactly as its command-line apparatus tool does. Corrected alignments are used as they are; the rest are collated if needed (slow the first time for long prose passages; cached afterwards). Alignment files are brought up to date and everything is one git commit. Passages without an apparatus are listed at the end.
• Settings (top bar): the collation and apparatus parameters, stored in editor.config.json.
  • Variants to leave out of the apparatus: Saktumiva’s normalizations (final nasals, visarga sandhi, b/v, gemination …). Readings that differ only in these ways become “minor” readings under the lemma. Turning one on works at once, even for existing alignment files; turning off one that an alignment was made with means that passage is collated again.
  • Letters treated as the same in all witnesses, e.g. ś=s, ṇ=n.
  • Witnesses’ own script notes: the <scriptNote xml:id="…"> entries in each witness’s <scriptDesc> apply to that witness only. script-X-Y (script-ba-va, script-śa-sa, script-na-ṇa …) makes X and Y the same letter; svarna-nasals (or savarna-nasals) treats anusvāra and the nasal of the same class, and final m and ṃ, as the same. Other notes can be given a rule in editor.config.json, e.g. "scriptNoteRules": {"script-ya-ja": "y=j"}. The Settings screen lists what it found in each witness.
  • Apparatus: normalized readings, merge groups, separate note for long omissions, show minor readings.
  • XML elements: which elements are left out of the collation with their contents (Saktumiva’s “Ignore <…>” options). Saktumiva’s defaults are listed first, then every other element found inside <text> in your files, with counts; anything else can be typed in.
  • Alignment: tokenization, scoring, distance function. Changing these means passages are collated again (for the whole Śārīrasthāna of the Suśrutasaṃhitā, about 5 minutes), except those you corrected by hand. Applying settings reloads the editor; save your changes first.
• Save (Ctrl+S) writes only the passages and notes you changed, keeps the file’s own formatting elsewhere, writes the passage’s alignment file to alignments/, and makes a git commit listing your edits. Undo (Ctrl+Z) works until you save; after that, use git (History button).

Safety checks on every save: the file must not have been changed on disk meanwhile (e.g. in Oxygen), the result must be well-formed XML, and xml:ids must stay unique. New notes that point nowhere are reported before saving.

Not yet possible

• Splitting or merging passages (new xml:ids).
• Carrying hand corrections of an alignment over when the passage’s text later changes: the editor then warns you, collates afresh, and asks before replacing the corrected file (the old one stays in git).
• Devanāgarī display.

Where the editor keeps its own files

Recent projects and computed alignments (so that each passage is collated only once) are kept outside your projects: on Linux in ~/.config/saktumiva-editor and ~/.cache/saktumiva-editor, on macOS in ~/Library/Application Support/saktumiva-editor and ~/Library/Caches/saktumiva-editor, on Windows in %APPDATA%\saktumiva-editor and %LOCALAPPDATA%\saktumiva-editor\Cache. The cache is safe to delete.

Development

git clone --recurse-submodules https://github.com/sushrutaproject/saktumiva2-editor.git
cd saktumiva-editor
python -m pip install -e ".[test]"
saktumiva-editor

• src/saktumiva_editor/server.py: the local server (Python standard library only); cli.py, project.py (sections, configuration, recent projects), updates.py (GitHub Releases).
• src/saktumiva_editor/app/: the editing screen (index.html, main.mjs …) and the project chooser (chooser.*). multi.mjs chooses several passages from clicks in the list. restructure.mjs merges and splits passages in one file’s text. nexus.mjs makes the NEXUS matrix from alignment files; stemma.mjs reads and draws the stemmata; it needs no other file and returns plain SVG, so it can be used on a web page as well.
• src/saktumiva_editor/app/saktumiva/: Saktumiva, as a git submodule pinned to one commit of chchch/saktumiva. Only its lib/ and the OpenSeadragon image viewer are served and packaged.
• src/saktumiva_editor/saktumiva-patches.json: the one change the editor needs in Saktumiva’s code (a hook in lib/apparatus.mjs through which the editor applies per-witness script notes and the extra “same letters” when deciding whether a reading agrees with the lemma). It is applied in memory as the file is served, so the submodule stays a clean copy of upstream.

Tests

python -m pytest                     # the server, configuration, update check
cd tests/js && npm ci && npm test   # the collation regression tests (Node 22)

The browser tests (tests/python/test_browser_several.py: choosing several passages, the combined apparatus, going back to one passage; test_browser_restructure.py: merging and splitting passages, down to the files on disk) run with Playwright and are skipped without it: python -m pip install -e ".[test,browser]" && python -m playwright install chromium (an installed Google Chrome is used if Playwright’s own Chromium is missing).

The regression tests run the editor’s collation and apparatus code, with the pinned Saktumiva, on real sections (tests/fixtures: the Suśrutasaṃhitā Śārīrasthāna and Rasendramaṅgala chapter 1) and compare the alignments, apparatus and published <standOff> with the stored results in tests/golden. stemma.test.mjs tests the Stemma view on the NeXML of SplitsTree6, Saktumiva and Bio::Phylo (tests/fixtures/stemma and the Rasendramaṅgala fixture); nexus.test.mjs the NEXUS export (tests/fixtures/nexus), multi.test.mjs choosing several passages (app/multi.mjs), restructure.test.mjs merging and splitting passages (app/restructure.mjs). They also check that the patch still fits and still matters (switching script notes off must change the apparatus of certain passages).

Updating Saktumiva

Dependabot proposes a pull request when Saktumiva has new commits; the tests run on it.

• Tests pass: nothing the editor uses has changed in effect. Merge.
• Tests fail: look at what changed. If the patch no longer fits, update find in saktumiva-patches.json (or drop the patch if Saktumiva now offers the hook itself). If the apparatus has changed and the change is an improvement, run npm run update-golden in tests/js, review git diff tests/golden, and commit.

By hand: cd src/saktumiva_editor/app/saktumiva && git fetch && git checkout <commit>, run the tests, commit.

Releasing

1. Set __version__ in src/saktumiva_editor/__init__.py and add a section to CHANGELOG.md.
2. Commit, then git tag v0.2.0 && git push --follow-tags.

.github/workflows/release.yml then builds the wheel and the programs for Linux, macOS and Windows, checks that each one starts, and publishes them as a GitHub Release, where Check for updates finds them.

Licence

The Saktumiva editor is free software under the GNU General Public License, version 3 (see LICENSE). Saktumiva itself is a separate project with its own terms.

Credits

Saktumiva is by Charles Li (github.com/chchch/saktumiva); it does the collation and makes the apparatus. The test fixtures come from the projects named in tests/fixtures/README.md; the Rasendramaṅgala transcriptions are licensed CC BY-SA 4.0.

This site is open source. Improve this page.