2 Overview
What follows is a high-level overview of Congame’s systems and how they all work together. If you’ve just finished the introductory tour then this will give you some more context for what you saw.
2.1 Help and Support
This documentation makes heavy use of links, both in the writing and in the code. You can click on any function used in a code example to view detailed documentation on that function and how it’s used.
Links to common Racket functions and concepts will take you outside these Congame docs and into documentation written for Racket in general, or for other Racket packages. If you get lost, just use your browser’s Back button to get back here.
If you have questions about Congame or about this documentation, create a post in the Discussions area of Congame’s GitHub repository, and the authors will respond.
2.2 Programming in Racket
The Congame system is built entirely on the Racket programming language, and the Congame studies you will create are essentially Racket programs.
If you only read these docs, you should be able to pick up enough Racket to write studies. But Congame gives you access to lots of Racket capabilities. If you take a few minutes to learn about Racket programming in general, you will have a better understanding of what’s happening in your study’s code and how to fix it when it isn’t working.
Here are some great resources for someone new to Racket:
Welcome to Racket and Racket Essentials, the first two sections of The Racket Guide.
For a deep dive that will give you a really solid foundation, see How to Design Programs, 2nd ed.
If you are already even a little handy with other programming languages, you may want to bookmark the Datatypes chapter of The Racket Reference, to build up your vocabulary of the most common functions.
2.3 Basic Congame Concepts
A step is a point within a study at which we provide information to a participant, and/or collect a response from them. In the simplest (and most common) case, “steps” in Congame correspond to individual web pages.
A study is a series of steps and a transition graph that controls how study participants proceed through those steps.
A study instance is a discrete time when a study is run on a particular server. Congame keeps separate sets of results for each study instance.
A replication is a duplicate of a study instance, created specifically to test whether a study instance’s results can be replicated — or, to run the study with new participants, or simply to keep a copy of the data.
2.4 Web Pages
Studies and study steps eventually become web pages, so it helps to know a little about HTML and Markdown. This section provides a short introduction to each.
HTML (Hypertext Markup Language) is the standard markup language used to create web pages. It provides the structure and content that the web browser renders to display a website. HTML consists of elements which are represented by tags (keywords enclosed in < and >) which surround the content of each element.
Below is a fragment from an HTML document:
"example.html"
<h1>Gary Benchley, Rock Star</h1>
<p>Before I moved to <a href="https://en.wikipedia.org/wiki/New_York_City">New York</a>
from Albany, I wrote a careful, step-by-step plan:</p>
<ol>
<li>Rock out.</li>
<li>No more data entry.</li>
</ol>
The h1 (level 1 heading), p (paragraph), ol (ordered list) and li (list item) elements are standard HTML elements. When your web browser loads this file, it applies appropriate styling to each element:
Rock out.
No more data entry.
Markdown is a simple text format for producing HTML-formatted text.
Here’s how we’d write the above fragment using Markdown:
"example.md"
# Gary Benchley, Rock Star
Before I moved to [New York][1] from Albany, I wrote out a careful,
step-by-step plan:
1. Rock out.
2. No more data entry.
[1]: https://en.wikipedia.org/wiki/New_York_City
A Markdown processor would convert this directly into the same HTML shown in the first example above. As you can see, this is much quicker to type than the HTML version, and it is very readable.
Conscript provides functions for generating specific HTML elements, as well as functions that accept Markdown-formatted text and convert it to HTML for you.
Here are some good resources for learning more:
HTML: The HTML documentation on MDN provides good tutorials and reference material for HTML.
Markdown: The Commonmark site has a handy intro and quick reference sheet which also links to a 10-minute tutorial.
2.5 “Scribble Syntax” in Conscript
Racket’s advanced documentation system is called Scribble. The document you’re reading now was written as a Scribble program, using the syntax described here. See The Scribble Syntax at a Glance for more information on this syntax.
The Conscript environment allows use of an alternative Racket syntax known as Scribble syntax (or @ Syntax).
Expressions in Scribble syntax are normal Racket expressions in disguise. They keep you from having to use double quotes " around all your strings. This makes them handy in situations where most of the code consists of strings of text, or where you want to intermingle code with text (such as in documentation).
Here are some examples of expressions written in Scribble syntax, and their equivalent forms in normal Racket:
| @foo{blah blah blah} | reads as | (foo "blah blah blah") | ||||
| |||||||
| @foo{blah "blah"} | reads as | (foo "blah \"blah\"") | ||||
| |||||||
| @foo{blah @hum[8] blah} | reads as | (foo "blah " (hum 8) " blah") | ||||
| |||||||
| @foo[1 2]{3 4} | reads as | (foo 1 2 "3 4") | ||||
| |||||||
| @foo[1 2 3 4] | reads as | (foo 1 2 3 4) | ||||
| |||||||
|
| reads as |
|
Scribble-style expressions have this form:
@ ‹command name› [ ‹Racket arguments ...› ] { ‹text body ...› }
A Scribble-style expression has the three possible parts after the @:
The command name appears immediately after the @. Typically it’s an identifier —
a short word — bound to a Racket function or macro. The Racket arguments appear between square brackets [ and ]. These are arguments supplied to the function or macro named in the command part. These arguments are entered using Racket conventions —
e.g., a string of text needs to be put in quotes as a "string of text". The text body appears between curly braces { and }. You can put any ordinary text here, or more @-expressions. Unlike with the Racket arguments, you don’t put quotes around the text. Everything in this text body is also supplied as an argument to the function or macro in the command part.
Each of the three parts is optional. You can also nest commands within each other. However:
You can never have spaces or line breaks between the three parts. (This is particularly relevant for people familiar with C-style syntax. You can’t put the { on a separate line!)
Whatever parts you use must always appear in the order above.
2.6 Markdown in Scribble syntax in Racket
If you’re not already familiar with Racket/Scribble, HTML, or Markdown, then your head might be spinning a little right now.
To try and tie it all together, let’s look at some example Conscript code from Introduction: a quick tour using Conscript:
#lang conscript (provide tutorial) (defstep (start) @md{ # The Beginning is the End This is all there is. }) (defstudy tutorial [start --> start])
Armed with the concepts explained in this chapter, you should be able to understand:
All of this is Racket code. (Programming in Racket)
This code defines a step called start, and then a study that uses that step. (Basic Congame Concepts).
The start step uses the md function to define some content using Markdown formatting. This Markdown gets converted to HTML, which is displayed in your web browser when you run the study. (Web Pages)
The call to md is written using Scribble-style syntax, purely for convenience, so that the string content can be written without quote marks and newline escapes (" and \n).