Sublime Text package doc renamed to README.md (from dev 6d767149c26c)
This commit is contained in:
171
doc/edit/sublime/README.md
Normal file
171
doc/edit/sublime/README.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Klammertext for Sublime Text
|
||||
|
||||
A Sublime Text port of the Emacs major mode for Klammertext
|
||||
(`doc/emacs/klammertext-mode.el`). It brings syntax highlighting, delimiter
|
||||
matching, and comment toggling to `.kt` and `.k` files. Behavior mirrors the
|
||||
Emacs mode closely; where the two intentionally differ, the file headers say so.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `Klammertext.sublime-syntax` | Syntax highlighting. Colors the text-removal constructs (`#`, `##`, `#[...]#`) and the three `@`-tiers — application `@`, definition `@@`, system `@@@` — each as an opening vs. a close, plus `^`-escapes and verbatim `@code ... code@` spans. |
|
||||
| `Klammertext.py` | Plugin with two features that share one context-sensitive matcher: jump between an opening and its close, and live highlighting of the matching delimiter as the caret moves (mismatched or unbalanced delimiters flag in red). |
|
||||
| `Klammertext_indent.py` | **Experimental.** Reindentation per the Klammertext convention (see below). A separate unit: delete this one file to disable indentation; nothing else is affected. |
|
||||
| `Klammertext_align.py` | **Experimental.** Table alignment (see below). Also a separate, deletable unit. |
|
||||
| `Default.sublime-keymap` | Binds jump-to-match to **Ctrl+M**, reindent to **Ctrl+Alt+I**, and table alignment to **Ctrl+Alt+A**, scoped to Klammertext files. |
|
||||
| `Comments.tmPreferences` | Comment toggling: **Ctrl+/** inserts `# ` (line removal), **Ctrl+Shift+/** wraps in `#[ ... ]#` (block removal). |
|
||||
| `Breakers` / `Celeste` / `Mariana` / `Monokai` / `Sixteen` `.sublime-color-scheme` | Color overrides for Sublime's five built-in schemes — one hue system, full intensity on the dark schemes, scaled down on the light ones. Additive: they recolor only the Klammertext delimiters and leave the rest of each scheme unchanged. |
|
||||
| `README.md` | This file. |
|
||||
|
||||
## Installation
|
||||
|
||||
Put the files into a folder named `Klammertext` under Sublime's `Packages`
|
||||
directory:
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| Linux | `~/.config/sublime-text/Packages/Klammertext/` |
|
||||
| macOS | `~/Library/Application Support/Sublime Text/Packages/Klammertext/` |
|
||||
| Windows | `%AppData%\Sublime Text\Packages\Klammertext\` |
|
||||
|
||||
The quickest way to find it: **Preferences ￫ Browse Packages…** opens the
|
||||
`Packages` directory. Create the `Klammertext` folder there and copy the files
|
||||
in. Sublime loads them live — no restart — and applies the syntax to `.kt` and
|
||||
`.k` files automatically.
|
||||
|
||||
Use a dedicated folder (not `Packages/User/`) so the bundled keymap does not
|
||||
merge into your personal one. If you want highlighting only, the
|
||||
`.sublime-syntax` file alone works from `Packages/User/`.
|
||||
|
||||
The plugin targets **Sublime Text 4**: the live-highlight colors use Sublime's
|
||||
adaptive `region.*` scopes, which were added in ST4.
|
||||
|
||||
## Features and keys
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| open a `.kt` / `.k` file | Syntax highlighting (automatic) |
|
||||
| **Ctrl+M** | Jump between a klammer application's opening and closing `@` (equivalent of the Emacs mode's `C-c C-j`) |
|
||||
| caret on a klammer `@` | The matching delimiter boxes automatically; a name mismatch or unbalanced delimiter boxes in red with a status-bar message (equivalent of `show-paren-mode`) |
|
||||
| **Ctrl+/** | Toggle line comment (`#`) |
|
||||
| **Ctrl+Shift+/** | Toggle block comment (`#[ ... ]#`) |
|
||||
| **Ctrl+Alt+I** | Reindent the selected lines (the current line when there is just a caret) — experimental, see "Indentation" below |
|
||||
| **Ctrl+Alt+A** | Align the columns of the table containing the caret — experimental, see "Table alignment" below |
|
||||
|
||||
Ctrl+M is Sublime's own "go to matching bracket" key, reused here because the
|
||||
built-in cannot match Klammertext's context-dependent `@`. macOS users who
|
||||
prefer `super+m` can change it in `Default.sublime-keymap`.
|
||||
|
||||
## Indentation (experimental)
|
||||
|
||||
`Klammertext_indent.py` ports the Emacs mode's indentation
|
||||
(`doc/emacs/klammertext-indent.el`): **Ctrl+Alt+I** reindents the line(s)
|
||||
touched by the selection to reflect the klammer nesting, two spaces per level:
|
||||
|
||||
```
|
||||
@ol
|
||||
Item one
|
||||
| Item two
|
||||
@ol
|
||||
Embedded item one
|
||||
| Embedded item two
|
||||
@
|
||||
| Item three
|
||||
@
|
||||
```
|
||||
|
||||
The rule: a line indents to 2 × depth; a line *beginning* with a bar run
|
||||
(`|`, `||`, …) or a closing delimiter sits one level less — at its owner's
|
||||
opening column, so bars and closes line up under the `@` of the klammer they
|
||||
belong to. All three `@`-tiers indent uniformly. Exceptions: `@document`
|
||||
contributes no level (a document's paragraphs stay at the left margin); lines
|
||||
inside verbatim `@code` content, inside `@eval` argument spans (inline Python
|
||||
is indentation-sensitive), and inside removed regions are never touched. The
|
||||
policy lists (`TRANSPARENT_KLAMMERS`, `CODE_KLAMMERS`, `INDENT_OFFSET`) are at
|
||||
the top of `Klammertext_indent.py`, kept in sync with the Emacs defcustoms.
|
||||
|
||||
Sublime's own Reindent (Edit ￫ Line ￫ Reindent) is driven by single-line
|
||||
regex patterns that cannot express Klammertext nesting, so this is a plugin
|
||||
command instead. Nothing reformats automatically (no on-Enter auto-indent):
|
||||
whitespace is content in Klammertext, so indentation happens only when you
|
||||
ask for it. To disable the feature, delete `Klammertext_indent.py` and the
|
||||
Ctrl+Alt+I entry in `Default.sublime-keymap` (or just the keymap entry, to
|
||||
keep the command available from plugins).
|
||||
|
||||
## Table alignment (experimental)
|
||||
|
||||
`Klammertext_align.py` ports the Emacs mode's table alignment
|
||||
(`doc/emacs/klammertext-align.el`): **Ctrl+Alt+A** with the caret anywhere
|
||||
inside a `@table` span pads the cells of its rows so the `|` separators line
|
||||
up:
|
||||
|
||||
```
|
||||
@table
|
||||
First item | Second | A third item that's longer ||
|
||||
Row 2 | Text | Not as long ||
|
||||
@
|
||||
```
|
||||
|
||||
A row is one line ending with the row delimiter `||` (the customary trailing
|
||||
delimiter; the last row may omit it). Alignment is for small data items, so
|
||||
a row is left untouched — and contributes nothing to the column widths —
|
||||
when any of its cells is longer than `CELL_MAX` (30) characters or the row
|
||||
spans lines. If the aligned rows would exceed `ROW_MAX` (100) columns,
|
||||
nothing changes and the status bar says so. The padding is semantically
|
||||
free: the SKS strips cell content, no whitespace is ever inserted inside a
|
||||
bar run (which would turn a `||` row separator into an empty `| |` cell),
|
||||
and bars inside a nested klammer in a cell (`@frac 1 | 2 @`) belong to that
|
||||
klammer, not the table. Aligned rows adopt the leading whitespace of the
|
||||
first aligned row — run Ctrl+Alt+I first if the rows disagree. The limits
|
||||
sit at the top of `Klammertext_align.py`, mirrored from the Emacs
|
||||
defcustoms.
|
||||
|
||||
## Colors
|
||||
|
||||
Colors are installed automatically for all five of Sublime's built-in schemes.
|
||||
Each `*.sublime-color-scheme` file (Breakers, Celeste, Mariana, Monokai,
|
||||
Sixteen) is an *additive override*: Sublime merges it onto the matching scheme
|
||||
by filename, recoloring only the Klammertext delimiters and leaving everything
|
||||
else untouched. There is nothing to set up.
|
||||
|
||||
All five share one hue system — application blue, definition green, system
|
||||
orange, each opening bright and its close the same hue darker — shown at full
|
||||
intensity on the dark schemes (Monokai, Mariana) and scaled down for contrast on
|
||||
the light schemes (Breakers, Celeste, Sixteen). Removed text uses each scheme's
|
||||
own comment grey.
|
||||
|
||||
For any other scheme — a legacy `.tmTheme` such as Solarized, or a third-party
|
||||
scheme — copy one of the included files to `<Scheme Name>.sublime-color-scheme`
|
||||
in the package folder (its name is shown at **Preferences ￫ Settings** under
|
||||
`color_scheme`), choosing a light or dark source file to match the ground. The
|
||||
exact values are in each file's header comment.
|
||||
|
||||
## Keeping literal klammers in sync
|
||||
|
||||
Klammers whose content is verbatim (`@code ... code@`) are listed in four
|
||||
places that must agree — a Sublime syntax/plugin cannot read the Emacs
|
||||
defcustom, so the list is duplicated:
|
||||
|
||||
- `klammertext-literal-klammers` in `doc/emacs/klammertext-mode.el` (the source of truth)
|
||||
- `LITERAL_KLAMMERS` in `Klammertext.py`
|
||||
- `LITERAL_KLAMMERS` in `Klammertext_indent.py`
|
||||
- the `@code` rule and `literal_code` context in `Klammertext.sublime-syntax`
|
||||
|
||||
All four are seeded with just `code`. When you add or remove a literal
|
||||
klammer, change all four.
|
||||
|
||||
## Not included
|
||||
|
||||
Whole-file semantic validation — persistent error underlines when the cursor is
|
||||
elsewhere, klammer-name completion, go-to-definition — is not part of this
|
||||
package. That would need a language server (used through the Sublime LSP
|
||||
package), a separate program, and is unrelated to the highlighting and matching
|
||||
provided here.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the plugin does not seem to load, open **View ￫ Show Console** for any error
|
||||
message. Check that the files sit directly inside `Packages/Klammertext/` (not
|
||||
a nested subfolder) and that the current file's syntax reads "Klammertext" in
|
||||
the status bar at the bottom-right of the window.
|
||||
Reference in New Issue
Block a user