The CodeDown Manual

1 Introduction

1.1 Features

CodeDown

CodeDown is implemented in Haskell and codedown is the executable that can be called from the command line to perform any of these conversions. See the according appendices below for the according instructions how to install and use it.

1.2 Overview

CodeDown is deliberately not smart. Its own idea is extremely simple and only requires to understand two or three syntax rules for the core conversion. However, this simplicity is built on the inherent properties of the Markdown lightweight markup language, so you need to become familiar with Markdown and we therefore start with a short recap of its features.

CodeDown is designed, implemented, and presented here in two steps. First, Core CodeDown defines the back and forth conversions between the different types of codes and Markdown. The simple rules for these conversions are introduced here, for the concrete example of PHP code, and for all other types of code in general. In practice however, one usually wants to generate other document formats than Markdown, say HTML, and to integrate this in a comfortable codedown command, the universal document converter Pandoc2 is merged into CodeDown. Pandoc CodeDown thus explains the options.

At the end, a couple of appendices summarize certain aspects or give additional hints: the installation, a codedown user manual, an overview of the Haskell implementation, the table of code symbols and a list of useful Links and resources.

2 Markdown

Markdown was originally designed as a way to ease the generation and comprehension of HTML source code. But meanwhile, there are a couple of Markdown extensions and implementations (including Pandoc) that suggest Markdown as a default authoring format for documents in general.

2.1 Markdown syntax, part 1

2.2 A typical example

For example, suppose we want to publish a HMTL file example.html with the following content:

<h1> Overview </h1>
<p>
  Originally, <a href="http://daringfireball.net/projects/markdown"> Markdown </a>
  introduced a simplified style for a couple of HTML inline and block elements, like the mentioned
  ones. All other HTML features still remained present by writing out the HTML tag syntax.
</p>
<p>
  Meanwhile, a couple of <a href="http://en.wikipedia.org/wiki/Markdown_extensions"> extensions </a>
  have been defined and implemented that introduce lightweight versions for tables, definition lists,
  footnotes etc and Markdown is evolving into a standard for writing documents in general.
</p>
<p>
  There are many <a href="http://http://xbeta.org/wiki/show/Markdown"> implementations </a> by now. We use
  <a href="http://johnmacfarlane.net/pandoc/"> Pandoc </a>, written by John MacFarlane, that not only
  offers many Markdown extensions, but is a universal converter between all kinds of text and
  documentation formats.
</p>

Instead of writing out this "tag soup", we could just create a file, say example.markdown, containing this:

# Overview

Originally, [Markdown][] introduced a simplified style for a couple of HTML inline and block
elements, like the mentioned ones. All other HTML features still remained present by writing out
the HTML tag syntax.

Meanwhile, a couple of [extensions][] have been defined and implemented that introduce
lightweight versions for tables, definition lists, footnotes etc. and Markdown is evolving into a
standard for writing documents in general.

There are many [implementations][] by now. We use [Pandoc][], written by John MacFarlane, that not
only offers many Markdown extensions, but is a universal converter between all kinds of text and
documentation formats.

[Markdown]: http://daringfireball.net/projects/markdown
[extensions]: http://en.wikipedia.org/wiki/Markdown_extensions
[implementations]: http://http://xbeta.org/wiki/show/Markdown
[Pandoc]: http://johnmacfarlane.net/pandoc/

and then generate example.html from example.markdown with the original Perl executable

Markdown.pl example.markdown > example.html

or alternatively with Pandoc by calling

pandoc --from=markdown --to=html --output=example.html example.markdown

The same effect is also achieved with a codedown call 3

codedown --from=markdown --to=html --output=example.html --input=example.markdown

2.3 Markdown syntax, part 2

There are three more Markdown syntax rules, that will be particularly important for the CodeDown conversions later on:

2.4 Markdown for program documentations

