docs: review and update (#18)

Of note: Described how hidden setup code can be run from adoc files

README.adoc

@@ -19,8 +19,8 @@ Test AsciiDoc and CommonMark code blocks found in articles and docstrings
 
 [CAUTION]
 ====
-Sample code in docs, while likely not malicious, could be illustrating, for example, how to wipe a drive.
-So, do be deliberate and careful about what docs you run through test-doc-blocks.
+While likely not malicious, sample code in docs could illustrate, for example, how to wipe a drive.
+So be deliberate and careful about what docs you run through test-doc-blocks.
 ====
 
 toc::[]
@@ -30,7 +30,7 @@ toc::[]
 Alpha - early adopters and feedback welcome!
 
 == Rationale
-I wanted to make sure the code examples I provided in rewrite-clj v1 documentation do not mislead and do function as expected for those who dare to try them.
+I wanted to make sure the code examples I provided in rewrite-clj v1 documentation do not mislead and function as expected for those who dare to try them.
 You might want the same for your library.
 
 == Docs
@@ -86,7 +86,7 @@ image:lread.png[lread,role="left",width=310,link="https://github.com/lread"]
 // AUTO-GENERATED:MAINTAINERS-END
 
 == License
-Copyright © 2021 Lee Read, all rights reserved.
+Copyright © 2024 Lee Read, all rights reserved.
 
 Distributed under the EPL License, same as Clojure.
 See LICENSE.

doc/01-user-guide.adoc

@@ -9,17 +9,17 @@
 //#:test-doc-blocks{:skip true :apply :all-next}
 
 == Audience
-You are someone who wants to verify that the Clojure/ClojureScript code examples in your docs work as expected.
+You want to verify that the Clojure/ClojureScript code examples in your docs work as expected.
 
 == Prerequisites
-Test generation requires Clojure v1.9 or above.
+You can generate tests with Clojure v1.9 or above.
 
-Generated tests can be run on Clojure v1.8 and above (if supported by your test runner).
+You can run generated tests with Clojure v1.8 and above (if supported by your test runner).
 
-You'll use your test runner of choice, for example: https://github.com/cognitect-labs/test-runner[Clojure test-runner], https://github.com/Olical/cljs-test-runner[cljs-test-runner], https://github.com/lambdaisland/kaocha[kaocha], or some https://github.com/technomancy/leiningen[lein] test runner.
+You'll use your test runner of choice: https://github.com/cognitect-labs/test-runner[Clojure test-runner], https://github.com/Olical/cljs-test-runner[cljs-test-runner], https://github.com/lambdaisland/kaocha[kaocha], or some https://github.com/technomancy/leiningen[lein] test runner.
 
 == Introduction
-Test-doc-blocks might (or might not, see link:#limitations[limitations], and link:#interesting-alternatives[interesting alternatives]) be of interest for your Clojure/ClojureScript project.
+Test-doc-blocks might (or might not; see link:#limitations[limitations] and link:#interesting-alternatives[interesting alternatives]) be of interest for your Clojure/ClojureScript project.
 
 Test-doc-blocks recognizes:
 
@@ -124,7 +124,7 @@ Invoke for this project via: `clj -M:isolated/clj-test-runner`
 [#leiningen]
 === Leiningen
 
-An an example subset of a `project.clj`:
+An example subset of a `project.clj`:
 
 [source,clojure,subs="attributes+"]
 ----
@@ -157,7 +157,7 @@ lein run-doc-tests
 
 === Detailed Doc Examples with Inline Options
 
-For detailed doc examples that include inline options you will want to read:
+For detailed doc examples that include inline options, you will want to read:
 
 * link:example.adoc[AsciiDoc example]
 * link:example.md[CommonMark example]
@@ -173,14 +173,14 @@ After you experiment with which options are appropriate for your project, you'll
 
 [TIP]
 ====
-Leiningen users should focus on the `-M` syntax and apply it back to the link:#leiningen[leiningen example].
+Leiningen users should focus on the `-M` syntax and apply it to the link:#leiningen[leiningen example].
 ====
 
 ==== docs
 By default, tests are generated for `README.md` only.
 
 *-X syntax* +
-If you want to specify a different vector of files you can do so via `:docs`
+If you want to specify a different vector of files, you can do so via `:docs`
 
 [source,shell]
 ----
@@ -236,7 +236,7 @@ Any special quoting should not be necessary when specifying options directly in
 ====
 
 ==== target-root
-The default directory where tests are generated is `./target`.
+By default, test-doc-blocks generates tests to `./target`.
 
 *-X syntax* +
 Override via `:target-root` when using the `-X` syntax:
@@ -348,7 +348,6 @@ Test-doc-blocks makes no platform assumptions when generating tests from doc blo
 
 Some limitations that we might entertain addressing:
 
-* If your code block depends on some external setup, we've no way to express that.
 * Test-doc-blocks will automatically handle inline `(require ...)` and `(import ...)` appearing in code blocks, but not in any complex expressions of these forms.
 * Parsing adoc and md files is on the naive side but should handle most common cases.
 If we've overlooked a common syntax, let us know.
@@ -371,11 +370,11 @@ Other options and related projects that I am currently aware of (in alphabetical
 It uses this support in tests for some of its documentation.
 A `.feature` document describes the feature and includes given, when, then scenarios that are both run and shown in the documentation.
 You can use step definitions to hide any gritty details.
-* https://github.com/pink-gorilla/notebook[notebook] - Some day notebook type tools might serve both as tests and docs.
+* https://github.com/pink-gorilla/notebook[notebook] - Someday notebook-type tools might serve both as tests and docs.
 Until that golden day, test-doc-blocks and similar tools are worthy of consideration.
 * https://github.com/hyperfiddle/rcf[RCF] - Turns your Rich Comment Forms into tests
 * https://github.com/seancorfield/readme[readme] (archived) - Generates tests for code blocks found in .md files and then runs them.
-It is simpler but but also has less features.
+It is simpler but also has fewer features.
 This project was the inspiration for test-doc-blocks.
 *Note:* This project is now archived and recommends existing users consider test-doc-blocks instead.
 * https://github.com/liquidz/testdoc[testdoc] - Tests code blocks in docstrings and external docs.

doc/02-developer-guide.adoc

@@ -14,14 +14,14 @@ Thanks for your interest test-doc-blocks development.
 == Generalities
 
 We make use of babashka tasks.
-To see a list of available tasks run:
+To see a list of available tasks, run:
 
 [source,shell]
 ----
 bb tasks
 ----
 
-For help on a task's available command line arguments run `bb <task-name> --help`, for example:
+For help on a task's available command line arguments, run `bb <task-name> --help`, for example:
 
 [source,shell]
 ----
@@ -92,7 +92,7 @@ bb outdated
 ----
 
 == Linting
-We use clj-kondo to lint project source and fail the build when linting fails.
+We use clj-kondo to lint the project source and fail the build when linting fails.
 
 To run linting as the CI server does:
 
@@ -101,7 +101,7 @@ To run linting as the CI server does:
 bb lint
 ----
 
-If, for whatever reason, you want to rebuild the lint cache, use the `--rebuild` option.
+If you want to rebuild the lint cache, use the `--rebuild` option.
 
 == Continuous Integration
 
@@ -152,12 +152,12 @@ Before a release, it can be comforting to preview what docs will look like on ht
 
 Limitations
 
-* This task should be considered experimental.
+* Considered this task experimental.
 I have only tested on macOS, but I am fairly confident it will work on Linux.
-Not sure about Windows at this time.
+I'm not sure about Windows at this time.
 * You have to push your changes to GitHub to preview them.
 This allows for a full preview that includes any links (source, images, etc.) to GitHub.
-This works fine from branches and forks - in case you don't want to affect your main development branch for a preview.
+This task works fine from branches and forks - if you don't want to affect your main development branch for a preview.
 
 **Start Local Services**
 
@@ -166,7 +166,7 @@ To start the local cljdoc docker container:
 bb cljdoc-preview start
 ----
 
-The local cljdoc server allows you to view your ingested docs in your web browser.
+The local cljdoc server lets you view your ingested docs in your web browser.
 
 The start command also automatically checks docker hub for any updates so that our cljdoc preview matches the current production version of cljdoc.
 
@@ -180,7 +180,7 @@ bb cljdoc-preview ingest
 The ingest command automatically publishes rewrite-clj to your local maven repository (cljdoc only works with published jars).
 
 The locally published version will include a `-cljdoc-preview` suffix.
-I find this distinction helps to reduce confusion around locally vs remotely installed artifacts.
+This distinction helps to reduce confusion about locally vs remotely installed artifacts.
 
 You'll have to remember to git commit and git push your changes before ingesting.
 
@@ -193,7 +193,7 @@ To open a view to the ingested docs in your default web browser:
 bb cljdoc-preview view
 ----
 
-If you have just run the start command, be a bit patient, the cljdoc server can take a few moments to start up - especially on macOS due to poor file-sharing performance.
+If you have just run the start command, be a bit patient; the cljdoc server can take a few moments to start up - especially on macOS due to poor file-sharing performance.
 
 **Stop Local Services**
 

doc/03-maintainer-guide.adoc

@@ -9,12 +9,12 @@ You are involved in maintaining/releasing test-doc-blocks.
 A release is triggered manually via a GitHub Action "Release" workflow.
 
 === Automated Workflow
-The released workflow is handled by our https://github.com/lread/test-doc-blocks/actions?query=workflow%3A%22Release%22[Release] GitHub Action.
+Our https://github.com/lread/test-doc-blocks/actions?query=workflow%3A%22Release%22[Release] GitHub Action handles the release workflow.
 
 Our GitHub Actions "Release" workflow:
 
 . Create a thin jar using our version scheme
-. Apply jar version to following docs:
+. Apply jar version to the following docs:
 .. user guide docs `deps.edn` usage example
 .. change log "unreleased" and "unreleased breaking changes" headings
 . Deploy the jar to clojars
@@ -34,7 +34,7 @@ The release workflow consults this file when constructing the version.
 
 === Special Setup
 
-GitHub has been configured with necessary secrets for GitHub Actions to deploy to clojars.
+GitHub has been configured with necessary secrets for GitHub Actions to deploy test-doc-blocks to clojars.
 
 === Local Verification
 To run the change log validation locally:
@@ -57,4 +57,4 @@ As a maintainer, you should have sufficient privileges to see a "Run Workflow" d
 The dropdown will prompt for a branch.
 I did not see a way to disable this prompt, leave it at "main" and run the workflow.
 
-TIP: Don't forget to pull after a release to get the changes made by the release workflow.
+TIP: Remember to pull after a release to get the changes made by the release workflow.