ack/klammertext
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Windows: product names, the editors, WSL; the Linux page's image step

Browse Source 
Assembled from development commit c3c40f6c8fca. Since 830b193: on Windows the
products carry Windows names (ktext.exe, klammertext.dll, document.dll,
reflect.dll) and the console's output code page is UTF-8 for a run; the
editor tooling works on Windows (VS Code, Sublime Text, Vim, with the
interpreter's name chosen by platform) and Notepad++ joins it
(doc/edit/notepadpp: a User Defined Language and two Run-menu commands);
a sixth install page, doc/install/windows_wsl_install.md, for Linux
inside WSL; the Windows page opens with the three routes and gains its
editor section, the PowerShell quoting and Path notes; the Linux page
installs OpenImageIO from the python3-openimageio package and verifies
with kdiag --machine; the README lists all six install pages. Linux and
macOS behaviour is unchanged.
This commit is contained in:
ack committed 2026-09-25 18:43:22 +02:00
1 parent 830b19394d
commit ee8bcf5300
33 files changed
+741 -122
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

doc/edit/README.md
+10 -6
View File
@@ -1,7 +1,7 @@
# Klammertext editor support
Editing support for Klammertext files (`.kt` documents and `.k` klammer
definitions) in four editors, built around one shared implementation.
definitions) in five editors, built around one shared implementation.
| Directory | Contents |
|---|---|
@@ -10,6 +10,7 @@ definitions) in four editors, built around one shared implementation.
| `sublime/` | Sublime Text package. Syntax file plus thin plugin wrappers that import the shared core directly (Sublime's plugin host is Python). |
| `vim/` | Vim plugin. Syntax/ftplugin files plus commands that run the shared core's CLI; with `+python3`, the core also runs in-process (`=` operator, live match highlighting). |
| `vscode/` | Visual Studio Code extension. TextMate grammar plus a dependency-free extension that spawns the language server and speaks LSP to it. |
| `notepadpp/` | Notepad++ (Windows). A User Defined Language for the highlighting, and two Run-menu commands that pass the current file through the shared core's CLI (delimiter check, reindent). No plugin host, so nothing structural runs in-process. |
## The architecture
@@ -41,7 +42,8 @@ document/range formatting (reindentation), documentHighlight and
definition (the matcher), and a `klammertext.alignTable` command. The
VS Code extension is its first client; any LSP client works — Neovim's
built-in LSP, Emacs eglot, Sublime's LSP package — with a one-line
configuration pointing at `python3 klammertext_ls.py`.
configuration pointing at `python3 klammertext_ls.py` (on Windows
`python klammertext_ls.py`).
Syntax highlighting and cursor-latency features stay native in each editor
(a tokenizer or a per-keystroke matcher cannot round-trip to Python), so
@@ -68,10 +70,12 @@ Two kinds of artifact cannot read it and restate parts of it by hand:
defcustoms, checked byte-for-byte against the shared core by
`tst/editor_test.sh`.
2. **The static syntax files** — the literal-klammer set (`@code`) appears
in the Sublime `.sublime-syntax`, the Vim `syntax/klammertext.vim`, and
the VS Code `tmLanguage.json` grammar (and the Emacs defcustom). When
you add a literal klammer, change them together; each file's header
carries the same SYNC note.
in the Sublime `.sublime-syntax`, the Vim `syntax/klammertext.vim`, the
VS Code `tmLanguage.json` grammar, and the Notepad++ `Klammertext.udl.xml`
(and the Emacs defcustom). When you add a literal klammer, change them
together; each file's header carries the same SYNC note. The UDL can
hold only names that are not prefixes of other klammer names (it has
no word boundary), so it carries `code` and not `c`.
## Testing
doc/edit/notepadpp/Klammertext.udl.xml
+114
View File
@@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Klammertext.udl.xml - Notepad++ User Defined Language for Klammertext
(.kt documents and .k klammer definitions). Highlighting only: Notepad++
has no Python plugin host and no built-in language-server client, so the
structural tools of the shared core (doc/edit/shared/klammertext_edit.py)
are reached through Run-menu commands instead; README.md has them.
What it colours, and how (a UDL is a fixed set of token classes, not a
grammar; the choices below are the closest fit):
@@@name, @@@ system commands Keywords1, prefix match, orange
@@name, @@ klammer definitions Keywords2, prefix match, green
@name, @ klammer applications Keywords3, prefix match, blue
The groups are checked in order, longest run first,
so @@name is not taken for an @ followed by a name.
A named close (name@) is coloured only at its @.
^X ^UUUU^ ^' escapes Keywords4, prefix match, the
default colour: consumed so the character after the
caret is never read as a delimiter, shown as text
(as the Emacs mode does).
# ... removal to end of line line comment, grey; only
when the # is the first thing on its line
(forcePureLC), because a UDL comment cannot tell
"# comment" from the whitespace operators #- #+ #/,
which would otherwise grey the rest of their line.
#[ ... ]# removal of a region block comment, grey, folds.
## #- #+ #/ the other # forms Operators2, marker red.
| : bars and option marks Operators1, marker red.
@code ... code@ verbatim interior Delimiters1, muted, nothing
inside it is coloured. The other literal klammer,
@c ... c@, is NOT here: a UDL delimiter has no word
boundary, so "@c" would also open at @caption,
@cond and every other c-klammer.
SYNC: the literal-klammer set's source of truth is LITERAL_KLAMMERS in
doc/edit/shared/klammertext_edit.py. When a klammer is added there, add
"@NAME" / "NAME@" as a further delimiter pair here (pairs 2 to 8 are free:
items 03/05, 06/08, ... in the "Delimiters" list) - if its name is not a
prefix of other klammer names.
Colours are the palette's light-ground values (notes/klammertext_palette.md:
application 528599, definition 758B55, system 996743, markers 994040,
removed text 9A9A9A); colorStyle="1" keeps every background transparent, so
a dark Notepad++ theme keeps its own ground (the hues still read there).
Install: copy this file into %AppData%\Notepad++\userDefineLangs\ and
restart Notepad++ (or Language > User Defined Language > Define your
language... > Import...). README.md has the details and the Run commands.
-->
<NotepadPlus>
<UserLang name="Klammertext" ext="kt k" udlVersion="2.1">
<Settings>
<Global caseIgnored="no" allowFoldOfComments="yes" foldCompact="no" forcePureLC="1" decimalSeparator="0" />
<Prefix Keywords1="yes" Keywords2="yes" Keywords3="yes" Keywords4="yes" Keywords5="no" Keywords6="no" Keywords7="no" Keywords8="no" />
</Settings>
<KeywordLists>
<Keywords name="Comments">00# 01 02 03#[ 04]#</Keywords>
<Keywords name="Numbers, prefix1"></Keywords>
<Keywords name="Numbers, prefix2"></Keywords>
<Keywords name="Numbers, extras1"></Keywords>
<Keywords name="Numbers, extras2"></Keywords>
<Keywords name="Numbers, suffix1"></Keywords>
<Keywords name="Numbers, suffix2"></Keywords>
<Keywords name="Numbers, range"></Keywords>
<Keywords name="Operators1">| :</Keywords>
<Keywords name="Operators2">## #- #+ #/</Keywords>
<Keywords name="Folders in code1, open"></Keywords>
<Keywords name="Folders in code1, middle"></Keywords>
<Keywords name="Folders in code1, close"></Keywords>
<Keywords name="Folders in code2, open"></Keywords>
<Keywords name="Folders in code2, middle"></Keywords>
<Keywords name="Folders in code2, close"></Keywords>
<Keywords name="Folders in comment, open">#[</Keywords>
<Keywords name="Folders in comment, middle"></Keywords>
<Keywords name="Folders in comment, close">]#</Keywords>
<Keywords name="Keywords1">@@@</Keywords>
<Keywords name="Keywords2">@@</Keywords>
<Keywords name="Keywords3">@</Keywords>
<Keywords name="Keywords4">^</Keywords>
<Keywords name="Keywords5"></Keywords>
<Keywords name="Keywords6"></Keywords>
<Keywords name="Keywords7"></Keywords>
<Keywords name="Keywords8"></Keywords>
<Keywords name="Delimiters">00@code 01 02code@ 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23</Keywords>
</KeywordLists>
<Styles>
<WordsStyle name="DEFAULT" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="COMMENTS" fgColor="9A9A9A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="LINE COMMENTS" fgColor="9A9A9A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="NUMBERS" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="KEYWORDS1" fgColor="996743" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
<WordsStyle name="KEYWORDS2" fgColor="758B55" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
<WordsStyle name="KEYWORDS3" fgColor="528599" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="1" nesting="0" />
<WordsStyle name="KEYWORDS4" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="KEYWORDS5" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="KEYWORDS6" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="KEYWORDS7" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="KEYWORDS8" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="OPERATORS" fgColor="994040" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="FOLDER IN CODE1" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="FOLDER IN CODE2" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="FOLDER IN COMMENT" fgColor="994040" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS1" fgColor="5A5A5A" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS2" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS3" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS4" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS5" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS6" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS7" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
<WordsStyle name="DELIMITERS8" fgColor="000000" bgColor="FFFFFF" colorStyle="1" fontName="" fontStyle="0" nesting="0" />
</Styles>
</UserLang>
</NotepadPlus>
doc/edit/notepadpp/README.md
+114
View File
@@ -0,0 +1,114 @@
# Klammertext support for Notepad++
Notepad++ support for editing Klammertext files (`.kt` documents and `.k`
klammer definitions): syntax highlighting through a **User Defined
Language**, and the shared editor core's delimiter check and
reindentation through two **Run-menu commands**. Notepad++ is Windows
only, and so is this package.
Notepad++ has no Python plugin host and no built-in language-server
client, so it cannot import the shared core the way Sublime Text does or
talk to the language server the way VS Code does. What it has is a
declarative highlighter and a Run menu that can invoke any program on the
current file, and this package uses exactly those two things.
## Files
| File | Purpose |
|---|---|
| `Klammertext.udl.xml` | The User Defined Language: highlighting for the three `@`-tiers, escapes, text removal, and the `@code` verbatim interior. Its header lists what it colours and the limits of a UDL. |
| `klammertext_edit.py` | The shared editor core (in the editing zip it sits here; in the Klammertext repository it is `doc\edit\shared\klammertext_edit.py`). The Run commands call it. |
| `README.md` | This file. |
## Requirements
- Notepad++ 7.9 or later (the `userDefineLangs` folder; any recent
version qualifies).
- For the Run commands: `python` on the `Path`, which the Klammertext
installation already needs.
## Install the highlighting
Copy `Klammertext.udl.xml` into Notepad++'s user-defined-language folder
and restart Notepad++:
```powershell
$d = "$env:AppData\Notepad++\userDefineLangs"
New-Item -ItemType Directory -Force $d | Out-Null
Copy-Item Klammertext.udl.xml $d
```
Notepad++ loads every file in that folder at start. `.kt` and `.k` files
then open as "Klammertext" (the language shows in the status bar and at
the bottom of the **Language** menu). The alternative is the dialog:
**Language ￫ User Defined Language ￫ Define your language… ￫ Import…**,
which copies the file to the same place.
What you see: klammer applications (`@name … @`) in blue, definitions
(`@@name … @@`) in green, system commands (`@@@name … @@@`) in orange;
a `#` at the start of a line greys the rest of the line, `#[ … ]#` greys
and folds a region; `##`, `#-`, `#+`, `#/`, `|` and `:` in the marker
red; the interior of `@code … code@` muted and uninterpreted. The
colours are the palette's light-ground values with transparent
backgrounds, so a dark theme keeps its own ground.
Two limits, both properties of a UDL rather than of Klammertext, are
documented in the file's header: a `#` that is not the first thing on
its line is not treated as a comment (so that the whitespace operators
`#-`, `#+`, `#/` never grey the rest of their line), and `@c … c@` is not
made verbatim (a UDL delimiter has no word boundary, so `@c` would also
open at `@caption` and `@cond`).
## The Run commands
The shared core's command-line interface reads a file on standard input
and writes the result on standard output; Notepad++'s **Run ￫ Run…**
dialog (`F5`) runs a command line with the current file's path filled in
as `$(FULL_CURRENT_PATH)`. Two commands cover the structural tools.
Replace `C:\Users\<you>\klammertext\doc\edit\shared` with the folder that
holds `klammertext_edit.py` (with the editing zip, the folder this
README is in).
**Check the delimiters** — lists every unclosed opening, extra close,
name or tier mismatch, and unclosed literal span or `#[` block, as
`line:column: message`; an empty window means the file is balanced.
The `/k` keeps the window open to read:
```
cmd /k python "C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py" check < "$(FULL_CURRENT_PATH)"
```
**Reindent the file** — rewrites the file with the canonical
indentation (2 spaces per nesting level, bars and closes at their
opener's column, `@document` transparent, verbatim and removed text
untouched):
```
cmd /c python "C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py" indent < "$(FULL_CURRENT_PATH)" > "$(FULL_CURRENT_PATH).tmp" && move /y "$(FULL_CURRENT_PATH).tmp" "$(FULL_CURRENT_PATH)"
```
Paste each line into the Run dialog once, press **Save…**, give it a
name ("Klammertext check", "Klammertext reindent") and a shortcut
(`Ctrl+Alt+K`, `Ctrl+Alt+I` are free); they then appear at the bottom of
the **Run** menu with those keys.
Two things to know about the reindent command. It works on the file
**on disk**, so save first (`Ctrl+S`); Notepad++ does not save before
running. And after it runs, Notepad++ notices the changed file: with the
default setting it asks whether to reload, which you answer Yes; under
**Settings ￫ Preferences ￫ MISC. ￫ File Status Auto-Detection** the
choice "Update silently" makes the reload automatic. Undo history is
lost on a reload, as for any external edit.
Table alignment and jump-to-match need a caret position the Run dialog
cannot pass, so they are not offered here. They are available in every
other supported editor, and for Notepad++ through the PythonScript
plugin, which embeds a Python that can import the shared core and reach
the caret; a script for it is a possible addition, not part of this
package.
## Keeping things in sync
The UDL restates the literal-klammer set (`@code`) that the shared core
owns in `LITERAL_KLAMMERS`; its header says how to add one. The editor
support's overview is `doc/edit/README.md` in the Klammertext repository.
doc/edit/shared/klammertext_edit.py
+11 -1
View File
@@ -56,7 +56,10 @@ import sys
# --- policy ----------------------------------------------------------------
# Klammer names whose content is a literal argument (verbatim interior,
# closed by a named NAME@ delimiter).
# closed by a named NAME@ delimiter). The static syntax artifacts restate
# this set by hand (Emacs defcustom, .sublime-syntax, vim syntax, tmLanguage,
# the Notepad++ UDL -- which can hold only "code"); doc/edit/README.md,
# "Keeping things in sync".
LITERAL_KLAMMERS = set(["code", "c"])
# Klammers that contribute no indentation level (a @document's paragraphs
@@ -1037,6 +1040,13 @@ def _cli(argv):
if len(argv) < 1:
return usage()
mode = argv[0]
# Klammertext writes LF on every system. Python's text-mode stdout turns
# every "\n" into "\r\n" on Windows, and an editor -- or the test suite --
# comparing the result with an LF buffer then sees every line changed.
# stdin keeps universal newlines: a CRLF buffer arrives as "\n" lines,
# which is what the algorithms expect.
if hasattr(sys.stdout, 'reconfigure'): # 3.7+; the floor is 3.8
sys.stdout.reconfigure(newline='\n')
s = sys.stdin.read()
if mode == 'indent':
doc/edit/sublime/README.md
+2 -2
View File
@@ -203,8 +203,8 @@ elsewhere) are not part of this package, but they exist: the **Klammertext
language server** (`doc/edit/shared/klammertext_ls.py`, the same program the
VS Code extension uses) serves them to Sublime through the community LSP
package. Install "LSP" from Package Control and add a client with
`command: ["python3", "/path/to/klammertext_ls.py"]` for the
`text.klammertext` selector. Everything in this package works the same
`command: ["python3", "/path/to/klammertext_ls.py"]` (on Windows
`"python"`) for the `text.klammertext` selector. Everything in this package works the same
with or without it.
## Troubleshooting
doc/edit/vim/README.md
+4 -3
View File
@@ -14,7 +14,8 @@ sync.
## Requirements
- Vim 8+ (or Neovim) with `+eval` — any normal Vim; only `vim-tiny` lacks it.
- `python3` on `PATH` (Klammertext itself already requires Python).
- `python3` on `PATH` — on Windows `python`, the name python.org installs
(Klammertext itself already requires Python).
- The shared core, found automatically in this order:
1. `g:klammertext_edit_py`, if you set it (a full path to
`klammertext_edit.py`);
@@ -81,7 +82,7 @@ in-process: the `=` operator reindents through `'indentexpr'` (`==`, `gg=G`),
and the matching delimiter is highlighted live as the cursor sits on one —
the show-paren equivalent, with a mismatched or unbalanced delimiter shown
in red plus a message. Without `+python3` the commands above still work;
they shell out to `python3`.
they shell out to `python3` (on Windows `python`).
**Comment toggling** — `'commentstring'` is set to `# %s`, so Vim 9.1's
built-in commenting and Neovim's `gcc`/`gc` (or the commentary plugin)
@@ -92,7 +93,7 @@ toggle `#` line removal.
| Variable | Meaning (default) |
|---|---|
| `g:klammertext_edit_py` | full path to `klammertext_edit.py` (auto-detected) |
| `g:klammertext_python` | Python interpreter (`python3`) |
| `g:klammertext_python` | Python interpreter (`python3`; on Windows `python`) |
| `g:klammertext_no_mappings` | set to define no default mappings |
## Neovim and the language server
doc/edit/vim/autoload/klammertext.vim
+4 -2
View File
@@ -11,7 +11,8 @@
" Configuration:
" g:klammertext_edit_py full path to klammertext_edit.py (overrides the
" search described below)
" g:klammertext_python the Python interpreter (default "python3")
" g:klammertext_python the Python interpreter (default "python3";
" on Windows "python", the name python.org installs)
" --- locating the shared core ---------------------------------------------
" Search order: an explicit g:klammertext_edit_py; a vendored copy at this
@@ -37,7 +38,8 @@ function! s:EditScript() abort
endfunction
function! s:Python() abort
return exists('g:klammertext_python') ? g:klammertext_python : 'python3'
return exists('g:klammertext_python') ? g:klammertext_python
\ : (has('win32') ? 'python' : 'python3')
endfunction
" Run the core CLI over the whole buffer. ARGS is the argument string
doc/edit/vscode/README.md
+9 -7
View File
@@ -18,8 +18,9 @@ language's structure, everywhere.
- VS Code 1.75 or later — a minimum, not a target: VS Code's monthly
releases count 1.75, 1.76, … (1.75 is from January 2023), so any
version from the last few years qualifies.
- `python3` on `PATH` (or set `klammertext.pythonPath`); Klammertext itself
already requires Python.
- `python3` on `PATH` — on Windows `python`, the name python.org installs
(or set `klammertext.pythonPath`); Klammertext itself already requires
Python.
- The language server, found automatically in this order:
1. the `klammertext.serverPath` setting, if set;
2. `klammertext_ls.py` vendored next to `extension.js` (the layout the
@@ -32,8 +33,9 @@ language's structure, everywhere.
## Install
Package the extension as a `.vsix` and install it (the builder needs only
bash and python3; the editing zip from the Klammertext website ships a
prebuilt `klammertext.vsix`, so there the first step is already done):
bash and Python — on Windows, run it in the MSYS2 shell the Klammertext
build uses; the editing zip from the Klammertext website ships a prebuilt
`klammertext.vsix`, so there the first step is already done):
./make_vsix.sh
code --install-extension klammertext.vsix
@@ -129,7 +131,7 @@ Shortcuts** (`Ctrl+K Ctrl+S`), search "klammertext", and rebind.
## Settings
A normal installation needs neither setting: the extension runs `python3`
from `PATH` and finds the language server automatically (the copy vendored
(on Windows `python`) from `PATH` and finds the language server automatically (the copy vendored
next to `extension.js`, then `../shared/`, then
`$KLAMMERTEXT_HOME/doc/edit/shared/`). They exist for unusual setups.
Set them in the Settings UI (`Ctrl+,`, search "klammertext") or in
@@ -138,10 +140,10 @@ reload the window after changing either.
| Setting | Meaning (default) |
|---|---|
| `klammertext.pythonPath` | Python interpreter for the server (`python3`) |
| `klammertext.pythonPath` | Python interpreter for the server (`python3`; on Windows `python`) |
| `klammertext.serverPath` | full path to `klammertext_ls.py` (auto-located) |
`pythonPath` matters when `python3` is not on the `PATH` VS Code sees — a
`pythonPath` matters when the interpreter is not on the `PATH` VS Code sees — a
VS Code launched from the desktop inherits a different environment than
your shell — or when a specific interpreter is wanted. `serverPath`
matters only when the server file lives outside the search chain above.
doc/edit/vscode/extension.js
+5 -1
View File
@@ -165,7 +165,11 @@ function activate(context) {
'diagnostics, formatting, matching and alignment need the server.');
return;
}
const python = vscode.workspace.getConfiguration('klammertext').get('pythonPath') || 'python3';
// The setting's declared default is empty so that this fallback is what
// decides: python3 everywhere but Windows, where python.org installs
// "python" only (the Klammertext commands there use the same name).
const python = vscode.workspace.getConfiguration('klammertext').get('pythonPath') ||
(process.platform === 'win32' ? 'python' : 'python3');
client = new LspClient(python, [serverPath], log);
client.proc.on('error', (err) => {
vscode.window.showWarningMessage(
doc/edit/vscode/make_vsix.sh
+9 -3
View File
@@ -9,7 +9,7 @@
# code --install-extension klammertext.vsix
#
# A .vsix is a zip holding a two-file manifest plus the extension payload
# under extension/. This script builds it with bash + python3 only — no
# under extension/. This script builds it with bash + Python only — no
# npm, no vsce — matching the extension's no-dependency design. The shared
# core and language server are vendored into the payload: from this folder
# if present (the editing-zip layout), else from ../shared (the repository
@@ -18,6 +18,12 @@
set -e
cd "$(dirname "$0")"
# The interpreter: $PYTHON if the environment names one (env/runtime.env
# does), else python3, else python -- the only name python.org installs on
# Windows, where this runs in the MSYS2 shell.
PYTHON="${PYTHON:-$(command -v python3 || command -v python)}"
[ -n "$PYTHON" ] || { echo "make_vsix.sh: no python3 or python on PATH" >&2; exit 1; }
OUT="$PWD/klammertext.vsix"
STAGE="$(mktemp -d)"
trap 'rm -rf "$STAGE"' EXIT
@@ -36,7 +42,7 @@ for f in klammertext_edit.py klammertext_ls.py; do
fi
done
VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
VERSION=$("$PYTHON" -c "import json; print(json.load(open('package.json'))['version'])")
cat > "$STAGE/[Content_Types].xml" <<'EOF'
<?xml version="1.0" encoding="utf-8"?>
@@ -75,7 +81,7 @@ cat > "$STAGE/extension.vsixmanifest" <<EOF
</PackageManifest>
EOF
python3 - "$STAGE" "$OUT" <<'EOF'
"$PYTHON" - "$STAGE" "$OUT" <<'EOF'
import os, sys, zipfile
stage, out = sys.argv[1], sys.argv[2]
with zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as z:
doc/edit/vscode/package.json
+2 -2
View File
@@ -83,8 +83,8 @@
"properties": {
"klammertext.pythonPath": {
"type": "string",
"default": "python3",
"description": "Python interpreter used to run the Klammertext language server."
"default": "",
"description": "Python interpreter used to run the Klammertext language server. Leave blank for python3 (on Windows: python)."
},
"klammertext.serverPath": {
"type": "string",
doc/install/linux_source_install.md
+13 -7
View File
@@ -7,6 +7,8 @@ including `:haskell` and `:shell` commands that depend on locally installed
software.
For the container installation on Linux, see `linux_container_install.md`.
On Windows, this page also applies unchanged inside the Windows Subsystem
for Linux; `windows_wsl_install.md` says what is specific to WSL.
## Prerequisites
@@ -21,15 +23,19 @@ sudo apt-get install g++ make python3-dev
The C++ compiler must support C++20. GCC 11 or later is required (Ubuntu 22.04
and later include GCC 12+).
The SKS `@image` klammer requires OpenImageIO Python bindings. These must match
the Python version that ktext is built against (check with
`python3.XX -c "import OpenImageIO"`). For example, if ktext links against
Python 3.12:
The SKS `@image` klammer requires the OpenImageIO Python bindings, for the
same Python that ktext is built against (the system `python3`). Ubuntu
packages them:
```bash
pip3.12 install OpenImageIO
sudo apt-get install python3-openimageio
python3 -c "import OpenImageIO"
```
(A `pip` install works too, but a fresh Ubuntu has no `pip` until
`python3-pip` is installed, and since 24.04 it refuses to install into the
system Python without `--break-system-packages`; the package avoids both.)
Verify:
```bash
@@ -284,8 +290,8 @@ ktext -s '@eval 1 + 1 @' -d
# Shell evaluation
ktext -s '@eval :shell date @' -d
# Show machine state (SKS is loaded by default)
ktext -s '' -m
# Show the machine's initial state: targets, argument types, the primitive klammers
kdiag --machine
# HTML and PDF output (uses the hello.kt from the Build section)
ktext hello.kt -t html
doc/install/windows_source_install.md
+88 -13
View File
@@ -13,6 +13,14 @@ The installation uses three things a Windows user installs once:
building; **Python** from python.org, which Klammertext embeds; and **TeX
Live**, for PDF output. Everyday use needs only PowerShell.
This is one of three ways to have Klammertext on Windows. If you are at
home in Linux, the Windows Subsystem for Linux gives you the Linux
installation unchanged, with the Windows editors and browser alongside:
`windows_wsl_install.md`. If you want no build at all, the prebuilt
container images run on Windows through Docker Desktop, which that page
also describes. This page is the native route: Windows programs, no
Linux layer.
## Prerequisites
@@ -119,10 +127,11 @@ optimizing compiler may run out of memory and report `out of memory
allocating`. If so, run `make -C com` without `-j`: slower, and it
finishes.
This builds the library, the Standard Klammer Set's components and the
three commands into `bin\`, and copies the library and the compiler's
runtime DLLs there too, so `bin\` is self-contained. The Python binding is
built into `kpy\`. Verify:
This builds the library (`klammertext.dll`), the Standard Klammer Set's
components and the three commands (`ktext.exe`, `kdesc.exe`, `kdiag.exe`)
into `bin\`, and copies the library and the compiler's runtime DLLs there
too, so `bin\` is self-contained. The Python binding is built into `kpy\`.
Verify:
```bash
ktext -s '@eval 1 + 1 @' -d # prints 2
@@ -221,21 +230,37 @@ ktext hello.kt -t pdf # writes hello.pdf
## Using the commands from PowerShell
Building needs the UCRT64 shell; using Klammertext does not. For everyday
use from PowerShell, put three directories on the `Path` and set
use from PowerShell, put two directories on the `Path` and set
`KLAMMERTEXT_HOME`, once, as user environment variables (Settings ▸
System ▸ About ▸ Advanced system settings ▸ Environment Variables, or with
`setx`):
System ▸ About ▸ Advanced system settings ▸ Environment Variables, or
from PowerShell):
```powershell
setx KLAMMERTEXT_HOME "C:\Users\<you>\klammertext"
setx Path "$env:Path;C:\Users\<you>\klammertext\bin;C:\Users\<you>\external\texlive\2026\bin\windows"
[Environment]::SetEnvironmentVariable("KLAMMERTEXT_HOME", "C:\Users\<you>\klammertext", "User")
$p = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$p;C:\Users\<you>\klammertext\bin;C:\Users\<you>\external\texlive\2026\bin\windows", "User")
```
Python is already on the `Path` from its installer. Open a new PowerShell
(Not `setx Path "$env:Path;…"`: `$env:Path` is the machine and user
values merged, so that copies every machine entry into your user `Path`,
and `setx` silently cuts a value over 1024 characters.) Python is already
on the `Path` from its installer. Open a new PowerShell
window and `ktext`, `kdesc` and `kdiag` work there directly. Paths
Klammertext prints use forward slashes on every system; paths you type may
use either.
One PowerShell rule to know when you pass Klammertext text with `-s`: an
apostrophe inside a single-quoted string ends the string, so `It's` must
be written `It''s` (two apostrophes), or the whole text put in double
quotes. The error you get otherwise mentions a "here-string header",
because PowerShell reads the next `@'` as one; it is PowerShell's message,
not Klammertext's.
```powershell
ktext -s '@i It''s a Pyrrhic victory! @' -d
ktext -s "@i It's a Pyrrhic victory! @" -d
```
## Verifying the installation
@@ -250,12 +275,12 @@ ktext hello.kt -t html # html
ktext hello.kt -t pdf # pdf, requires TeX Live
make -C $KLAMMERTEXT_HOME/tst test # the engine's test suites
make -C $KLAMMERTEXT_HOME/sks/tst test # the Standard Klammer Set's suites (needs TeX Live)
```
A few suite cases report `SKIP` on Windows for things the MSYS2 shell
cannot provide, such as a real terminal for the colour tests or a
symbolic link; that is expected.
symbolic link; that is expected. (The Standard Klammer Set's own suites
are part of the development repository, not of this distribution.)
## Updating
@@ -269,6 +294,56 @@ make -C com -j
```
## Editor support
Klammertext's editor support (`doc\edit\`, one shared implementation
behind VS Code, Sublime Text, Vim and Emacs integrations) works on Windows
with the Python already installed. Each editor's README in `doc\edit\`
has the details; the Windows-specific steps are these.
**Visual Studio Code.** Build the extension package in the UCRT64 shell,
then install it from PowerShell (or from any window where `code` is on the
`Path`):
```bash
cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh
```
```powershell
code --install-extension C:\Users\<you>\klammertext\doc\edit\vscode\klammertext.vsix
```
Reload VS Code. The extension runs `python` from the `Path` and finds the
language server inside the package; nothing needs configuring.
**Sublime Text 4.** Copy the package and the shared core into Sublime's
`Packages` directory (**Preferences ￫ Browse Packages…** opens it):
```powershell
$p = "$env:AppData\Sublime Text\Packages\Klammertext"
New-Item -ItemType Directory -Force $p | Out-Null
Copy-Item C:\Users\<you>\klammertext\doc\edit\sublime\* $p
Copy-Item C:\Users\<you>\klammertext\doc\edit\shared\klammertext_edit.py $p
```
Sublime loads the package live.
**Notepad++.** Highlighting comes from a User Defined Language file, the
delimiter check and reindentation from two Run-menu commands
(`doc\edit\notepadpp\README.md` has both):
```powershell
$d = "$env:AppData\Notepad++\userDefineLangs"
New-Item -ItemType Directory -Force $d | Out-Null
Copy-Item C:\Users\<you>\klammertext\doc\edit\notepadpp\Klammertext.udl.xml $d
```
Restart Notepad++; `.kt` and `.k` files open as Klammertext.
**Vim.** As in `doc\edit\vim\README.md`; the plugin runs the shared core
through `python` on Windows automatically.
## Troubleshooting
**The command window closes at once, or "The code execution cannot proceed
@@ -282,7 +357,7 @@ runtime, which nearly every Windows machine already has but a freshly
installed one may not. Install it from
https://aka.ms/vs/17/release/vc_redist.x64.exe and try the import again.
**"libklammertext.so was not found" or "libstdc++-6.dll was not found".**
**"klammertext.dll was not found" or "libstdc++-6.dll was not found".**
`bin\` is not on the `Path`, or the build did not finish: `make -C com -j`
places the library and the runtime DLLs in `bin\` beside the commands.
doc/install/windows_wsl_install.md
+153
View File
@@ -0,0 +1,153 @@
# Klammertext on Windows through the Windows Subsystem for Linux
This page is for someone who works in Linux by habit and has a Windows
machine to work on. The Windows Subsystem for Linux (WSL 2) runs a real
Linux kernel and an ordinary Ubuntu inside Windows, and Klammertext's
Linux installation applies there unchanged: the same compiler, the same
Python, the same TeX Live, the same `runtime.env`. So this page is short.
It gets you to an Ubuntu prompt, sends you to the Linux page, and then
says what is specific to living in WSL: where files belong, how to look
at the output from Windows, and how the Windows editors reach the Linux
side. The steps were followed on a Windows 11 machine with WSL 2.7 and
the Ubuntu it installs today, 26.04.
There are two other ways to have Klammertext on Windows: as native
Windows programs built from source (`windows_source_install.md`), and
from the prebuilt container images, which this page covers at the end,
since Docker runs inside WSL as it runs on Linux.
## Getting Linux
In a PowerShell window:
```powershell
wsl --install
```
This turns on the subsystem, installs the WSL layer and the current
Ubuntu, and may ask you to restart Windows; do that before going on.
Then open a terminal and type `wsl` (or start "Ubuntu" from the Start
menu). The first start asks for a Linux username and a password; these
are separate from your Windows account. Ubuntu may also ask whether to
send platform metrics; you can say no. You are then at a bash prompt in
your Linux home directory, and `wsl -l -v` in PowerShell shows Ubuntu as
version 2.
Two things worth knowing about the Ubuntu you now have: `sudo` works with
the password you just chose, and the machine's Windows `Path` is appended
to the Linux `PATH`, so Windows programs can be run from the Linux prompt
by name (`explorer.exe`, `code`). That is convenient below and harmless
otherwise; a Windows Python or TeX Live on the machine is not picked up
by Linux, since Linux does not resolve `.exe` names.
## Installing Klammertext
Follow `linux_source_install.md` at the Ubuntu prompt, from its first
line. Everything on it applies: the packages by `apt-get`, the clone, the
line in `~/.bashrc` that sources `runtime.env`, the build, TeX Live by the
bundled script, the verification. Nothing on that page is different
inside WSL. On the machine this page was written on, the build took under
a minute and TeX Live nine, and the engine's test suite passed as it does
on Linux.
Keep the clone and your documents in the Linux file system, under your
Linux home, not under `/mnt/c`. The Windows drives are mounted there and
work, but every file operation crosses between the two systems, and a
build or a PDF run on `/mnt/c` is several times slower.
## Seeing the output from Windows
WSL has no browser or PDF viewer of its own, and it needs none. Windows
sees the Linux file system as a network path, `\\wsl.localhost\Ubuntu\`,
and Windows programs can open files there. From the Linux prompt, after
`ktext hello.kt -t html` and `ktext hello.kt -t pdf`:
```bash
# at the Ubuntu prompt (type wsl in PowerShell to get there), not in PowerShell
explorer.exe "$(wslpath -w hello/index.html)"
explorer.exe "$(wslpath -w hello.pdf)"
```
`wslpath -w` turns a Linux path into the Windows form of the same file,
and `explorer.exe` opens it with whatever Windows opens that kind of file
with: your browser, your PDF viewer. The first time, Windows may ask
which application to use. `explorer.exe .` opens the current Linux
directory in Explorer, and from the Windows side the same files are in
Explorer under "Linux" in the sidebar. (`explorer.exe` reports exit
status 1 even when it succeeds; a script that needs a true status can use
`powershell.exe -NoProfile -Command "Start-Process \"$(wslpath -w hello.pdf)\""`
instead.)
## Editors
The Windows editors reach the Linux side, and the Linux editors are
simply there.
**Visual Studio Code**, the case this page was written for. Install VS
Code on Windows and its "WSL" extension (Microsoft's
`ms-vscode-remote.remote-wsl`). Then, at the Linux prompt, in the
directory you want to work in:
```bash
code .
```
The first time, this installs VS Code's Linux-side server into your
Linux home and opens a VS Code window on Windows connected to it. The
Klammertext extension is installed on that Linux side, once, from the
package built in the clone:
```bash
cd ~/klammertext/doc/edit/vscode && ./make_vsix.sh && code --install-extension klammertext.vsix
```
Run from the Linux prompt, `code --install-extension` installs to the
WSL side, where the extension then starts the Klammertext language
server with the Linux `python3`; everything in `doc/edit/vscode/README.md`
applies as on Linux. (Extensions installed on the Windows side of VS Code
are a separate list and do not run in WSL windows.)
**Emacs and Vim** are Linux programs: `sudo apt-get install emacs` or
`vim`, then the Emacs and Vim packages under `doc/edit/` as on Linux.
**Sublime Text and Notepad++** on Windows can open the Linux files
through `\\wsl.localhost\Ubuntu\...` and highlight them with their
Klammertext packages (`doc/edit/sublime/`, `doc/edit/notepadpp/`); their
commands that run the shared core would run the Windows `python`, so for
those two editors the native Windows installation is the better fit.
## The container route
If you would rather not build anything, the prebuilt Klammertext images
run inside WSL exactly as `linux_container_install.md` describes, since
the Ubuntu WSL installs today runs systemd and therefore Docker's
service: follow that page at the Ubuntu prompt, from `apt-get install
docker.io` on. That was done on the machine this page was written on:
the image, 2.4 GB with its TeX Live, pulled in about a minute, and its
`ktext` made the page's web page and PDF, owned by the Linux user. Docker
Desktop for Windows is the other way to run the same images; its engine
is WSL 2 as well, and it has its own licence terms for larger companies.
## Troubleshooting
**`wsl --install` says virtualization is not enabled.** WSL 2 needs the
CPU's virtualization support turned on in the machine's firmware
settings; the name varies (Intel VT-x, AMD-V, SVM). Turn it on and run
the command again.
**`code .` says the command is not found.** VS Code's `bin` directory is
put on the Windows `Path` by its installer; open a new WSL terminal after
installing VS Code, so the Linux `PATH` picks it up.
**A build or a PDF run is slow.** The clone or the document is under
`/mnt/c`. Move it under your Linux home.
**The Ubuntu window asks for a username again.** The distribution was
reset or reinstalled; the setup creates a fresh Linux home, and
Klammertext must be installed again inside it.