diff options
| -rw-r--r-- | docs/shared-libs.md | 14 | ||||
| -rw-r--r-- | docs/typ/building.typ | 16 | ||||
| -rw-r--r-- | docs/typ/cheatsheet.typ | 2 | ||||
| -rw-r--r-- | docs/typ/install.typ | 8 | ||||
| -rw-r--r-- | docs/typ/reference.typ | 48 | ||||
| -rw-r--r-- | src/CHANGELOG.md | 7 |
6 files changed, 69 insertions, 26 deletions
diff --git a/docs/shared-libs.md b/docs/shared-libs.md index 70e585b3..52457bf1 100644 --- a/docs/shared-libs.md +++ b/docs/shared-libs.md @@ -21,6 +21,20 @@ a second FreeType (tools/shared_libs_check.zig). It counts static functions too, and several functions per family, because a release build inlines some of them. +## PDF panes became an addon (2026-11-06) + +`lib/pardes/addons/pdf.so` (addons/pdf/pdf.c and pdf_bridge.c) holds MuPDF, +built against the build's FreeType and zlib and linked into the library +with them, all three compiled position-independent; it exports +`pardes_addon` alone (a version script), so its FreeType and zlib never +meet the window's. The binaries hold no MuPDF: the tty none of FreeType or +zlib either, the window the one FreeType its glyph atlas uses. MuPDF and +the bridge allocate through pardes's heap for kinds (`pa_api.heap` over the +`addon` region, memory.zig), never their own malloc, so the Debug leak check +sees them. A window that loads pdf.so holds a second FreeType and zlib +beside its own: a library apart, as image.so's decoders are. The rows below +are the binaries before both addons. + ## Image panes became an addon (2026-11-06) `lib/pardes/addons/image.so` (addons/image/image.c) decodes image panes with diff --git a/docs/typ/building.typ b/docs/typ/building.typ index 4b736251..50b85986 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -12,7 +12,9 @@ pieces fit. To install it, see #doc("setup", section: "install"). Zig *0.17.0* (`build.zig.zon` pins `minimum_zig_version`). Dependencies are fetched and pinned by the manifest; the terminal build needs no system package. The SDL shell builds SDL3 and FreeType from source. PDF support -builds MuPDF and is on by default (`-Dmupdf=false` drops it). +is an addon, `pdf.so`, built over MuPDF (its own FreeType and zlib in it) +and on by default (`-Dmupdf=false` leaves it out); the binaries hold no +MuPDF. #pairs( [`zig build`], [the terminal shell and the SDL window together, *installed into `~/.local/bin`* (`pardes` and `pardes-gui`)], @@ -38,7 +40,7 @@ must share with its session; `pardes --help` lists every flag. #pairs( [`-Dplatform`], [`tui`, `gui`, `macos`; absent: the tui and SDL shells together, installed into `~/.local`], [`-Dstatic`], [bool, `false`], - [`-Dmupdf`], [bool, `true`], + [`-Dmupdf`], [bool, `true`: build and install the PDF addon], [`-Djpx`], [bool, `true`: JPEG 2000, and with it scanned PDFs], [`-Dtree-sitter`], [`disabled`, `zig`, `minimal`, `full`; `full`], [`-Dembed-sources`], [bool, `false`: serve the sources under #file("/src")], @@ -60,7 +62,7 @@ must share with its session; `pardes --help` lists every flag. zig build unit-test module and shell unit tests (the perf gate runs with it) zig build test-build compile the unit-test programs without running them zig build core-test core tests without native shell tests -zig build pane-test pane, output, PDF and namespace integration tests +zig build pane-test pane, output and namespace integration tests zig build kitty-test kitty graphics conformance of terminal panes, at the core zig build kitty-harness kitty graphics through a pane end to end (a fake kitty terminal outside on the tui, the GPU capture on the gui; @@ -81,7 +83,7 @@ zig build hxdiff differential suite against helix's own behaviour zig build hxparity file-pane vs pty-pane editing parity zig build hxgolf every helix-golf example, step by step, against helix zig build perf-gate a gesture on the 50k-line file over 3x its baseline fails -zig build mupdf-check compile, link, render and search docs/design.pdf +zig build mupdf-check the PDF addon's MuPDF: compile, link, render and search docs/design.pdf zig build cheatsheet render the cheatsheet PDF (needs typst) ``` @@ -103,8 +105,8 @@ zig build cheatsheet render the cheatsheet PDF (needs typst) - `zig build hxdiff -- --strict cases.jsonl reference.jsonl [waivers.jsonl]` runs custom differential cases. `docs/helix-keys.md` tracks helix parity key by key and names the reference helix build; `docs/selections.md` is the selection model under normal mode. -- Benchmarks (`perf`, `pdf-bench`, `pdf-scroll-bench`, - `pdf-sections-bench`, `lspbench`, `fs-bench`) take `-- --json`; measure +- Benchmarks (`perf`, `pdf-scroll-bench`, `pdf-pointer-bench`, + `lspbench`, `fs-bench`) take `-- --json`; measure with `-Doptimize=ReleaseFast`. `perf -- --base old.json` refuses reports whose build metadata differs. - `zig build history -- run 'ancestors(@, 2)' DIR -- zig build unit-test` @@ -151,7 +153,7 @@ effects such as spawning processes. - `host_io.Host` is a context pointer and a vtable of optional callbacks; a null method is not an error, and `Host{}` is a complete in-process pardes that the tests use. Comptime decides what a build has (`pardes.platform`, - `can_attach`, `pdf_enabled`); the vtable + `can_attach`); the vtable decides who serves it. - The root module is chosen by platform: `main.zig` (tui, gui), `macos.zig`. The macOS shell is a library whose host owns `main()`. diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ index 60bea770..25a9294f 100644 --- a/docs/typ/cheatsheet.typ +++ b/docs/typ/cheatsheet.typ @@ -28,7 +28,7 @@ One button: Alt/Option-click is #btn("B2"), Cmd/Super-click #btn("B3"), sweeps t #tag("New Term Find Grep Joincol Delcol") #tag("Save Term Collapse Del", path: "/home/me/notes.txt") #tag("Term+bash Save Mode Filter Collapse Del", path: "/home/me/src") -#tag("Term PdfSections PdfTint PdfFit Collapse Del", path: "manual.pdf [1/12]") +#tag("Term PdfSections PdfTint PdfFit Collapse Del", path: "[1/12] … manual.pdf") - #word("Del") over unsaved text refuses once; again discards. #word("Del") `j`: rows below. #key("SPC d") between two panes takes #key("k") (rows above) or #key("j") (below), asking only if you pause. - #word("Undo") #word("Redo") #word("Edit") #word("Mode") work typed anywhere. #doc("tags") diff --git a/docs/typ/install.typ b/docs/typ/install.typ index 570f4313..6b7c2d34 100644 --- a/docs/typ/install.typ +++ b/docs/typ/install.typ @@ -23,6 +23,8 @@ downloaded, a first build from a clean cache took 62 seconds on 16 cores): #cmd("# pardes, in a terminal\nzig build -Dplatform=tui --prefix ~/.local") #cmd("# pardes-gui, its own window\nzig build -Dplatform=gui --prefix ~/.local") Then run `pardes` or `pardes FILE`. Each also installs -`lib/pardes/addons/image.so`, the image addon, which pardes loads at start -from its prefix: a pardes without it (a downloaded binary alone) shows -image files as text. +`lib/pardes/addons/image.so`, the image addon, and +`lib/pardes/addons/pdf.so`, the PDF addon (MuPDF, left out by +`-Dmupdf=false`), which pardes loads at start from its prefix: a pardes +without them (a downloaded binary alone) shows image files and PDFs as +text. diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 7af819a1..44b3bed9 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -503,8 +503,9 @@ keyboard goes to its tag, #file("focus") reads empty, the log says only #file("tag") files (#file("/tag"), #file("/col/<n>/tag"), #file("/pane/<n>/tag")) read the whole tag, with no newline after it. A -pane's starts with its computed path (an image's with its mode words, a -PDF's with its page), then the editable text. `>` replaces the editable +pane's starts with its computed path, then the editable text. A kind's +pane's starts with what its kind says (an image's `img`, a PDF's page +`[1/12]`), the core's art words when it shows a picture, then its path. `>` replaces the editable text (the default words too: `echo Make > tag` leaves only `Make`) and drops the one newline that ends it; `>>` appends, so `printf ' Make' >> tag` (the blank matters; `echo` would start a second @@ -977,14 +978,20 @@ An addon is a shared library that brings one kind of pane: a picture, a game, a plot. It is written against one header, `src/kinds/pardes_addon.h`, in C or anything that speaks C, and links nothing of pardes: the records are the header's, and what pardes does for it (an allocation from the -pane's arena, a job off the loop, a Look, a message, a new text pane) it is -handed at load. `addons/fake/fake.c` uses every function and -`addons/snake/snake.c` is a game in it; a kind with only a head and `paint` -is a valid one. Pictures are an addon too, `addons/image/image.c` (PNG, -JPEG, GIF, BMP, PPM, PGM and TGA through stb_image, at most 1280 pixels a -side), which the build installs as `<prefix>/lib/pardes/addons/image.so`; -without it an image file opens as text. The header is ABI 2: an addon -built against another major is refused. +pane's arena, memory that outlives a call, a job off the loop, a Look or an +Exec, a message, a new text pane, its selection) it is handed at load. +`addons/fake/fake.c` uses every function and `addons/snake/snake.c` is a +game in it; a kind with only a head and `paint` is a valid one. Pictures +are an addon too, `addons/image/image.c` (PNG, JPEG, GIF, BMP, PPM, PGM and +TGA through stb_image, at most 1280 pixels a side), which the build +installs as `<prefix>/lib/pardes/addons/image.so`, and so are PDFs, +`addons/pdf/pdf.c` over MuPDF (its pages rendered on jobs, two at once), +installed as `<prefix>/lib/pardes/addons/pdf.so` (none with +`-Dmupdf=false`); without them an image file and a PDF open as text. The +header is ABI 2.1: an addon built against another major is refused, and +one of 2.0 runs as it did (2.1 added at the ends of its records: `heap`, +`view`, `exec` and `select` in its `pa_api`, the rail's thumb in +`pa_paint`, its own `search`). - `tick(state, now, flags)` returns the absolute time of its next step (0: none) on a monotonic clock. It is called when that time comes and @@ -1025,13 +1032,24 @@ built against another major is refused. elsewhere is refused. A Look of a file whose extension an addon claims opens a pane of its kind. - A pane of an addon's kind takes every key but #key("Esc") when its kind - takes keys, as a raw terminal does, and its clicks when it takes the - mouse. Its #file("body") is the kind's text, if it has any; its + takes keys, as a raw terminal does (#key("Esc") too, first, for a kind + of 2.1: not taken, it leaves), and its clicks when it takes the mouse, + a press's drag and release wherever they go, and a motion off its body + when the pointer leaves it. `tick` is called again when its view (its + window, a cell's pixels, the theme) changes. A `/` in it asks its kind's + `search`, a `+Search` of its rows; a Look of `file:<place>` (`:<place>` + in it) is its kind's `address`, a miss said `<path>` and what the kind + said (`has no page 99`), one from a list its kind made (`text`) handed + with the list's name first (`+PdfSections 3:2`). Its #file("body") is the kind's text, if it has any; its #file("ctl") read ends with the kind's own fields. - A dump keeps each such pane: its kind, version, path and place, and the - kind's own record. Restored without its addon, the pane waits in its - place saying `addon <name> <version> is not loaded: Addon load <path>`; - the addon loaded, it opens there. + kind's own record (a PDF's: its file's bytes, its fit, tint and page). + Restored without its addon, the pane waits in its place saying `addon + <name> <version> is not loaded: Addon load <path>`; the addon loaded, it + opens there. One with no record opens from its file, at its place, its + words given again; a PDF pane of a dump made before the PDF addon comes + back so. A pane whose file changes on disk opens again from it, its + record kept for its `load` (a PDF stays on its page). - An addon runs in pardes's process. A load is marked on disk while it runs; a start that finds the mark of one that never finished skips that library, listed so, until #word("Addon") `load` asks for it again. A diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 6182be8c..766004d5 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -2,6 +2,13 @@ ## Unreleased +- PDFs are an addon: `lib/pardes/addons/pdf.so` (addons/pdf, over MuPDF, + which left the binaries), installed beside them and loaded at start; a + pardes without it shows a PDF as text. A PDF's tag starts with its page, + `[1/12]`, then the art words its pictures take and its path. Addons + speak ABI 2.1: a heap, the pane's view, `exec`, `select`, their own + `search` for `/`, Esc first, a rail's thumb. + - Pictures are an addon: `lib/pardes/addons/image.so` (addons/image), installed beside the binaries and loaded at start; a pardes without it shows image files as text. |
