Adhere to one sentence per line for adocs

Author: lread

CHANGELOG.adoc

@@ -20,7 +20,8 @@ If you wish, you can read nitty gritty details on link:doc/design/01-merging-rew
 What follows is a summary of changes.
 
 ==== New
-* A new home under clj-commons. Thanks to @xsc, rewrite-clj will also retain its same maven coordinates on Clojars making for a seamless upgrade path for rewrite-clj v0 users.
+* A new home under clj-commons.
+Thanks to @xsc, rewrite-clj will also retain its same maven coordinates on Clojars making for a seamless upgrade path for rewrite-clj v0 users.
 * Now supports ClojureScript, merging in rewrite-cljs specific functionality.
 Frustrations like not having namespace map support and differences from rewrite-clj, like whitespace parsing, should now be things of the past.
 Rewrite-cljs users migrating to rewrite-clj v1 are now at, and will remain at, feature parity with rewrite-clj.
@@ -75,7 +76,8 @@ Rewrite-cljs users migrating to rewrite-clj v1 are now at, and will remain at, f
 * Moved from potemkin import-vars to static template based version https://github.com/clj-commons/rewrite-clj/issues/98[#98]:
 ** Avoids frustration/mysteries of dynamic import-vars for users and maintainers
 ** Argument names now correct in API docs (some were gensymed previously)
-** Also turfed use of custom version of potemkin defprotocol+ in favor of plain old defprotocol. Perhaps I missed something, but I did not see the benefit of defprotocol+ for rewrite-clj v1.
+** Also turfed use of custom version of potemkin defprotocol+ in favor of plain old defprotocol.
+Perhaps I missed something, but I did not see the benefit of defprotocol+ for rewrite-clj v1.
 
 ==== Internal changes (developer facing)
 * Tests updated to hit public APIs https://github.com/clj-commons/rewrite-clj/issues/106[#106]

README.adoc

@@ -25,7 +25,8 @@ Only a minor failure on zprint v1.1.1 was found due to intentional breaking chan
 * Please review link:CHANGELOG.adoc[change log] for an overview of all v1 changes.
 * I am very conservative on making any further v0->v1 breaking changes, but am open to breaking changes to any of the new v1 work.
 
-We'll move out of alpha after folks have had a chance to give rewrite-clj v1 alpha a good shake. Things look solid but I would be very surprised if there are no issues and/or feedback.
+We'll move out of alpha after folks have had a chance to give rewrite-clj v1 alpha a good shake.
+Things look solid but I would be very surprised if there are no issues and/or feedback.
 
 See https://github.com/clj-commons/rewrite-clj/projects/1[project page for current priorities].
 
@@ -44,7 +45,8 @@ Rewrite-clj versioning scheme is: `major`.`minor`.`patch`-`test-qualifier`
 * `major` increments when a non alpha release API has been broken - something, as a rule, we'd like to avoid.
 * `minor` increments to convey significant new features have been added.
 * `patch` indicates bug fixes - it is the total number of commits in the repo.
-* `test-qualifier` is absent for stable releases. Can be `alpha`, `beta`, `rc1`, etc.
+* `test-qualifier` is absent for stable releases.
+Can be `alpha`, `beta`, `rc1`, etc.
 
 == People
 

doc/01-user-guide.adoc

@@ -12,7 +12,7 @@ Rewrite-clj is a library that can read, update and write Clojure, ClojureScript
 If rewrite-clj is not your cup of tea, consider following alternatives:
 
 |===
-| Project | Parsing? | Writing? | Whitespace Perserving? | Includes Element Row/Col?
+| Project | Parsing? | Writing? | Whitespace Preserving? | Includes Element Row/Col?
 
 | https://github.com/carocad/parcera[parcera]
 | yes
@@ -124,7 +124,7 @@ As you get more experienced with rewrite-clj, you will want to review link:#sexp
 === Tools Deps
 Include the following dependency in your `deps.edn` file:
 //:test-doc-blocks/skip
