Add skeleton of functions page.

doc/modules/ROOT/nav.adoc

@@ -1,3 +1,4 @@
 * xref:intro.adoc[Introduction]
 * xref:values.adoc[Predefined Values]
 * xref:attrs.adoc[Attributes]
+* xref:funcs.adoc[Functions]

doc/modules/ROOT/pages/attrs.adoc

@@ -12,8 +12,8 @@ keywords that identify the attribute being configured, and whose
 values are what you want to use for that attribute.
 
 The specific attributes accepted by each function are described in the
-function documentation. Some attributes are used by the function
-itself, and some are passed along to the SVG to be come
+<<funcs#,function documentation>>. Some attributes are used by the
+function itself, and some are passed along to the SVG to be come
 https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute[SVG
 attributes] of the element you are drawing.
 
@@ -26,8 +26,9 @@ requiring you to build up the map explicitly. Drawing functions which
 accept attributes will process this notation for you.
 
 > If you are interested in the intricate details, attribute
-  expressions are interpreted by the function `eval-attribute-spec`
-  near the top of the
+  expressions are interpreted by the
+  <<funcs#eval-attribute-spec,function `eval-attribute-spec`>> near
+  the top of the
   https://github.com/Deep-Symmetry/bytefield-svg/blob/master/src/org/deepsymmetry/bytefield/core.cljs[source].
 
 === Raw Maps
@@ -50,7 +51,7 @@ sets>> of attributes, instead of a map you can pass the keyword that
 names them. For example, if you want to render some text in the same
 style normally used for drawing hexadecimal numbers, you can reference
 the attribute set named `:hex` as the second (attribute) argument to
-the `text` function:
+the <<funcs#text,`text` function>>:
 
 [source,clojure]
 (text "NUL" :hex)
@@ -60,8 +61,9 @@ looked up in the `named-attributes` table, and the corresponding value
 is used as the attributes to control the drawing.
 
 In addition to the predefined values that start out in that table, you
-can add your own named attribute definitions by calling the `defattrs`
-function, perhaps in a shared include file.
+can add your own named attribute definitions by calling the
+<<funcs#defattrs,`defattrs`>> function, perhaps in a shared include
+file.
 
 === Combining Attributes
 
@@ -95,7 +97,7 @@ takes up the space of four normal boxes:
 
 === No Attributes
 
-If you don't want to pass any attributes at all, you can either pass
+If you don’t want to pass any attributes at all, you can either pass
 an empty map, `{}`, or `nil` which is interpreted in the same way.
 This tells the function to use its default values and behaviors. But
 most functions which accept an attribute parameter also allow you to
@@ -136,8 +138,10 @@ these, as well as to add your own new sets).
 
 | |
 |:dotted |A line style for drawing dotted lines. Commonly used with
- borders, but you can use it when calling lower-level SVG line-drawing
- primitives too.
+ borders, but you can use it when calling the
+ <<funcs#draw-line,`draw-line` function>> and
+ https://github.com/liebke/analemma[lower-level SVG drawing
+ primitives] too.
 
 |:border-unrelated |The line styles for drawing the borders of boxes
  whose content is separate from the boxes around them (this uses the

doc/modules/ROOT/pages/funcs.adoc

@@ -0,0 +1,124 @@
+= Functions
+James Elliott <james@deepsymmetry.org>
+:icons: font
+:toc: preamble
+:experimental:
+
+This section describes the drawing functions that are the main purpose
+of `bytefield-svg`. They are designed to flexibly draw the elements
+you might need in a byte field diagram. But they are also intended to
+be combined with the functions in the Clojure
+https://clojure.github.io/clojure/[core library], and you can dive
+down to the https://github.com/liebke/analemma[Analemma SVG building
+functions] used by these functions if you need to draw something
+unique.
+
+> TODO: Consider providing some basic documentation for the Analemma
+  functions we export because the Analemma site is cryptic and
+  currently has broken links to the source.
+
+== append-svg
+
+> TODO: Document
+
+
+[defattrs]
+== defattrs
+
+> TODO: Document
+
+
+== draw-bottom
+
+> TODO: Document
+
+
+[draw-box]
+== draw-box
+
+> TODO: Document
+
+And here is an example of how to draw a box with a custom label function:
+
+[source,clojure]
+(draw-box (fn [left top width height]
+            (draw-line left top (+ left width) (+ top height))
+            (draw-line left (+ top height) (+ left width) top)))
+
+And here’s what it looks like repeated over a four-box row:
+
+[bytefield]
+----
+(def boxes-per-row 4)
+(def left-margin 1)
+(draw-column-headers)
+(doseq [_ (range 4)]
+  (draw-box (fn [left top width height]
+              (draw-line left top (+ left width) (+ top height))
+              (draw-line left (+ top height) (+ left width) top))))
+----
+
+
+[draw-boxes]
+== draw-boxes
+
+> TODO: Document
+
+
+[draw-column-headers]
+== draw-column-headers
+
+> TODO: Document
+
+
+[draw-gap]
+== draw-gap
+
+> TODO: Document
+
+[draw-line]
+== draw-line
+
+> TODO: Document
+
+[draw-related-boxes]
+== draw-related-boxes
+
+> TODO: Document
+
+[draw-row-header]
+== draw-row-header
+
+> TODO: Document
+
+[eval-attribute-spec]
+== eval-attribute-spec
+
+> TODO: Document
+
+
+[hex-text]
+== hex-text
+
+> TODO: Document
+
+
+[next-row]
+== next-row
+
+> TODO: Document
+
+
+[text]
+== text
+
+> TODO: Document
+
+
+[tspan]
+== tspan
+
+> TODO: Document
+
+
+include::partial$Footer.adoc[]

