Merge pull request #9 from carpentry-org/veit/new-style-docs

fix: use new style docs to avoid unwanted code blocks

Author: scolsen

docs/Dimensional.html

@@ -72,14 +72,11 @@ <h3 id="tabulate">
                     (tabulate f)
                 </pre>
                 <p class="doc">
-                    <pre><code>Tabulate maps a `lookup` function (any function that takes an `Index` as an
-argument) over the positions of a sized functor.
-
-`(tabulate (lookup f))= (id f)`
-
-To make this function useful, one often needs to use an overarching context
-to ensure the resulting functor is sized appropriately. 
-</code></pre>
+                    <p>Tabulate maps a <code>lookup</code> function (any function that takes an <code>Index</code> as an
+argument) over the positions of a sized functor.</p>
+<p><code>(tabulate (lookup f))= (id f)</code></p>
+<p>To make this function useful, one often needs to use an overarching context
+to ensure the resulting functor is sized appropriately.</p>
 
                 </p>
             </div>
@@ -99,17 +96,12 @@ <h3 id="transpose">
                     (transpose f)
                 </pre>
                 <p class="doc">
-                    <pre><code>Transpose takes a sized functor whose inhabitants are sized functors and
-effectively swaps their sizes; it is equivalent to matrix transposition.
-
-For example, given a Vector of Size 3 of Vectors of Size 2
-
-`(Vector [(Vector [1 2]) (Vector [3 4]) (Vector [5 6])])`
-
-transpose will return a Vector of size 2 of Vectors of size 3:
-
-`(Vector [(Vector [1 3 5]) (Vector [2 4 6])])`
-</code></pre>
+                    <p>Transpose takes a sized functor whose inhabitants are sized functors and
+effectively swaps their sizes; it is equivalent to matrix transposition.</p>
+<p>For example, given a Vector of Size 3 of Vectors of Size 2</p>
+<p><code>(Vector [(Vector [1 2]) (Vector [3 4]) (Vector [5 6])])</code></p>
+<p>transpose will return a Vector of size 2 of Vectors of size 3:</p>
+<p><code>(Vector [(Vector [1 3 5]) (Vector [2 4 6])])</code></p>
 
                 </p>
             </div>

docs/Hompair.html

@@ -115,12 +115,9 @@ <h3 id="empty?">
                     (empty? pair)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns false. Hompairs may never be empty by definition.
-
-```
-(empty? &amp;(Hompair.of 1 1))
+                    <p>Returns false. Hompairs may never be empty by definition.</p>
+<pre><code>(empty? &amp;(Hompair.of 1 1))
 =&gt; false
-```
 </code></pre>
 
                 </p>
@@ -161,12 +158,9 @@ <h3 id="len">
                     (len pair)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns the length of a Hompair.
-
-```
-(len (Hompair.of 1 1))
+                    <p>Returns the length of a Hompair.</p>
+<pre><code>(len (Hompair.of 1 1))
 =&gt; 2
-```
 </code></pre>
 
                 </p>
@@ -225,13 +219,10 @@ <h3 id="nth">
                     (nth pair index)
                 </pre>
                 <p class="doc">
-                    <pre><code>Retrieves the nth value from a Hompair using the int value of `index`. 
-If n is greater than or equal 1, returns the second member of the Hompair.
-
-```
-(nth &amp;(Hompair 1 2) (Index.init 0))
+                    <p>Retrieves the nth value from a Hompair using the int value of <code>index</code>.
+If n is greater than or equal 1, returns the second member of the Hompair.</p>
+<pre><code>(nth &amp;(Hompair 1 2) (Index.init 0))
 =&gt; 1
-```
 </code></pre>
 
                 </p>
@@ -252,12 +243,9 @@ <h3 id="of">
                     (of x y)
                 </pre>
                 <p class="doc">
-                    <pre><code>Constructs a new Hompair from values `x` and `y`.
-
-```
-(Hompair.of 2 4)
+                    <p>Constructs a new Hompair from values <code>x</code> and <code>y</code>.</p>
+<pre><code>(Hompair.of 2 4)
 =&gt; (Hompair 2 4)
-```
 </code></pre>
 
                 </p>
@@ -336,12 +324,9 @@ <h3 id="replicate">
                     (replicate x)
                 </pre>
                 <p class="doc">
