Screedcast

A highly un-configurable library for generating coding screencasts

Setup

Leiningen/Boot

[com.sagevisuals/screedcast "1"]

Clojure CLI/deps.edn

com.sagevisuals/screedcast {:mvn/version "1"}

Require

(require '[screedcast.core :refer [generate-all-screencasts]])

Introduction

Software documentation ought to have lots of code examples. Because some people learn better by watching audio-visual screencasts, those screencasts ought to have lots of code examples, too. Or, perhaps someone is considering a library, but would prefer to casually watch and listen to a screencast with a cup of tea instead of wading through pages and pages of dry text.

A standard slideshow presentation does not display code examples in an audience-friendly manner. While they may offer animations for transitioning from one slide to the next, they don't have any particular awareness of text that represents code. Displaying a mass of code can be visually overwhelming, and it's difficult for people in the audience to focus on what the speaker is dicussing. One tactic is to progressively reveal examples to keep people's attention focused on the moment's topic. Typical slideshow software does not facilitate this.

And standard slideshow presentation software does not make it straightforward include code examples. We must write the examples in the code editor, evaluate it, then copy-paste the entire glob into the slideshow. If we want to change a code example, we must delete it, and start the dance all over again.

Screedcast is a library for generating a screencast with evaluated Clojure code examples. Except for the source file directories and the output file directories, there are almost no settings to be adjusted. Take it as it is.

Screencasts are authored in hiccup-dialect html. A utility function inserts a minuscule amount of javascript/css around Clojure code examples. When clicked/tapped, the screencast gently reveals the expression's value. Code examples are easily adjusted directly inside the document, the functions are always up-to-date with the library, and the screencast reveals the code examples in a manner that focuses the audience's attention.

Usage

Overview

We write a screencast, which is, at the bottom, Clojure code in .clj files. The code examples are straight Clojure, while the surrounding text, formatting, and document organization are hiccup forms. Then, we create an options file, that tells Screedcast where to find the files and where to send the output html files. Finally, we tell Screedcast to compile the hiccup forms into html. Those html files are viewable in any modern web browser. When rendered by a web browser, clicking/tapping on a Clojure expression triggers a dom event that toggles the visibility of expression's evaluation.

Detailed usage

Complete the setup.
Write the presentation in hiccup/html. Each episode section is formatted like this.
```
[:body
  (panel ❬hiccup content❭)
  ...]
```
The panel function is convenience utility automatically creates the hiccup required for a header, footer, page-numbering, etc.

When we wish to create a code example, we use the following pattern.
```
(prettyfy-form-prettyfy-eval "(inc 99)")
```
Notice that we do not insert a 100. prettyfy-form-prettyfy-eval does that for us during compilation. If, while writing the screencast, we'd like to know what the expression evaluates to, put the cursor right before the closing quotation marks and eval-last-sexp.

See also a sibling project's usage for a few more tips.

Screedcast also includes a trio of css helpers.
- [:div.vspace] provides some vertical breathing room between elements.
- This pattern provides side-by-side column content blocks.
```
[:div.side-by-side-container
  [:div.side-by-side
    [:p "Stuff in the left column."]
    [:p "Lorem ipsum dolor..."]]
  [:div.side-by-side
    [:p "Stuff in the right column."]
    [:p "Duis aute irure..."]]]
```
- Speaker notes may be included within a [:div.note ...]. Their visibility is toggled by clicking the copyright notice.
Insert the required and optional information in the screedcast_options.edn file. Feel free to copy-paste this example, and edit as necessary.

The following keys are required (i.e., they do not have a default value):
- :screencast-filename-bases A vector of hash-maps, one hash-map for each screencast. Each map contains the following keys:
  - :screencast-filename A string representing the filename without the .clj extension.
  - :screencast-title A string that will appear as the first text of the screencast title in the first panel.
  - :screencast-uuid A version 4 Universally Unique Identifier.
- :project-name-formatted A string containing the name of the project, appearing in the title panel.
- :project-description A string describing the project, appearing in the web browser's OS window frame.
- :project-webpage-link A string appearing in the footer of the screencast.
- :copyright-holder A string used to create the copyright notice.
The following keys are optional, and will revert to defaults if not supplied by the options.
- :project-license-section A hiccup/html form that announces the screencast's license. Defaults to the MIT license.
- :sections-directory A string representing the directory to find the hiccup/html files. Include the trailing '/'. Defaults to 'resources/screencast_sections/'.
- :screencast-html-directory A string representing the directory to place the output files. Include the trailing '/'. Defaults to 'doc/screencast_slides/'.
- :separator A string representing a sequence of characters to insert between the Clojure code form and resulting evaluation. Defaults to ' => '.
- :wrap-at An integer that governs the wrapping column for the zprint pretty printer. Defaults to 80.
- :tidy-html? Indent and wrap html. Defaults to false.
Generate the html files. Screedcast is not fancy. Just evaluate this.
```
(generate-all-screencasts (load-file "resources/screedcast_options.edn"))
```
Or use a generator script. Find the html files in the output directory, which defaults to doc/screencast_slices/.

Examples

Introduction screencast
Usage screencast
Creating screencast

Alternatives

Traditional slideshow applications, such as Apple Keynote, Google Slides, LibreOffice Impress, or Microsoft PowerPoint.
LaTeX/Beamer
Various Emacs modes

Glossary

panel: A single frame of a screencast, written in hiccup-style html, which may contain Clojure code examples. Screedcast uses the term panel to distinguish between a traditional slideshow slide.

screed: A lengthy, boring piece of discourse.

screencast: An presentation whose visual component is a series of screens and whose audio component is voice narration.

section: One html file that contains the panels for one episode of a screencast. The Screedcast generator is capable of compiling multiple episodes with a single invocation.

slideshow: A typical presentation authored in Apple Keynote, Google Slides, LibreOffice Impress, or Microsoft PowerPoint, etc. No particular provisions for displaying evaluated Clojure code examples.

License

This program and the accompanying materials are made available under the terms of the MIT License.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcuts Report a problem cljdoc on GitHub

× close