Repository navigation
clojure(docs[guide]): Fix reader wording and links - #158
Merged
Merged
Conversation
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
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.
Fixes three findings from a review of the published Clojure pages on libtmux.org (rows C15, C16 and C22 of the review ledger). libtmux.org stages the Clojure README, the Clojure guide and the core.async README verbatim, so the wording and links in these source files are what site readers see. Docs only; no code, no changelog entry (the unreleased Clojure documentation entry already covers these pages).
C15: repository-reader wording
The Clojure README, the core.async README and the Clojure guide said "this checkout", "Every Clojure snippet in this README", "the module's
javadocclassifier" and "Start with the package README". On the site these point at nothing.javadocclassifier sentences name the artifact (libtmux-clojure,libtmux-clojure-core-async), and the generated-site path is spelled from the repository root.C16:
asyncalias clashThe guide aliased both
clojure.core.asyncandlibtmux.asyncasasync.libtmux.asyncis nowtm-asyncin the three snippets that used it, andclojure.core.asynckeepsasync.C22:
[guide-streaming]anchor[guide-streaming]in the Clojure README linked the whole guide from the words "control streaming". It now ends in#lifecycle-streaming-and-optional-adapters, the guide section that covers control. The libtmux/docs staging script rewrites the path to the staged guide route and keeps the fragment, so it resolves on GitHub and on the site.Test plan
./gradlew :integration-tests:clojureIntegrationTest -PlibtmuxClojureTestNamespaces=libtmux.documentation-examples-testpasses (6 tests, 26 assertions, tmux 3.8a), so every guide and README snippet still runs and matches its displayed resulttm-async/cancel!call toasync/cancel!makes the same task fail withNo such namespace: async, so the gate catches a broken alias./gradlew :docs:test --tests io.github.libtmux.docs.DocumentationFactsTestpasses, including the repository link check