Document draw-column-headers

While doing so, I realized the way I was doing headers for big-endian
tables was way too esoteric for the kinds of beginners who use this
library, so I also changed the implementation to offer a much cleaner
way to accomplish that, and showed examples of how to use it. This
will require a new release of the node module.

Plus, the function didn't actually have a zero-arity version; it must
be a feature of the `sci` interpreter that was letting me get away
with calling it that way!

doc/modules/ROOT/pages/funcs.adoc

@@ -333,7 +333,110 @@ drawing of each box.
 [[draw-column-headers]]
 == draw-column-headers
 
-> TODO: Document
+Draws the row of byte offsets at the top of the diagram, making it
+easy to visually determine the addresses of boxes below. This is not
+done until you ask for it, to give you an opportunity to first adjust
+<<values#,predefined values>> that will affect the result.
+
+.Arguments
+[source,clojure]
+----
+[]
+[attr-spec]
+----
+
+If you supply `attr-spec`, it is parsed as an
+<<attrs#attribute-expressions,attribute expression>> that you can use
+to further customize the column headers (in ways that don’t affect the
+structure of the rest of the diagram):
+
+=== Column Header Attributes
+
+[cols="2m,2m,6"]
+|===
+|Attribute |Default Value |Meaning
+
+|:font-family |"Courier New, monospace" |The typeface used to draw the
+ column headers.
+
+|:font-size |11 |Controls the size of the column headers.
+
+|:height |14 |The amount of vertical space allocated to the column
+ headers.
+
+|:labels |<<values#column-labels,column-labels>> |A sequence whose
+ elements are used as the actual text of each column header in order.
+ You might want to change this if you are drawing a bit field, where
+ the high order bits come first, as shown in the examples below.
+|===
+
+With no redefinitions of predefined values and no attribute
+expression, this generates headers for a row of sixteen bytes as
+hexadecimal digits:
+
+[source,clojure]
+(draw-column-headers)
+
+[bytefield]
+----
+(draw-column-headers)
+----
+
+If you are dealing with big-endian values, you can reverse the
+`column-labels` predefined value that is used to generate the
+labels, and pass it in as the `:labels` attribute:
+
+[source,clojure]
+(draw-column-headers {:labels (reverse column-labels)})
+
+[bytefield]
+----
+(draw-column-headers {:labels (reverse column-labels)})
+----
+
+If you want to draw a diagram with fewer columns, redefine
+`boxes-per-row` before calling this:
+
+[source,clojure]
+(def boxes-per-row 8)
+(draw-column-headers)
+
+[bytefield]
+----
+(def boxes-per-row 8)
+(draw-column-headers)
+----
+
+But note that if you want to both reduce the number of columns _and_
+reverse the headers, you need to do a little more than combining these
+two steps, because that simple approach results in the following
+headers:
+
+[source,clojure]
+(def boxes-per-row 8)
+(draw-column-headers {:labels (reverse column-labels)})
+
+[bytefield]
+----
+(def boxes-per-row 8)
+(draw-column-headers {:labels (reverse column-labels)})
+----
+
+...Which makes sense, if you think about it: there are sixteen values
+in `column-labels`, so reversing it gives you the top eight. Luckily
+the solution is straightforward, just use the
+https://clojuredocs.org/clojure.core/take[Clojure’s `take`] function
+to get the first eight labels _before_ calling `reverse`:
+
+[source,clojure]
+(def boxes-per-row 8)
+(draw-column-headers {:labels (reverse (take 8 column-labels))})
+
+[bytefield]
+----
+(def boxes-per-row 8)
+(draw-column-headers {:labels (reverse (take 8 column-labels))})
+----
 
 
 [[draw-gap]]

doc/modules/ROOT/pages/values.adoc

@@ -16,7 +16,7 @@ and coordinates] in SVG are interpreted as “user units”, which default
 in these diagrams to pixels (as if you had added `px` after the
 number).
 
-[cols="1m,1m,4"]
+[cols="1m,1m,3"]
 |===
 |Variable |Default Value |Purpose
 
@@ -36,15 +36,27 @@ number).
  sure the box boundaries don’t get clipped. You can make it bigger if
  you want to draw custom content there.
 
+| | |
+
 |box-width |40 | How much horizontal space each box takes up.
 
 |boxes-per-row |16 |How many boxes are drawn on a row before moving to
  the next row. The default is 16, so that the hexadecimal row labels
  increment by `10` and the diagram is a nice width. If you are drawing
  smaller structures you can reduce this.
 
+[[column-labels]]
+|column-labels |["0" "1" ... "f"] |A sequence whose elements are used
+ as the actual text of each column header in order. Although you can
+ change this globally by redefining this value, it is more common to
+ simply pass a different sequence (often by transforming this one) as
+ the `:labels` attribute when calling
+ <<funcs#draw-column-headers,`draw-column-headers`>>.
+
 |row-height |30 | How much vertical space a row of boxes takes up.
 
+| | |
+
 |named-attributes | |See the <<attrs#predefined-attributes,next section>>.
 
 |row-header-fn |default-row-header-fn |The function that is called to

src/org/deepsymmetry/bytefield/core.cljs

@@ -122,7 +122,7 @@
    (draw-column-headers nil))
   ([attr-spec]
    (let [{:keys [labels height font-size font-family]
-          :or   {labels      (str/split "0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f" #",")
+          :or   {labels      @('column-labels @*globals*)
                  height      14
                  font-size   11
                  font-family "Courier New, monospace"}
@@ -645,6 +645,7 @@
     'bottom-margin 1  ; Space at bottom, currently just enough to avoid clipping bottom box edges.
     'box-width     40 ; How much room each byte (or bit) box takes up.
 
+    'column-labels (str/split "0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f" #",") ; The default column headers.
     'boxes-per-row 16 ; How many individual byte/bit boxes fit on each row.
     'row-height    30 ; The height of a standard row of boxes.