-                    <pre><code>Creates a new Hompair with `x` as both of its members.
-
-```
-(Hompair.replicate 1)
+                    <p>Creates a new Hompair with <code>x</code> as both of its members.</p>
+<pre><code>(Hompair.replicate 1)
 =&gt; (Hompair 1 1)
-```
 </code></pre>
 
                 </p>
@@ -482,12 +467,9 @@ <h3 id="swap">
                     (swap pair)
                 </pre>
                 <p class="doc">
-                    <pre><code>Swaps the position of each value in a Hompair.
-
-```
-(swap &amp;(Hompair.of 1 2))
+                    <p>Swaps the position of each value in a Hompair.</p>
+<pre><code>(swap &amp;(Hompair.of 1 2))
 =&gt; (Hompair 2 1)
-```
 </code></pre>
 
                 </p>
@@ -548,8 +530,7 @@ <h3 id="zero">
                     (zero)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns a Hompair of the zero values of a given type.
-</code></pre>
+                    <p>Returns a Hompair of the zero values of a given type.</p>
 
                 </p>
             </div>

docs/Size.html

@@ -215,11 +215,9 @@ <h3 id="size">
                     (size n)
                 </pre>
                 <p class="doc">
-                    <pre><code>Size types can be quite a pain to type out in full, as the rely on significant nesting.
-
-The size macro generates an appropriate Size based on an integer value, and
-may be used to generate a size type in functions signatures and macros.
-</code></pre>
+                    <p>Size types can be quite a pain to type out in full, as the rely on significant nesting.</p>
+<p>The size macro generates an appropriate Size based on an integer value, and
+may be used to generate a size type in functions signatures and macros.</p>
 
                 </p>
             </div>

docs/Vector.html

@@ -134,8 +134,7 @@ <h3 id="empty">
                     (empty)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns an empty Vector
-</code></pre>
+                    <p>Returns an empty Vector</p>
 
                 </p>
             </div>
@@ -155,8 +154,7 @@ <h3 id="head">
                     (head v)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns the first element of a Vector.
-</code></pre>
+                    <p>Returns the first element of a Vector.</p>
 
                 </p>
             </div>
@@ -215,8 +213,7 @@ <h3 id="last">
                     (last v)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns the last element of a Vector.
-</code></pre>
+                    <p>Returns the last element of a Vector.</p>
 
                 </p>
             </div>
@@ -255,9 +252,8 @@ <h3 id="map">
                     (map f v)
                 </pre>
                 <p class="doc">
-                    <pre><code> Maps a function `f` over all the elements of a Vector and returns a new
- Vector containing the results.
-</code></pre>
+                    <p>Maps a function <code>f</code> over all the elements of a Vector and returns a new
+Vector containing the results.</p>
 
                 </p>
             </div>
@@ -277,14 +273,11 @@ <h3 id="nth">
                     (nth v ix)
                 </pre>
                 <p class="doc">
-                    <pre><code>Retrieves the nth element of a Vector using a given `Index`.
-
-The given `Index` must have a `Size` equivalent to the `Vector`'s size in
-its first position (the bound position).
-
-If the `Index`'s Int value exceeds the length of the Vector, this
-function will return the last element of the Vector.
-</code></pre>
+                    <p>Retrieves the nth element of a Vector using a given <code>Index</code>.</p>
+<p>The given <code>Index</code> must have a <code>Size</code> equivalent to the <code>Vector</code>'s size in
+its first position (the bound position).</p>
+<p>If the <code>Index</code>'s Int value exceeds the length of the Vector, this
+function will return the last element of the Vector.</p>
 
                 </p>
             </div>
@@ -304,8 +297,7 @@ <h3 id="of">
                     (of values)
                 </pre>
                 <p class="doc">
-                    <pre><code>Creates a new Vector from the contents of an Array literal.
-</code></pre>
+                    <p>Creates a new Vector from the contents of an Array literal.</p>
 
                 </p>
             </div>
@@ -364,8 +356,7 @@ <h3 id="push">
                     (push x v)
                 </pre>
                 <p class="doc">
-                    <pre><code>Adds an element to the end of a Vector, returning a new Vector.
-</code></pre>
+                    <p>Adds an element to the end of a Vector, returning a new Vector.</p>
 
                 </p>
             </div>
