From add462d2d2bb7d6f00ec0c0af77eed18164b3979 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Thu, 12 Nov 2026 22:10:19 -0600 Subject: [PATCH] clojure(docs[guide]): Fix reader wording and links why: libtmux.org publishes the Clojure README and guide verbatim, so repository-reader phrases ("this checkout", "this README", "the package README", "the module's javadoc classifier") read wrongly on the site. The guide aliased libtmux.async and clojure.core.async both as async, and the README's control-streaming link landed on the whole guide. what: - Reword the checkout, README and javadoc-classifier phrases in the Clojure and core.async READMEs and the Clojure guide so they read on GitHub and on libtmux.org - Alias libtmux.async as tm-async in the three guide snippets that used async, leaving async for clojure.core.async - Point [guide-streaming] at #lifecycle-streaming-and-optional-adapters --- docs/guide/clojure.md | 44 ++++++++++++++-------------- libtmux-clojure-core-async/README.md | 8 +++-- libtmux-clojure/README.md | 18 +++++++----- 3 files changed, 37 insertions(+), 33 deletions(-) diff --git a/docs/guide/clojure.md b/docs/guide/clojure.md index 3246598f9..31601471e 100644 --- a/docs/guide/clojure.md +++ b/docs/guide/clojure.md @@ -4,10 +4,10 @@ encoding, transport, server identity and compatibility in Java, while exposing captured persistent Clojure values and ordinary collection operations. -Start with the package [README](../../libtmux-clojure/README.md) for the -install boundary and one capture. This guide explains the choices that matter -after the first program: what is captured, what can perform I/O, who owns -workers and streams, and where model-facing MCP tooling begins. +Start with the [install and quick start](../../libtmux-clojure/README.md) for +the install boundary and one capture. This guide explains the choices that +matter after the first program: what is captured, what can perform I/O, who +owns workers and streams, and where model-facing MCP tooling begins. The native API references list every documented public var in [the core façade](clojure-api.md) and @@ -134,16 +134,16 @@ submission does not add another tmux transport or alter the captured values. ```clojure -(require '[libtmux.async :as async] +(require '[libtmux.async :as tm-async] '[libtmux.core :as tm]) (let [socket-path (java.nio.file.Path/of (System/getProperty "libtmux.docs.socket") (make-array String 0))] (with-open [server (tm/open! {:socket-path socket-path}) - runtime (async/runtime! {:max-running 3})] + runtime (tm-async/runtime! {:max-running 3})] (tm/new-session! server {:name "docs-parallel"}) - (let [tasks (mapv (fn [_] (async/submit! runtime #(tm/snapshot! server))) + (let [tasks (mapv (fn [_] (tm-async/submit! runtime #(tm/snapshot! server))) (range 2))] (mapv #(boolean (some (fn [session] (= "docs-parallel" (:session/name session))) @@ -158,7 +158,7 @@ started. Use a separate `:wait` task for operations that wait for a release. ```clojure -(require '[libtmux.async :as async] +(require '[libtmux.async :as tm-async] '[libtmux.core :as tm]) (import '[java.time Duration]) @@ -166,14 +166,14 @@ started. Use a separate `:wait` task for operations that wait for a release. (System/getProperty "libtmux.docs.socket") (make-array String 0))] (with-open [server (tm/open! {:socket-path socket-path}) - runtime (async/runtime! {})] + runtime (tm-async/runtime! {})] (let [started (promise) - task (async/submit! runtime {:kind :wait} - #(do (deliver started true) - (tm/await-channel! server "docs-cancel" - (Duration/ofSeconds 20))))] + task (tm-async/submit! runtime {:kind :wait} + #(do (deliver started true) + (tm/await-channel! server "docs-cancel" + (Duration/ofSeconds 20))))] @started - (async/cancel! task) + (tm-async/cancel! task) (try @task (catch clojure.lang.ExceptionInfo failure @@ -369,7 +369,7 @@ explicitly when ownership requires it. ```clojure -(require '[libtmux.async :as async] +(require '[libtmux.async :as tm-async] '[libtmux.core :as tm] '[manifold.deferred :as deferred]) (import '[java.util.concurrent CompletionStage]) @@ -378,14 +378,14 @@ explicitly when ownership requires it. (System/getProperty "libtmux.docs.socket") (make-array String 0))] (with-open [server (tm/open! {:socket-path socket-path}) - runtime (async/runtime! {})] + runtime (tm-async/runtime! {})] (tm/new-session! server {:name "docs-manifold"}) - (let [task (async/submit! runtime #(tm/snapshot! server)) - stage (async/then! runtime task - #(boolean (some (fn [session] - (= "docs-manifold" - (:session/name session))) - (:tmux/sessions %)))) + (let [task (tm-async/submit! runtime #(tm/snapshot! server)) + stage (tm-async/then! runtime task + #(boolean (some (fn [session] + (= "docs-manifold" + (:session/name session))) + (:tmux/sessions %)))) observed (deferred/->deferred stage)] [(instance? CompletionStage stage) @observed]))) ;; => [true true] diff --git a/libtmux-clojure-core-async/README.md b/libtmux-clojure-core-async/README.md index f97018234..43d433b19 100644 --- a/libtmux-clojure-core-async/README.md +++ b/libtmux-clojure-core-async/README.md @@ -21,7 +21,8 @@ core.async dependency. This adapter has not shipped. Its Maven coordinate is `io.github.libtmux:libtmux-clojure-core-async`; there is no public release to -install yet. Build and verify it from this checkout: +install yet. To build and verify it from source, run this from the root of a +libtmux-java clone: ```console $ ./gradlew :libtmux-clojure-core-async:check @@ -47,8 +48,9 @@ The [complete core.async program][program] includes imports, a CLI entry point, the optional dependency alias, private-server setup and cleanup. It closes its events consumer, reads the terminal outcome, and reuses the borrowed connection. -The `javadoc` classifier contains native reference HTML and an offline source -browser, generated from this module's var metadata. +The `javadoc` classifier of the `libtmux-clojure-core-async` artifact contains +native reference HTML and an offline source browser, generated from the +adapter's var metadata. [api]: ../docs/guide/clojure-core-async-api.md [core-async]: https://clojure.github.io/core.async/clojure.core.async.html diff --git a/libtmux-clojure/README.md b/libtmux-clojure/README.md index e208d085f..303b3ce9f 100644 --- a/libtmux-clojure/README.md +++ b/libtmux-clojure/README.md @@ -22,7 +22,8 @@ leaves ordinary Clojure collection processing local and unconstrained. The Clojure façade has not shipped. Its Maven coordinate is `io.github.libtmux:libtmux-clojure`; there is no public release to install yet. -Build and verify it from this checkout: +To build and verify it from source, run this from the root of a +libtmux-java clone: ```console $ ./gradlew :libtmux-clojure:check :integration-tests:clojureIntegrationTest @@ -128,13 +129,14 @@ with the tmux version, endpoint choice, and the smallest reproducer. run. It does not yet claim a façade-specific benchmark. - [Changelog](CHANGELOG.md) — module-visible changes once this façade ships. -Every Clojure snippet in this README and the guide runs against an isolated -tmux server in `:integration-tests:clojureIntegrationTest`; no snippet is -illustrative pseudocode. +Every Clojure snippet on this page and in the [guide][guide] runs against an +isolated tmux server in `:integration-tests:clojureIntegrationTest`; no snippet +is illustrative pseudocode. -The module's `javadoc` classifier contains native Clojure reference HTML and -an offline source browser. Build it with `:libtmux-clojure:clojureApiJar`; -the generated site starts at `build/docs/clojure/index.html` in this module. +The `javadoc` classifier of the `libtmux-clojure` artifact contains native +Clojure reference HTML and an offline source browser. To build it from source, +run `:libtmux-clojure:clojureApiJar`; the generated site starts at +`libtmux-clojure/build/docs/clojure/index.html`. [benchmarks]: ../benchmarks/README.md [api]: ../docs/guide/clojure-api.md @@ -145,7 +147,7 @@ the generated site starts at `build/docs/clojure/index.html` in this module. [core-async]: ../libtmux-clojure-core-async/README.md [data-api]: ../docs/guide/clojure-api.md#libtmuxdata [guide]: ../docs/guide/clojure.md -[guide-streaming]: ../docs/guide/clojure.md +[guide-streaming]: ../docs/guide/clojure.md#lifecycle-streaming-and-optional-adapters [java-core]: ../libtmux/README.md [mcp-guide]: ../docs/guide/mcp.md [programs]: ../examples/api/README.md#clojure-programs