-// NOTE: the version in this snippit is automaticaly updated by our release workflow
+// NOTE: the version in this snippit is automatically updated by our release workflow
 [source,clojure]
 ----
 rewrite-clj/rewrite-clj {:mvn/version "0.6.1"}
@@ -288,7 +288,7 @@ Use:
 ==== Familiar Functions for Updating Nodes with the Zip API
 
 The zip API provides familiar ways to work with parsed Clojure data structures.
-It offers some functions that correspond to the standard Clojure seq functions, for example:
+It offers some functions that correspond to the standard Clojure `seq` functions, for example:
 
 [source, clojure]
 ----
@@ -324,7 +324,7 @@ It offers some functions that correspond to the standard Clojure seq functions,
 ;; => "{:prefix/a 10 :prefix/b 20}"
 ----
 
-// Targetted from docstrings
+// Targeted from docstrings
 [#position-tracking]
 ==== Tracking Position with the Zip API
 
@@ -764,7 +764,8 @@ Observations:
 Rewrite-clj v1 will carry on.
 ** It seems the idea might have been that the caller could eval the sexpr result if they wanted to?
 ** Note for ClojureScript users, `read-string` is not available under `cljs.core`, but a version is available under `cljs.tools.reader`.
-2. Tag metadata is returned as boolean metadata. A user could infer the intent through inspection though.
+2. Tag metadata is returned as boolean metadata.
+A user could infer the intent through inspection though.
 
 // NOTE: target of some docstrings
 [#namespaced-elements]
@@ -889,7 +890,7 @@ The resulting zipper will then automatically apply your `:auto-resolve` within a
 ** `edit` - the current node is sexpr-ed
 ** `get` and `assoc` - sexpr is applied to the map key
 
-// NOTE: targetted from docstrings
+// NOTE: targeted from docstrings
 [#impact-of-auto-resolve]
 ==== Impact of Auto-Resolve
 

doc/02-developer-guide.adoc

@@ -5,14 +5,16 @@
 == Supported Environments
 Rewrite-clj is verified on each push on macOS, Ubuntu and Windows via GitHub Actions.
 
-All scripts are written in Clojure and most invoked via https://github.com/borkdude/babashka[babashka]. This gives us a cross platform
-scripting language that is familiar, fun and consistent. These docs will show babashka scripts invoked explicitly via babashka's `bb`; on
-macOS and linux feel free to leave out `bb`.
+All scripts are written in Clojure and most invoked via https://github.com/borkdude/babashka[babashka].
+This gives us a cross platform scripting language that is familiar, fun and consistent.
+These docs will show babashka scripts invoked explicitly via babashka's `bb`; on macOS and linux feel free to leave out `bb`.
 
-We make use of planck for cljs bootstrap (aka cljs self-hosted) testing. Planck is currently not available for Windows.
+We make use of planck for cljs bootstrap (aka cljs self-hosted) testing.
+Planck is currently not available for Windows.
 
-We test that rewrite-clj operates as expected when natively compile via GraalVM. Automated testing is setup using GraalVM v21 for
-both jdk8 and jdk11. On Windows we only test against jdk11 as tool setup for jdk8 on Windows seemed overly arduous.
+We test that rewrite-clj operates as expected when natively compile via GraalVM.
+Automated testing is setup using GraalVM v21 for both JDK8 and JDK11.
+On Windows we only test against JDK11 as tool setup for JDK8 on Windows seemed overly arduous.
 
 == Prerequisites
 * Java JDK 1.8 or above
@@ -26,25 +28,23 @@ both jdk8 and jdk11. On Windows we only test against jdk11 as tool setup for jdk
 
 ==== Git and newlines
 The primary development OSes for rewrite-clj are macOS and Linux.
-Our line endings are lf only.
+Our line endings are LF only.
 
 I'm not sure what Windows developers typically want for line endings while working on source.
-I expect, but don't know, that most Windows editors automatically handle lf as line ending.
+I expect, but don't know, that most Windows editors automatically handle LF as line ending.
 Someone let me know if I am wrong.
 
 Note that I do explicitly set git's config `core.autocrlf` to `false` on our Windows CI unit test environment.
 Our import vars code generation checks currently rely on line endings remaining unconverted.
 
 ==== Babashka
-The Clojure story on Windows is still in the early chapters. https://scoop.sh/[Scoop] offers an easy way to install tools.
-@littleli is doing a great job  w/maintaining https://github.com/littleli/scoop-clojure[scoop apps for Clojure, Babashka and other tools] and
-this is how I installed Babashka.
+The Clojure story on Windows is still in the early chapters.
+https://scoop.sh/[Scoop] offers an easy way to install tools.
+@littleli is doing a great job  w/maintaining https://github.com/littleli/scoop-clojure[scoop apps for Clojure, Babashka and other tools] and this is how I installed Babashka.
 
 ==== Clojure
-We all choose our own paths, but for me, using https://github.com/borkdude/deps.clj[deps.clj] instead of
-https://github.com/clojure/tools.deps.alpha/wiki/clj-on-Windows[Clojure's PowerShell Module] offered me no
-fuss no muss Clojure on Windows and GitHub Actions on Windows. I decided to install deps.clj not through scoop but through
-https://github.com/borkdude/deps.clj#windows[the deps.clj `install.ps1` script].
+We all choose our own paths, but for me, using https://github.com/borkdude/deps.clj[deps.clj] instead of https://github.com/clojure/tools.deps.alpha/wiki/clj-on-Windows[Clojure's PowerShell Module] offered me no fuss no muss Clojure on Windows and GitHub Actions on Windows.
+I decided to install deps.clj not through scoop but through https://github.com/borkdude/deps.clj#windows[the deps.clj `install.ps1` script].
 This makes it simple to treat `deps.exe` as if it were the official `clojure` via a simple rename:
 
 ----
@@ -64,10 +64,10 @@ Here's what works on my Windows dev environment:
 call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
 ----
 
-And finally, I never did figure out how to get the Windows prerequisites setup for the jdk8 version of GraalVM, so I only test on the jdk11 version.
+And finally, I never did figure out how to get the Windows prerequisites setup for the JDK8 version of GraalVM, so I only test on the JDK11 version.
 
 == Setup
-After checking out this project from github,
+After checking out this project from GitHub,
 
 1. Install JavaScript libraries and tools required by https://github.com/bensu/doo[doo] and https://github.com/thheller/shadow-cljs[shadow-cljs]:
 +
@@ -150,13 +150,14 @@ bb ./script/clj_watch.clj
 This launches https://github.com/lambdaisland/kaocha[kaocha] in watch mode.
 
 === ClojureScript
-For Clojurescript, I open a shell terminal window and run:
+For ClojureScript, I open a shell terminal window and run:
 
 ----
 bb ./script/cljs_watch.clj
 ----
 
-This launches https://figwheel.org/[fighweel main]. After initialization, your default web browser will automatically be opened with the figwheel auto-testing page.
+This launches https://figwheel.org/[fighweel main].
+After initialization, your default web browser will automatically be opened with the figwheel auto-testing page.
 
 == Docs
 
@@ -221,7 +222,8 @@ Current libs we test against:
 
 Additional libs are welcome.
 
-If you are troubleshooting locally, and want to only run specific tests, you can specify which ones you'd like to run. For example:
+If you are troubleshooting locally, and want to only run specific tests, you can specify which ones you'd like to run.
+For example:
 
 ----
 bb ./script/libs_tests.clj run cljfmt zprint
@@ -236,7 +238,6 @@ To check for outdated libs:
 bb ./script/libs_test.clj outdated
 ----
 
-
 Notes:
 
 * `libs_tests.clj` was developed on macOS and is run on CI under Linux only under JDK 11 only.
@@ -267,7 +268,8 @@ Note that checks are only done against installed `./node_modules`, so you may wa
 == Linting
 We use https://github.com/borkdude/clj-kondo[clj-kondo] for linting rewrite-clj source code.
 
-We fail the build on any lint violations. The ci server runs:
+We fail the build on any lint violations.
+The CI server runs:
 ----
 bb ./script/lint.clj
 ----
@@ -288,14 +290,12 @@ bb ./script/gen_api_diffs.clj
 Run this script manually on an as-needed basis, and certainly before any official release.
 Generated reports are to be checked in to version control.
 
-Reports are generated to `doc/generated/api-diffs/` and include manually written
-notes from `doc/diff-notes/`.
+Reports are generated to `doc/generated/api-diffs/` and include manually written notes from `doc/diff-notes/`.
 
-These reports are referenced from other docs, so if you rename files, be sure to
-search for links.
+These reports are referenced from other docs, so if you rename files, be sure to search for links.
 
-Makes use of https://github.com/lread/diff-apis[diff-apis]. Delete
-`.diff-apis/.cache` if you need a clean run.
+Makes use of https://github.com/lread/diff-apis[diff-apis].
+Delete `.diff-apis/.cache` if you need a clean run.
 
 
 == Cljdoc Preview
@@ -318,8 +318,7 @@ bb ./script/cljdoc_preview.clj start
 
 The local cljdoc server allows your ingested docs to be viewed 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.
+The start command also automatically checks docker hub for any updates so that our cljdoc preview matches the current production version of cljdoc.
 
 **Ingest Docs**
 
@@ -328,9 +327,8 @@ To ingest rewrite-clj API and docs into the local cljdoc database:
 bb ./script/cljdoc_preview.clj ingest
 ----
 
-The ingest command automatically publishes rewrite-clj to your local maven repository
-(cljdoc only works with published jars), but you'll have to remember to git commit and git push
-your changes before ingesting.
+The ingest command automatically publishes rewrite-clj to your local maven repository (cljdoc only works with published jars).
+You'll have to remember to git commit and git push your changes before ingesting.
 
 Repeat these steps any time you want to preview changes.
 
@@ -350,8 +348,7 @@ When you are done, you'll want to stop your docker container:
 bb ./script/cljdoc_preview.clj stop
 ----
 
-This will also delete temporary files created to support your preview session, most notably the local
-cljdoc database.
+This will also delete temporary files created to support your preview session, most notably the local cljdoc database.
 
 Note that NO cleanup is done for any rewrite-clj artifacts published to your local maven repository.
 

doc/03-faq.adoc

@@ -3,14 +3,17 @@
 == Documentation
 
 === What is the meaning of the ^:no-doc metadata?
-Our goal is to produce documentation for users of rewrite-clj. As such we only want to document public APIs.
+Our goal is to produce documentation for users of rewrite-clj.
+As such we only want to document public APIs.
 
-`^:no-doc` is a signal to https://cljdoc.org/[cljdoc] that source code should not be included in generated documentation. This metadata convention was introduced by https://github.com/weavejester/codox[codox].
+`^:no-doc` is a signal to https://cljdoc.org/[cljdoc] that source code should not be included in generated documentation.
+This metadata convention was introduced by https://github.com/weavejester/codox[codox].
 
 == What the markdown?
 Stand alone articles are written up in https://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc].
 
 1. it is a richer markup language than GitHub markdown.
 2. is supported by cljdoc.
 
-Our docstrings sometimes take advantage of https://commonmark.org/[CommonMark] which is supported by cljdoc for docstrings. GitHub uses CommonMark as part of of its markdown solution.
+Our docstrings sometimes take advantage of https://commonmark.org/[CommonMark] which is supported by cljdoc for docstrings.
+GitHub uses CommonMark as part of of its markdown solution.