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.

Exercise Types

There are currently five types of exercises:

  1. Syntax Checking
  2. Translation
  3. Truth Tables
  4. Derivations

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