Repository navigation
Lua reference: object domains, member ranking, and a live Ruby/Lua deploy - #19
Merged
Merged
Conversation
tony
force-pushed
the
lua-reference
branch
2 times, most recently
from
September 25, 2026 23:25
d197170 to
b4228f5
Compare
why: Member lists sorted alphabetically, and the page body by kind string first. Python's Server listed `sessions` behind `__enter__`, `_list_panes` and every private helper; the sidebar and the page did not even agree on the order. what: - Add member-order.ts: tiers listing accessors, query operations (search-* and snapshot, which is how Lua lists), concept-mapped operations, members the guides discuss, other public members, deprecated, special and private members - Break ties by how many ports implement the member's concept, then its place in the concept map, then guide mentions, then name - Use one comparator for the sidebar and the page body - Test every port: each list-sessions, list-windows and list-panes accessor ranks in its type's first three, and no private or special member ranks above a public one; alphabetical order fails both
why: A hierarchy bucket's path rule claimed whatever its object's source file declared. Lua's `CommandOutcome` sat under Server because it lives in server.lua, while TypeScript's identical type sat under Commands; Rust's Layout, Rotation and SplitDirection sat under Window. Lua's `Fields.Session` record, named after the object, took Session's bucket from the handle that has the methods. what: - Make the Server, Session, Window, Pane and Client path clauses yield to a later bucket's name - File object-named records of a `Fields` module under Formats - Regenerate the Lua and Rust sidecars; no other port moves
why: `toPath` split on dots, `::` and `->`, so `Server:new_session` stayed one segment and matched nothing. Every Lua guide writes methods that way, and those mentions went unlinked. C headers and sources (`tmux.h`, `options-table.c`) were counted as unresolved symbols. what: - Split `Name:method` between two identifiers - Treat .c, .h, .lua and .rb paths as filenames - Regenerate mentions.json
why: LuaLS copies a base class's fields into every subclass, so a subclass page listed its inherited methods as its own. what: - Read each class's `extends` records and trace a field to the furthest ancestor declaring it at the same file and line - Set `inheritedFrom` on those members
why: Both ports are marked as publishing their own tree, so the shell deploy drops en/ruby/latest and en/lua/latest from its artifact. Neither port's docs workflow can publish yet, so the live pages stay on a build older than the reference's domain buckets. what: - Set `publishesOwnTree: false` for ruby and lua until their workflows have published `latest`
why: libtmux-lua now declares Session, Window, WindowLink, Pane, Client and Buffer handle classes (libtmux/libtmux-lua#3). The site's Lua model predated them, so the Session, Window and Pane domains held field records and the concept map pointed every operation at the generic Entity. what: - Regenerate the Lua model, sidebar and paths from libtmux-lua fd4258b - Point Lua concepts at the handle class that owns each operation, and the session, window and pane concepts at those classes - Record Configurable, the shared options and hooks base, as unsettled - Regenerate mentions.json - Assert each Lua object domain opens on its handle class
why: The port index opened on a grid of module disclosures, and the domain sections the sidebar leads with came after it. On Lua that grid is one `libtmux` module holding every type, so the page started with the flat list the domain buckets exist to replace. what: - Render the bucket sections first and the module index after them; module anchors are unchanged
why: LuaLS exports `---@field name fun(...)` with its arguments one level down, under `extends.types`, and each member of a union in a nested group of its own. The adapter read only `extends.args`, so every Lua method in the reference rendered as `name()` with no parameters, types or return, and `Server:handle`'s overloads were lost. what: - Collect every function type a field holds, recursing through union members, and emit one signature per overload with `overload` set - Read argument names from LuaLS's name nodes - Print LuaLS's `(T)?` optionals as `T?` - Test both shapes; the old adapter fails the new test
why: libtmux-lua 294ebba gives each option, hook and environment call its own options class (libtmux/libtmux-lua#4), and the adapter now reads method signatures. what: - Regenerate the Lua model, sidebar, paths and mentions from 294ebba - Move Lua's cross-reference floor to what the assembled tree resolves: signatures add links to every parameter and return type, and the eight fields that linked `Entity` plus a snapshot record now link one class
why: With method signatures rendered, Lua's builtins became most of what the reference printed unlinked: `string`, `boolean`, `integer` and `table` in nearly every parameter list, with no table entry to link them as the other ports' builtins are. what: - Point nil, boolean, number, integer, string, function, table, thread and userdata at the manual's Values and Types section, and LuaLS's `any` and `unknown` at its annotation docs - Lower Lua's plain type-name ceiling and raise its cross-reference floor to what the assembled tree now measures
tony
temporarily deployed
to
docs-preview-cleanup
September 26, 2026 00:32 — with
GitHub Actions
Inactive
This was referenced Sep 26, 2026
tony
added a commit
that referenced
this pull request
Nov 18, 2026
…pability directories why: The Raku reference pages for the session, window and pane handles cannot show the "What is on here" capability directory until the model carries the prose it is built from. libtmux-raku#19 adds the directory to LibTmux::Model::SessionRef, WindowRef and PaneRef, and the committed model, guide cache and manifest still described ae97f9f87. The pin is the merge commit of the PR, which is on master. what: - Pin Raku to libtmux/libtmux-raku@cce868d81 and regenerate its model and path data (exported with Rakudo 2026.09, the compiler recorded in the previous model; the exporter now lives at scripts/export-docs/export-docs.raku and its digest moves), tmux usage, source cache, guide cache and manifest packages with the repository's generators; the mention index, the example sources and the sidebar sidecar come out unchanged - Adopt the source change between the pins: the model keeps 1069 symbols with none added or removed and 3 docs changed, the three handle classes that gain the directory - Re-anchor the reviewed tmux usage rules: the directories added 230 lines above the shared transfer and constructor code of Model.rakumod, so the two citations of the same-pane check in `PaneRef.join` and `PaneRef.move` and the five captured-view constructor reviews now name the line the text is on; no claim or rule changed - Take the rewritten examples README into the guide cache - Expect the directories of SessionRef (6 rows, 16 references), WindowRef (6, 18) and PaneRef (11, 38) in the directory test; the captured views Session, Window and Pane carry no directory in the source - Leave the landing example, its recording and the home fixture at 9a9838047f15: examples/quickstart.raku is unchanged between that revision and the new pin Source refs: libtmux/libtmux-raku master cce868d81823db54a0d161a94db4d078d09f1861 (#19), previous pin ae97f9f87b73db63d4ab3cabb108a195f64e4f6f.
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Lua reference at libtmux.org still opened on Queries, Errors, Runtime and an 82-entry Internal bucket, with no Server, Session, Window or Pane. Two causes: the
_internal/classifier fix never reacheden/lua/latest, and Lua had no Session, Window or Pane type to file. Member lists on every port were alphabetical, soServer.sessionssat behind__enter__and the private helpers.Changes
en/ruby/latestanden/lua/latestuntil those ports' own docs workflows can publish. Previously the shell dropped both trees and nothing else wrote them.member-order.ts): listing accessors first, then operations the concept map shares across ports (by how many ports implement them), then members the guides discuss, public, deprecated, special and private. One comparator drives the sidebar and the page body.CommandOutcomejoins Commands, as TypeScript's twin already had; Rust'sLayout,Rotation,SplitDirection,KeyBindingandEnvironmentEntryleave Window/Server/Session. Lua'sFields.*records move to Formats.Server:new_sessionresolves; C, Lua and Ruby filenames stop counting as unresolved symbols.inheritedFrom.A follow-up commit on this branch refreshes the Lua model once libtmux/libtmux-lua#3 (per-kind handle classes) merges.
Verification
$ pnpm test$ node scripts/check-nav.mjsThe member-order test runs the same property against alphabetical order and asserts it fails.