doc/modules/ROOT/pages/intro.adoc

@@ -1,7 +1,6 @@
 = Introduction
 James Elliott <james@deepsymmetry.org>
 :icons: font
-:toc: preamble
 :experimental:
 
 This tool was created to enable the porting of a pair of large LaTeX
@@ -27,13 +26,25 @@ https://clojure.org/reference/reader#_sets[sets]), and compact way of
 representing them in source, are a big part of why this worked so
 well.
 
-TIP: But this means that to get really productive with
+[TIP]
+====
+But this means that to get really productive with
 `bytefield-svg`, you are going to need to
 https://clojure.org/guides/getting_started[learn] at least a little
-Clojure. The https://github.com/borkdude/sci[sci] interpreter offers a
-large subset of the language, with the omission of host interop
-features and a few functions which would be dangerous in a shared
-hosting environment.
+Clojure.
+
+Here is an introduction to the
+https://clojure.org/guides/learn/syntax[syntax], a
+https://clojure.org/api/cheatsheet[cheat sheet] and some help
+deciphering what will initially look like strange
+https://clojure.org/guides/weird_characters[characters] that are hard
+to search for on the web.
+
+The https://github.com/borkdude/sci[sci] interpreter that runs your
+`bytefield-svg` source offers a large subset of the language, with the
+omission of host interop features and a few functions which would be
+dangerous in a shared hosting environment.
+====
 
 [[drawing-model]]
 ## The Drawing Model
@@ -47,9 +58,9 @@ column and row headers to help readers keep track of byte addresses.
 Reasonable defaults are provideded, but everything is very
 configurable. Before diving into those details, it will help to look
 at some concrete examples. The main function you’ll use for drawing
-byte boxes is `draw-box`. By default it creates a box that represents
-one byte. So if we create a diagram with only `(draw-box 0)` as its
-content, here is what we get:
+byte boxes is <<funcs#draw-box,`draw-box`>>. By default it creates a
+box that represents one byte. So if we create a diagram with only
+`(draw-box 0)` as its content, here is what we get:
 
 [bytefield]
 ----
@@ -125,9 +136,9 @@ in hexadecimal.
 
 For situations where you have a series of bytes that you want to
 convey are part of a related structure, you can use the
-`draw-related-boxes` function. It takes a sequence as its first
-argument, and does the looping for you, in addition to using dashed
-borders inside the related group:
+<<funcs#draw-related-boxes,`draw-related-boxes`>> function. It takes a
+sequence as its first argument, and does the looping for you, in
+addition to using dashed borders inside the related group:
 
 [source,clojure]
 (draw-column-headers)
@@ -146,9 +157,9 @@ it is drawn as a label. And `draw-box` takes a second argument after
 the box content, which is a map of attributes, identified by keyword,
 that modify the box. The `:span` attribute controls how many bytes
 wide the box should be, with a default value of 1. Putting that
-together, and using a new `draw-gap` function which is designed to
-communicate variable-length structures, we can draw something like
-this:
+together, and using a new <<funcs#draw-gap,`draw-gap`>> function which
+is designed to communicate variable-length structures, we can draw
+something like this:
 
 [source,clojure]
 (draw-column-headers)
@@ -178,30 +189,7 @@ boxes, and that’s how many hexadecimal digits fit in two bytes.
 
 With that introduction, we’re ready to start exploring all the
 <<values#,values that can be configured>>, and the full details of the
-functions that you can use for drawing.
-
-## Diagram Drawing Functions
-
-> TODO: Document, including links to relevant Analemma docs.
-
-And here is an example of how to draw a box with a custom label function:
-
-[source,clojure]
-(draw-box (fn [left top width height]
-            (draw-line left top (+ left width) (+ top height))
-            (draw-line left (+ top height) (+ left width) top)))
+<<funcs#,functions that you can use for drawing>>.
 
-And here’s what it looks like repeated over a four-box row:
-
-[bytefield]
-----
-(def boxes-per-row 4)
-(def left-margin 1)
-(draw-column-headers)
-(doseq [_ (range 4)]
-  (draw-box (fn [left top width height]
-              (draw-line left top (+ left width) (+ top height))
-              (draw-line left (+ top height) (+ left width) top))))
-----
 
 include::partial$Footer.adoc[]