Markdown is an excellent format for the documentation of programming source code! If you ever have to write a manual for some program or application, this is a very convenient format. It is very easy to read and write, especially the just mentioned syntax for inline code and code blocks is very efficient and intuitive. The huge amount of Markdown converter implementations, including some online tools, makes it ubiquitously available. And they not only convert to HTML, but to any documentation format you could possibly whish for: groff man pages, PDF, RTF, LaTeX, DocBook XML, you name it. Besides, it is even very readable in its own text style.

By the way, this very document CodeDownManual.html was originally written in Markdown and then converted to HTML. 5 The source text CodeDownManual.markdown should thus be a good example for the ease and beauty of the Markdown syntax (in the extended Pandoc version).

3 Core CodeDown

The main idea behind CodeDown is the use of Markdown as the language for the documentation of program code and also as the primary target format of the document generation.

The core of the CodeDown program is made of the functions that convert source code (in C, JavaScript, Scheme, or whatever) to Markdown text, and vice versa.

3.1 Document generation

First, let us explain the document generator, i.e. the function that converts code to Markdown.

       document generator
code ----------------------> Markdown

Here, code can be virtually any type of source code, say PHP, JavaScript or C.

By the way, a list of all the currently implemented types of code is given by a call of

codedown --help=codes

3.1.1 Calling the document generator

Later on, we will explain the syntax and semantics of the codedown executable. But in order to give an idea how to realize the conversion in practice, let us take the following example.

Suppose we want to generate a Markdown document named example.markdown from a given PHP file example.php. We can do this by calling

codedown --from=PHP --to=Markdown --input=example.php --output=example.markdown

or a little shorter by the following call that has the same effect

codedown -f PHP -t Markdown -i example.php -o example.markdown

where the order of the options is arbitrary and format specifications (here PHP and Markdown) are case insensitive (i.e. we could have written php and markdown, or Php and MARKDOWN, instead).

3.1.2 The rules for the conversion to Markdown

Obviously, converting a file from PHP to Markdown changes the content and character of the file. Let us first introduce the conversion for the concrete example of PHP code.

Recall, that PHP has two kinds of comments:

  1. A line comment, where everything after a // symbol until the end of the line is considered a comment.6

  2. A block comment, that includes everything between an opening /* and a closing */.

As usual, a comment is a part of the source code, that is ignored by code applications like interpreters or compilers.

By a variation of these comments, CodeDown destinguishes the following areas in the PHP source code:

  1. A Markdown document line starts with a // // (i.e. 2 slash, 1 space, 2 slash, 1 space) at the beginning of the line. Everything that follows is preserved by the conversion to Markdown as part of a code block. More precisely, all parts of the form

      // // ... some Markdown text ...
    

    in the PHP source are converted to

      ... some Markdown text ...
    

    in the Markdown target text, i.e. this comment will be preserved as it is.

  2. A Markdown document block is everything between a /*** and a ***/, where both symbols have to be placed at the beginning of a line. In other words, all parts of the form

      /***
      ... some Markdown text ...
      ... more Markdown text ...
      ***/
    

    in the PHP source are preserved as such

      ... some Markdown text ...
      ... more Markdown text ...
    

    in the Markdown target text.

  3. A literal code block is everything between a line that starts with ///BEGIN/// and another line that starts with ///END///. Note, that each of these two delimiter lines makes a PHP line comment, so that all code lines inbetween is not comment, but PHP code that will be processed by PHP machines. In the conversion to Markdown, these code blocks are wrapped in Markdown code blocks (with 4 spaces before each line of code) and this is again placed into a quote (with a preceding > and another space). In other words, all parts of the form

     ///BEGIN///
     ... some PHP code ...
     ... more PHP code ...
     ///END///
    

    are converted into

     >     ... some PHP code ...
     >     ... more PHP code ...
    

    A further conversion of the Markdown text into HTML would return

     <blockquote>
     <pre><code>... some PHP code ...
     ... more PHP code ...
     </code></pre>
     </blockquote>
    

    where all special symbols in the PHP code are turned into HMTL entities. In the browser, this would render as

     ... some PHP code ...
     ... more PHP code ...
    

    with all white space and symbols as given in the original PHP file.