@@ -424,8 +415,7 @@ <h3 id="tail">
                     (tail v)
                 </pre>
                 <p class="doc">
-                    <pre><code>Returns all but the first element of a Vector as a new Vector.
-</code></pre>
+                    <p>Returns all but the first element of a Vector as a new Vector.</p>
 
                 </p>
             </div>
@@ -445,8 +435,7 @@ <h3 id="to-array">
                     (to-array v)
                 </pre>
                 <p class="doc">
-                    <pre><code>Converts a Vector to an Array.
-</code></pre>
+                    <p>Converts a Vector to an Array.</p>
 
                 </p>
             </div>
@@ -466,8 +455,7 @@ <h3 id="zip">
                     (zip f v v1)
                 </pre>
                 <p class="doc">
-                    <pre><code>Combines two Vectors using a binary function `f`.
-</code></pre>
+                    <p>Combines two Vectors using a binary function <code>f</code>.</p>
 
                 </p>
             </div>

docs/index-type.html

@@ -135,10 +135,8 @@ <h3 id="index-to-int">
                     (index-to-int ix)
                 </pre>
                 <p class="doc">
-                    <pre><code>Converts an index to a safe integer value, for sized functor element access.
-
-The integer value will always be lesser than the `Size` encoded in the `Index`.
-</code></pre>
+                    <p>Converts an index to a safe integer value, for sized functor element access.</p>
+<p>The integer value will always be lesser than the <code>Size</code> encoded in the <code>Index</code>.</p>
 
                 </p>
             </div>

impl/vector.carp

@@ -20,9 +20,9 @@
     (fn [i]
       (Vector.nth &v i)))
 
-   (doc map "
-     Maps a function `f` over all the elements of a Vector and returns a new
-     Vector containing the results.")
+   (doc map
+     "Maps a function `f` over all the elements of a Vector and returns a new "
+     "Vector containing the results.")
    (implements smap map)
    (sig map (Fn [(Ref (Fn [a] b)) (Ref (Vector (Size n) a))] (Vector (Size n) b)))
    (defn map [f v]

src/dimensional.carp

@@ -7,28 +7,28 @@
 (definterface smap (Fn [(Ref (Fn [a] b)) (Ref (f s a))] (f s b)))
 
 (defmodule Dimensional
-  (doc tabulate "
-    Tabulate maps a `lookup` function (any function that takes an `Index` as an
-    argument) over the positions of a sized functor.
-
-    `(tabulate (lookup f))= (id f)`
-
-    To make this function useful, one often needs to use an overarching context
-    to ensure the resulting functor is sized appropriately. ")
+  (doc tabulate
+    "Tabulate maps a `lookup` function (any function that takes an `Index` as an "
+    "argument) over the positions of a sized functor."
+    ""
+    "`(tabulate (lookup f))= (id f)`"
+    ""
+    "To make this function useful, one often needs to use an overarching context "
+    "to ensure the resulting functor is sized appropriately.")
   (defn tabulate [f]
     (smap f &(positions)))
 
-  (doc transpose "
-    Transpose takes a sized functor whose inhabitants are sized functors and
-    effectively swaps their sizes; it is equivalent to matrix transposition.
-
-    For example, given a Vector of Size 3 of Vectors of Size 2
-
-    `(Vector [(Vector [1 2]) (Vector [3 4]) (Vector [5 6])])`
-
-    transpose will return a Vector of size 2 of Vectors of size 3:
-
-    `(Vector [(Vector [1 3 5]) (Vector [2 4 6])])`")
+(doc transpose
+  "Transpose takes a sized functor whose inhabitants are sized functors and "
+  "effectively swaps their sizes; it is equivalent to matrix transposition."
+  ""
+  "For example, given a Vector of Size 3 of Vectors of Size 2"
+  ""
+  "`(Vector [(Vector [1 2]) (Vector [3 4]) (Vector [5 6])])`"
+  ""
+  "transpose will return a Vector of size 2 of Vectors of size 3:"
+  ""
+  "`(Vector [(Vector [1 3 5]) (Vector [2 4 6])])`")
   (sig transpose (Fn [(Ref (f (Size n) (g (Size m) a)))] (g (Size m) (f (Size n) a))))
   (defn transpose [f]
     (tabulate &(fn [i] (smap &(fn [x] ((lookup x) i)) f))))