docs: review, fix link, clarify

Author: lread

doc/example.adoc

@@ -1,9 +1,12 @@
 = AsciiDoc test-doc-blocks Example
 :toc:
 
+If you are writing your docs in AsciiDoc, read on.
+If you are writing your docs in CommonMark, you'll want to read link:/doc/example.md[CommonMark test-doc-blocks Example] instead.
+
 Test-doc-blocks will find Clojure source code blocks in your `.adoc` files and generate tests for them.
 
-You tell test-doc-blocks which files to scan on the link:/01-user-guide.adoc#command-line[command line].
+You tell test-doc-blocks which files to scan on the link:/doc/01-user-guide.adoc#command-line[command line].
 
 == The Basics
 Test-doc-blocks generates a test for each Clojure code block.

doc/example.md

@@ -1,9 +1,12 @@
 CommonMark test-doc-blocks Example
 ==========
 
+If you are writing your docs in CommonMark, read on.
+If you are writing your docs in AsciiDoc, you'll want to read [AsciiDoc test-doc-blocks Example](/doc/example.adoc) instead.
+
 Test-doc-blocks will find Clojure source code blocks in your docstrings and `.md` files and generate tests for them.
 
-You tell test-doc-blocks which files to scan on the [command line](/01-user-guide.adoc#command-line).
+You tell test-doc-blocks which files to scan on the [command line](/doc/01-user-guide.adoc#command-line).
 
 The Basics
 --

test-resources/expected/test-doc-blocks/test/example_adoc_cljs_test.cljs

@@ -6,7 +6,7 @@
   (:import goog.events.EventType))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 242 - Specifying The Platform - :platform"
+  (clojure.test/testing  "doc/example.adoc - line 245 - Specifying The Platform - :platform"
 ;; this code block will generate a test under example-adoc-cljs-test ns to a .cljs file
 
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_inline_ns_test.cljc

@@ -10,7 +10,7 @@
   (:import #?@(:clj [java.util.List java.util.Queue java.util.Set] :cljs [goog.math.Long goog.math.Vec2 goog.math.Vec3])))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 364 - Inline requires and imports"
+  (clojure.test/testing  "doc/example.adoc - line 367 - Inline requires and imports"
 ;; Stick the basics for requires, shorthand notation isn't supported
 
 ;; Some examples:

test-resources/expected/test-doc-blocks/test/example_adoc_inline_refer_clojure_test.cljc

@@ -7,7 +7,7 @@
             [clojure.edn :refer [read-string]]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 394 - Inline refer-clojure"
+  (clojure.test/testing  "doc/example.adoc - line 397 - Inline refer-clojure"
 ;; a contrived example that uses uses clojure.edn/read-string in place of clojure.core/read-string
 ;; and excludes clojure.core/for
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_new_ns/ns1_test.cljc

@@ -6,7 +6,7 @@
             [clojure.string :as string]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 210 - Specifying Test Namespace - :test-ns"
+  (clojure.test/testing  "doc/example.adoc - line 213 - Specifying Test Namespace - :test-ns"
 ;; this code block will generate tests under example-adoc-new-ns.ns1-test
 
 nil

test-resources/expected/test-doc-blocks/test/example_adoc_new_ns_test.cljc

@@ -5,7 +5,7 @@
             #?(:clj lread.test-doc-blocks.runtime)))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 194 - Specifying Test Namespace - :test-ns"
+  (clojure.test/testing  "doc/example.adoc - line 197 - Specifying Test Namespace - :test-ns"
 ;; this code block will generate tests under example-adoc-new-ns-test
 
 (clojure.test/is (= '8 (* 2 4)))))

test-resources/expected/test-doc-blocks/test/example_adoc_out_test.clj

@@ -4,7 +4,7 @@
             lread.test-doc-blocks.runtime))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 61 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 64 - The Basics"
 ;; A snippit of Clojure where we check result, stderr and stdout
 (let [[actual actual-out actual-err] (lread.test-doc-blocks.runtime/eval-capture (do
   (println "To out I go")

test-resources/expected/test-doc-blocks/test/example_adoc_out_test.cljs

@@ -4,7 +4,7 @@
             [lread.test-doc-blocks.runtime :include-macros]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 74 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 77 - The Basics"
 ;; And the same idea for ClojureScript
 (let [[actual actual-out actual-err] (lread.test-doc-blocks.runtime/eval-capture (do
   (println "To out I go")

test-resources/expected/test-doc-blocks/test/example_adoc_test.cljc

@@ -9,19 +9,19 @@
             [clojure.string :as string]))
 
 (clojure.test/deftest block-0001
-  (clojure.test/testing  "doc/example.adoc - line 15 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 18 - The Basics"
 ;; Some valid Clojure code here
 
 ; test-doc-blocks dummy assertion to appease tools that fail on no assertions
 (clojure.test/is (= '"dummy" "dummy"))))
 
 (clojure.test/deftest block-0002
-  (clojure.test/testing  "doc/example.adoc - line 27 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 30 - The Basics"
 ;; test-doc-block will generate an assertion to verify (+ 1 2 3) evaluates to the expected 6
 (clojure.test/is (= '6 (+ 1 2 3)))))
 
 (clojure.test/deftest block-0003
-  (clojure.test/testing  "doc/example.adoc - line 36 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 39 - The Basics"
 ;; test-doc-blocks will generate an assertion to verify (+ 1 2 3 4) evaluates to the expected 10
 (clojure.test/is (= '10 (+ 1 2 3 4)))
 ;; it understands that Clojure and ClojureScript can evaluate differently
@@ -36,7 +36,7 @@
   (clojure.test/is (= ["is this right?" "or not?"] (clojure.string/split-lines actual-out))))))
 
 (clojure.test/deftest block-0004
-  (clojure.test/testing  "doc/example.adoc - line 89 - The Basics"
+  (clojure.test/testing  "doc/example.adoc - line 92 - The Basics"
 (->> "here we are only checking that our code will run"
      reverse
      reverse
@@ -46,7 +46,7 @@
 (clojure.test/is (= '"dummy" "dummy"))))
 
 (clojure.test/deftest block-0005
-  (clojure.test/testing  "doc/example.adoc - line 151 - Wrap Test in a Reader Conditional - :reader-cond"
+  (clojure.test/testing  "doc/example.adoc - line 154 - Wrap Test in a Reader Conditional - :reader-cond"
 #?(:clj
 (do
 ;; This code block will be wrapped in a #?(:clj (do ...))
@@ -59,7 +59,7 @@ nil
 (clojure.test/is (= '"dummy" "dummy"))))
 
 (clojure.test/deftest block-0006
-  (clojure.test/testing  "doc/example.adoc - line 163 - Wrap Test in a Reader Conditional - :reader-cond"
+  (clojure.test/testing  "doc/example.adoc - line 166 - Wrap Test in a Reader Conditional - :reader-cond"
 #?(:cljs
 (do
 ;; This code block will be wrapped in a #?(:cljs (do ...))
@@ -71,18 +71,18 @@ nil
 (clojure.test/is (= '"dummy" "dummy"))))
 
 (clojure.test/deftest block-0007
-  (clojure.test/testing  "doc/example.adoc - line 173 - Wrap Test in a Reader Conditional - :reader-cond"
+  (clojure.test/testing  "doc/example.adoc - line 176 - Wrap Test in a Reader Conditional - :reader-cond"
 ;; And our generic cljc code:
 (clojure.test/is (= '[1 2 3] (read-string "[1 2 3]")))))
 
 (clojure.test/deftest ^:testing-meta123 block-0008
-  (clojure.test/testing  "doc/example.adoc - line 273 - Specifying Metadata - :meta"
+  (clojure.test/testing  "doc/example.adoc - line 276 - Specifying Metadata - :meta"
 ;; this code block will generate a test with metadata {:testing-meta123 true}
 
 (clojure.test/is (= '[[:a 1]] (into [] {:a 1})))))
 
 (clojure.test/deftest ^{:testing-meta123 "a-specific-value", :testing-meta789 :yip} block-0009
-  (clojure.test/testing  "doc/example.adoc - line 286 - Specifying Metadata - :meta"
+  (clojure.test/testing  "doc/example.adoc - line 289 - Specifying Metadata - :meta"
 ;; this code block will generate a test with metadata:
 ;;  {:testing-meta123 "a-specific-value" :testing-meta789 :yip}
 
@@ -93,32 +93,32 @@ nil
    ["oh" "my" "goodness"])))))
 
 (clojure.test/deftest block-0010
-  (clojure.test/testing  "doc/example.adoc - line 326 - Section Titles"
+  (clojure.test/testing  "doc/example.adoc - line 329 - Section Titles"
 nil
 
 (clojure.test/is (= '"well!how!about!that" (string/join "!" ["well" "how" "about" "that"])))))
 
 (clojure.test/deftest block-0011
-  (clojure.test/testing  "doc/example.adoc - line 342 - Support for CommonMark Code Block Syntax"
+  (clojure.test/testing  "doc/example.adoc - line 345 - Support for CommonMark Code Block Syntax"
 nil
 
 (clojure.test/is (= '{1 :a, 2 :b} (set/map-invert {:a 1 :b 2})))))
 
 (clojure.test/deftest block-0012
-  (clojure.test/testing  "doc/example.adoc - line 430 - Test Run Order"
+  (clojure.test/testing  "doc/example.adoc - line 433 - Test Run Order"
 (defn fn-block1 [] (+ 1 2 3))
 
 ; test-doc-blocks dummy assertion to appease tools that fail on no assertions
 (clojure.test/is (= '"dummy" "dummy"))))
 
 (clojure.test/deftest block-0013
-  (clojure.test/testing  "doc/example.adoc - line 436 - Test Run Order"
+  (clojure.test/testing  "doc/example.adoc - line 439 - Test Run Order"
 (def var-block2 (+ 4 5 6))
 
 (clojure.test/is (= '21 (+ (fn-block1) var-block2)))))
 
 (clojure.test/deftest block-0014
-  (clojure.test/testing  "doc/example.adoc - line 445 - Test Run Order"
+  (clojure.test/testing  "doc/example.adoc - line 448 - Test Run Order"
 (clojure.test/is (= '100 (+ (fn-block1) var-block2 79)))))
 
 (defn test-ns-hook [] (block-0001) (block-0002) (block-0003) (block-0004) (block-0005) (block-0006) (block-0007) (block-0008) (block-0009) (block-0010) (block-0011) (block-0012) (block-0013) (block-0014))