Carnap's Pandoc

Within Carnap, shared documents and problem sets are created using pandoc markdown, a simple formatting language (akin to LaTeX) developed by John McFarlane as part of the Pandoc project. Pandoc markdown extends John Gruber's original markdown syntax with some additional niceties.

It would be a little redundant to give the full specifications for pandoc markdown here, since there are many excellent resources already available. See, instead,

  1. John Gruber's original markdown specification.
  2. The Pandoc user's guide

If you learn best from example, it's also possible to download the source code for documents shared on Carnap.io from the shared document list, available at https://carnap.io/shared. The pandoc source for this document, should you wish to inspect it, is available here.

You can create pandoc documents in any text editing program. Pandoc is nothing but plain text that is written with some special notation to indicate how text is to be formatted. For example, you can write *italic* to generate the text "italic". However, there are some very good text-editor plugins and dedicated applications available for working with Pandoc. These provide extra features like live previews of the formatted text. A list of these can be found here. An online pandoc editor, with live previews of what the rendered document will look like, can be found at http://markup.rocks.

General Pattern

Carnap's exercises are created by including special code blocks within a pandoc document. A code block looks something like this:

~~~ 
CONTENT GOES HERE
~~~

To indicate which type of exercise you want to create, you apply classes and data attributes to the code block. That would look something like this:

~~~{.SOMECLASS .ANOTHER attribute="value"}
CONTENT GOES HERE
~~~

with classes indicated by a leading ., and attributes assigned with the = sign, and surrounded by quotes.

Some common attributes

Here are some common attributes that can be applied to to any exercise

Name Effect
points Sets a custom point value
submission Controls how work is submitted. Set to "none" to disable submission
options Exercise-specific options

the options attribute might require some extra explanation. This attribute is set to a string of space separated words, indicating what special options are set for the exercise-block it is attached to. Different types of exercises allow for different options.

Random problems

When you create a problem set, the different problems within a code block will generally be assigned numbers or some other identifier. So you might write

~~~ 
1.1 SOME PROBLEM
~~~

If the same identifier is used for a contiguous series of problems, then when the problem set is assigned and viewed by a student, one of the problems in the series will be chosen randomly and displayed. So, for example given

~~~ 
1.1 PROBLEM A
1.1 PROBLEM B
~~~

Students will see PROBLEM A or PROBLEM B, but not both. A student reloading the page will continue to see the same problem, so if they see PROBLEM A on the first viewing, they'll continue to see PROBLEM A.

The selection of a random problem only takes place when the document is viewed as an assignment, so when the document is viewed through the instructor's "manage documents" tab, all the variant problems will be displayed.

Exercise Types

There are currently eight types of exercises:

  1. Syntax Checking
  2. Translation
  3. Truth Tables
  4. Derivations
  5. Model Checking
  6. Qualitative Problems
  7. Sequent Calculus Problems
  8. Gentzen-Prawitz Natural Deduction Problems

To learn more about each one, follow the links above.