notespace.v2.tutorial-test

Intro

This is a notespace – a namespace that is a sequence of notes. It is intented to be a tutorial about creating and using notespaces.

It is recommended to read this notespace alongside its rendered result.

Computing and rendering

To use notespace, require the namespace notespace.v2.note, bringing the symbols of the relevant note kinds to your own namespace using :refer. For example, if you want to use notes of kind :md, you may like to (require '[notespace.v2.note :refer [note-md]]). More about note kinds – below.

To see your rendered results with a live-reload experience, require the namespace notespace.v2.live-reload too. This will setup a live-reload server using Ring and Mirador, and will open a browser showing the rendered data.

To compute and render the whole notespace, call:

(notespace.v2.note/compute-this-notespace!)

To compute and rerender a certain note, call:

(notespace.v2.note/compute-note-at-line! line)

where line is one of the lines of the file that are taken by that note.

The notespace library is still experimental. In the (not unlikely) that something breaks, our current recommendation to reload the main notespace namespace, so that the broken state will overridden.

(require 'notespace.v2.note :reload)

Soon things will be more robust.

Editor integration.

It is handy to be able to invoke the API functions using commands (and keybindings) of your editor. All you need is to figure out how to make your editor call Clojure functions and pass them the current line of the cursor.

In Emacs, one may do this using the following Elisp code:

 (defun notespace/compute-note-at-line ()
  (interactive)
  (save-buffer)
  (cider-interactive-eval
   (concat "(notespace.v2.note/compute-note-at-line! "
           (number-to-string (count-lines 1 (point)))
           ")")
   (cider-interactive-eval-handler nil (point))
   nil
   nil)))

(defun notespace/compute-this-notespace ()
  (interactive)
  (save-buffer)
  (cider-interactive-eval
   "(notespace.v2.note/compute-this-notespace!)"
   (cider-interactive-eval-handler nil (point))
   nil
   nil)
  

Note kinds

We can have all kinds of different notes. The different kinds behave differently when rendered.

This one is a note of kind :md. When rendered, it renders as markdown and does not show the source string.

The following is a 'regular' note, of kind :code. When renders, it shows both the source code and the printed return value.

The following is a note of kind :void. It shows the source, but does not show the output.

The following is a note of kind :hiccup. It does not show the source, and renders the return value as hiccup.

Sometimes, we may want to render things as markdown or hiccup, but do want to see the source too. The following two kinds of notes are useful in those cases.

This is a note of kind :as-md. Shows the source, renders as markdown.

The following is a note of kind :as-hiccup. Shows the source, renders as hiccup.

Here is the summary of the note kinds we mentioned: (Sorry for this strange table. Markdown tables do not render properly at the moment.)

| kind | symbol | render source? | value-rendering |

| code | note | v | pretty printing |

| void | note-void | v | x |

| md | note-md | x | as markdown |

| as-md | note-as-md | v | as markdown |

| hiccup | note-hiccup | x | as hiccup |

| as-hiccup | note-as-hiccu | v | as hiccup |

Labels

In the definition of the following note, we begin with a keyword: :label-example. This keyword is called the label of the note, and it is not rendered. It creates a link to that note from the table-of-contents.

Tables

It may be handy to render data in interactive tables. We have some auxiliary functions to render this using the DataTables JS library.

Graphics

Graphics can be rendered as hiccup. Here is an example using SVG.

Tests

One may use the check function to create tests using arbitrar functions.