All other code outside Markdown document lines or blocks and literal code blocks are simply ignored.

3.1.3 An example

The following PHP code

<?php

include "MyStandardLibrary.php";

/***
# The mother of all programs

This is the [first standard program](http://en.wikipedia.org/wiki/Hello_world) in
computer language tutorials.

***/

// // ## An auxiliary function
// // `greetings()` returns a friendly string when it is called.
///BEGIN///
function greetings() {
  $str = "Hello world!";
  return $str;
}
///END///

// // ## The main program
///BEGIN///
echo greetings();     // returns "Hello world!"
///END///

?>

converts to the following Markdown text

# The mother of all programs

This is the [first standard program](http://en.wikipedia.org/wiki/Hello_world) in
computer language tutorials.

## An auxiliary function
`greetings()` returns a friendly string when it is called.

>     function greetings() {
>       $str = "Hello world!";
>       return $str;
>     }

## The main program

>     echo greetings();     // returns "Hello world!"

and that would convert to the following (X)HTML

<h1>The mother of all programs</h1>
<p>
  This is the <a href="http://en.wikipedia.org/wiki/Hello_world">first standard program</a>
  in computer language tutorials.
</p>

<h2>An auxiliary function</h2>
<p>
  <code>greetings()</code> returns a friendly string when it is called.
</p>
<blockquote>
<pre><code>function greetings() {
  $str = &quot;Hello world!&quot;;
  return $str;
}
</code></pre>
</blockquote>

<h2>The main program</h2>
<blockquote>
<pre><code>echo greetings();     // returns "Hello world!"
</code></pre>
</blockquote>

3.1.3.1 Generating the example

Suppose, the original PHP code of the previous example is the content of a file named HelloWorld.php.

We can generate the Markdown text as content of a file called HelloWorld.markdown by calling

codedown --from=php --to=markdown --input=HelloWorld.php --output=HelloWorld.markdown

A subsequent conversion of this Markdown file into the HTML file called HelloWord.html is achieved by

codedown --from=markdown --to=html --input=HelloWorld.markdown --output=HelloWorld.html

We may as well convert the PHP file directly into HTML by calling

codedown --from=php --to=html --input=HelloWorld.php --output=HelloWorld.html

3.1.4 Calling for help

We can ask for a summary of the CodeDown rules for PHP by calling

codedown --help=php

or alternatively

codedown -h php

This will be the response:

Markdown document lines in PHP:
+-----------------------------------------+
| // // ... one line of Markdown text ... |
+-----------------------------------------+
Markdown document blocks in PHP:
+--------------------------------+
| /***                           |
| ... lines of Markdown text ... |
| ***/                           |
+--------------------------------+
Literal PHP code blocks:
+---------------------------+
| ///BEGIN///               |
| ... lines of PHP code ... |
| ///END///                 |
+---------------------------+

3.2 Document generation for arbitrary code languages

We just described how CodeDown defines the Markdown document generator for the PHP programming language. But CodeDown is a Markdown document generator for just any (main stream) code language. In fact, the implementation is designed so that adding a new document generator for yet another type of code XYZ just requires a few lines of code. 7 In this sense, CodeDown is a true "document generator generator".

In the sequel, we explain the document generation with CodeDown for arbitrary types of code.

3.2.1 Any-time help

Once the general principles for the document generation is understood, it should be possible to work with codedown without the need to consult this manual anymore. All specific information is then available from the following calls:

3.2.2 Line and block comments

All mainstream programming languages allow the insertion of comments into the source code. These are text parts, that are ignored by machine (i.e. the interpreter or compiler). The syntax for comments always works according to at least one of the following two principles:

line comment

There is a special symbol (a single character or a certain short character string), after which the rest of the line is ignored. In C, JavaScript and Java this is the "//", in Scheme an Lisp this is ";".

block comment

That is a text part spanning over an arbitrary length, wrapped between a begin and end symbol. For example, in JavaScript, block comments are enclosed between "/*" and "*/". In SML, the delimiters are "(*" and "*)".

Again, every modern programming language provides at least one of the following kinds of comments. Some only have line comments, such as Scheme, bash scripts or Perl.8 Others only know block comments, such as SML and SQL. And languages like C and Haskell have both. 9

3.2.3 Markdown document lines and blocks, and literal code blocks

The universal CodeDown document generator modifies the comments of a given code language so that each source contains certain designated parts:

Markdown document parts

These are comments written in Markdown format, which are preserved during the conversion. Depending on the comments defined in the code language, these parts are Markdown document lines, in case the code language has line comments, or Markdown document blocks, in case block comments are defined.

In PHP, document lines are lines that start with a "// //" and document blocks are initiated with line "/***" and terminate with a line "***/".

Literal code blocks

These are comment delimiters around parts of code. In PHP, for example, a literal code block was opened with a "///BEGIN//" and closed with an "///END///". Literal code blocks are preserved as code blocks in the documentation.

All other source code outside Markdown document parts and literal code blocks is ignored during the document generation.

Note, that the special CodeDown symbols (e.g. "// //", "/***" and "***/", "///BEGIN///" and "///END///" in PHP) always have to be at the beginning of a line.

3.2.3.1 For example: document generation in C

An exhaustive overview of the CodeDown document generation rules for the C programming language is shown after a call of

codedown --help=c

The answer will be

Markdown document lines in C:
+-----------------------------------------+
| // // ... one line of Markdown text ... |
+-----------------------------------------+
Markdown document blocks in C:
+--------------------------------+
| /***                           |
| ... lines of Markdown text ... |
| ***/                           |
+--------------------------------+
Literal C code blocks:
+-------------------------+
| ///BEGIN///             |
| ... lines of C code ... |
| ///END///               |
+-------------------------+

That means, we have both Markdown document lines and -blocks available.

For example, a C source file HelloWorld.c with might contain the following code:

/***

This is the __Hello world program__ in C.

***/

#include <stdio.h>

// // Implementation of the `main` function:

///BEGIN///
int main (void) {
  printf ("Hello world\n");  // prints a message
  return 0;                  // exit normally
}
///END///

/***
To compile the program and generate an executable `hello`, call

     gcc -o hello HelloWorld.c

Subsequently, you apply it by calling

    ./hello

It will answer with

    Hello world

***/

If we call

codedown --from=c --to=markdown --input=HelloWorld.c --output=HelloWorld.markdown

then the content of HelloWorld.markdown will be

This is the __Hello world program__ in C.

Implementation of the `main` function:

>     int main (void) {
>       printf ("Hello world\n");  // prints a message
>       return 0;                  // exit normally
>     }


To compile the program and generate an executable `hello`, call

    gcc -o hello HelloWorld.c

Subsequently, you apply it by calling

    ./hello

It will answer with

    Hello world

3.2.3.2 For example: document generation in Scheme

....continuehere..

3.2.3.3 For example: document generation in C

....continuehere..

3.2.4 Good style recommendations

........continuehere ............................

3.3 Code generation or literal programming

........continuehere ............................

4 Pandoc CodeDown

........continuehere ............................

5 Appendix: Installation

........continuehere ............................

6 Appendix: The codedown user manual

We explain the syntax and options of the codedown executable in some detail. A short summary can be obtained at any time by calling the help function without a value, i.e.

codedown --help

or its short version

codedown -h

The answer will be something like this:

SYNTAX:
  codedown OPTION_1 OPTION_2 ... OPTION_N
TYPES OF CODE:
  scheme, bash, latex_code, perl, python, ruby, sml, ocaml, sql, html_code, xml_code, c, cpp, java, scala, javascript, php, haskell, lisp
TYPES OF DOCUMENTS:
  json, html, s5, slidy, docbook, opendocument, latex, context, texinfo, man, markdown, rst, mediawiki, textile, rtf, org, odt, epub, pdf
HELP OPTIONS:
  --help            -h               this general help message
  --help=codes      -h codes         list of supported types of codes
  --help=docs       -h docs          list of supported document type formats
  --help=symbols    -h symbols       prints the table of code types symbols
  --help=pandoc     -h pandoc        same as: pandoc --help
  --help=CODE       -h CODE          the CodeDown rules for specified type of CODE
CORE OPTIONS:
  --from=FORMAT  -f FORMAT   --read=FORMAT   -r FORMAT    specifies the FORMAT of the source
  --to=FORMAT    -t FORMAT   --write=FORMAT  -w FORMAT    specifies the FORMAT of the target
  --input=FILE_1,...,FILE_N  -i FILE_1 ... FILE_N         the input source files
  --output=FILE              -o FILE                      the output targe file
ADDITIONAL PANDOC OPTIONS: (see `pandoc -h` for many more):
  --standalone  -s                produce a whole document, with header etc.
  --html5  -5                     produce HTML5 instead of HTML4
  --number-sections -N            number the headings
  --table-of-contents   --toc     include an automatically generated table of contents
  --css=URL   -c URL              use URL as CSS stylesheet
LINKS:
  http://bucephalus.org/CodeDown
  http://johnmacfarlane.net/pandoc

In the sequel, we will explain this information in some more detail.

6.1 Formats

CodeDown is universal converter between different text formats, and there are three types of formats:

The names of all these formats need to be specified in the source (--from or --read) and target (--to or --write) options of the codedown command. These name values are case-insensitive. For example, LaTeX, latex and LATEX are equally possible.

6.2 Syntax of the codedown call

The syntax of the codedown command is

codedown OPTION_1 OPTION_2 ... OPTION_N

The order of the options in such a call is arbitrary.11

6.2.1 Syntax for options

Each OPTION is a combination of a key and possible values. Each OPTION has has a long form

--KEY
--KEY=VALUE
--KEY=VALUE_1,VALUE_2,...,VALUE_N

and often also an equivalent short version, where the key K stands for just one letter

-K
-K VALUE
-K VALUE_1 VALUE_2 ... VALUE_N

For example, a possible call could be

codedown --from=JavaScript --to=HTML --input=Part1.js,Part2.js --output=Manual.html --standalone --css=MyStyle.css

where each of these options has a short version and can thus be replaced by 12

codedown -f JavaScript -t HTML -i Part1.js Part2.js -o Manual.html -s -c MyStyle.css

6.2.2 The codedown options

We distinguish three kinds of options

.....CONTINUEHERE........................................

7 Appendix: Haskell implementation

Haskell module Haddock documentation CodeDown documentation in HTML CodeDown documentation in Markdown
CodeDownManual.html CodeDownManual.markdown
CodeDown.hs CodeDown.html CodeDown.hs.html CodeDown.hs.markdown
CoreCodeDown.hs CoreCodeDown.html CoreCodeDown.hs.html CoreCodeDown.hs.markdown
PandocCodeDown.hs PandocCodeDown.html PandocCodeDown.hs.html PandocCodeDown.hs.markdown

8 Appendix: Table of code symbols

The following table lists all types of code languages currently implemented in CodeDown, together with the comment symbols.

+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|  Type of   | commment | comment | comment |  doc   |   doc    |  doc   |    literal    |   literal   |
|    code    |   line   |  begin  |   end   |  line  |  begin   |  end   |     begin     |     end     |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|   SCHEME   |    ;     |         |         |  ; ;   |          |        |  ;;;BEGIN;;;  |  ;;;END;;;  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    BASH    |    #     |         |         |  # #   |          |        |  ###BEGIN###  |  ###END###  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
| LATEX_CODE |    %     |         |         |  % %   |          |        |  %%%BEGIN%%%  |  %%%END%%%  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    PERL    |    #     |         |         |  # #   |          |        |  ###BEGIN###  |  ###END###  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|   PYTHON   |    #     |         |         |  # #   |          |        |  ###BEGIN###  |  ###END###  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    RUBY    |    #     |         |         |  # #   |          |        |  ###BEGIN###  |  ###END###  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    SML     |          |   (*    |   *)    |        |   (***   |  ***)  | (***BEGIN***) | (***END***) |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|   OCAML    |          |   (*    |   *)    |        |   (***   |  ***)  | (***BEGIN***) | (***END***) |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    SQL     |          |   /*    |   */    |        |   /***   |  ***/  | /***BEGIN***/ | /***END***/ |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
| HTML_CODE  |          |  <!--   |   -->   |        | <!-- --  | -- --> | <!--BEGIN-->  | <!--END-->  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|  XML_CODE  |          |  <!--   |   -->   |        | <!-- --  | -- --> | <!--BEGIN-->  | <!--END-->  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|     C      |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    CPP     |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    JAVA    |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|   SCALA    |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
| JAVASCRIPT |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    PHP     |    //    |   /*    |   */    | // //  |   /***   |  ***/  |  ///BEGIN///  |  ///END///  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|  HASKELL   |    --    |   {-    |   -}    | -- --  |   {---   |  ---}  |  ---BEGIN---  |  ---END---  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+
|    LISP    |    ;     |   #|    |   |#    |  ; ;   |   #|||   |  |||#  |  ;;;BEGIN;;;  |  ;;;END;;;  |
+------------+----------+---------+---------+--------+----------+--------+---------------+-------------+

where

Note, that

...........continuehere......................

9 Appendix: Links and resources

..............................................

  1. This is entirely thanks to John MacFarlanes Pandoc, that does all the hard work hidden behind the scenes.

  2. Compare to the simplicity of CodeDown, Pandoc is a huge and very sophisticated program written by John MacFarlane, which does all the heavy conversion work between the different document formats.

  3. The syntax of the codedown command is very similar to the pandoc command syntax. There is one big difference, however, namely the --input option, which does not exist for pandoc. There, the input files are added at the end of the call, as the example shows.

  4. There is yet another version for code blocks in Markdown, but only in the extended Markdown version of Pandoc, namely delimited code blocks between tilde-lines, with an option to use syntax highlighting for many types of code. You can use that, too, but the official version of CodeDown does not mention this explicitly.

  5. The conversion was done with the command codedown --from=markdown --to=html --input CodeDownManual.markdown --output=CodeDownManual.html --table-of-contents --standalone --css=CodeDown.css, and that has the same effect as pandoc --from=markdown --to=html --output=CodeDownManual --table-of-contents --standalone --css=CodeDown.css CodeDownManual.markdown.

  6. In fact, there are two versions for a line comment in PHP, namely the // and a # symbol. But CodeDown takes only one of the two. By taking // and neglecting #, PHP behaves the same way as the other languages from the C-like syntax family, like JavaScript, C and Java.

  7. See the CoreCodeDown.hs.html documentation of the Haskell CoreCodeDown.hs module, which explains how a new programming language is added to the supported types of code. This simple customization of CodeDown is complete, it even implies the automatic generation of the help messages, i.e. a call of codedown --help=XYZ.

  8. In this context, Perl, Python and Ruby are considered languages that only have line comments, because their block comments use a special markup for their own document converters.

  9. In the implementation of the general document generators in the CoreCodeDown.hs module we say that a code language is of type 1, if it has a line, but no block comment. If it is the other way round, we call it a type 2 code language. If it has both, line and block comments, it is of type 3. For example, scheme and bash are type 1, SML and SQL are type 2, and C and (Common) Lisp are type 3.

  10. PDF output is generated via LaTeX and is supported with the markdown2pdf wrapper, included in the Pandoc installation. By using codedown, all this is done automatically. For example, calling codedown -f markdown -t pdf -i example.markdown -o example.pdf should work just fine.

  11. To be precise, the order of the options in a codedown call is not entirely arbitrary, namely in case you specify the same option several times. But this is never intended and average users will avoid doing that, anyway.

  12. As it is common for one-letter UNIX command options without values, these one-letter flags can be condensed into a single one. For example, in UNIX, a call of ls -A -l -r -R -S is equivalent to ls -AlrRS. This works in CodeDown and Pandoc, too, but the time and space to mention this is probably not worth the time that can be saved when using these abbreviations.