The CodeDown Manual

1 Introduction

1.1 Features

CodeDown

• is a document generator in the sense that it generates a documention from given source code

• is also a literal programming tool in the sense that it extracts source code scattered in a (Markdown) document and so turns it into an application

• uses Markdown as the principal (intermediate) document format in these kind of conversions, but also as the very convenient and powerful syntax for source code documentations itself.

• is very universal, as it works for all kinds of programming languages. In fact, it is not only a document generator, but a document generator generator for any new type of code.

• is very universal also in the variety of available documentation formats.¹

• is very easy to learn for all these languages and formats, because it comprisis only two or three syntactical rules to manage all situations.

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 Pandoc² 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

• Emphasized text like <emph>this</emph> is simplified to _this_ (alternatively, *this* is also possible)

• Strongly emphasized parts like <strong>that one</strong> is simplified to __that one__ (or **that one**)

• To produce headers like

  <h1>Header One</h1>
  <h2>Header Two</h2>
  <h3>Header Three</h3>
  

  etc. we just write

  # Header One
  ## Header Two
  ### Header Three
  

  etc, respectively, each one starting at the beginning of a line.

• Links like

  the entry on <a href="http://en.wikipedia.org/wiki/Markdown"> Markdown </a> in the Wikipedia
  

  can be induced by writing it inline, with the address inside the text

  the entry on [Markdown](http://en.wikipedia.org/wiki/Markdown) in the Wipedia
  

  or with a reference label, say link1, that points to the address later on

  the entry on [Markdown][link1] in the Wikipedia
  
  [link1]: http://en.wikipedia.org/wiki/Markdown
  

  or even shorter with an implicit link label

  the entry on [Markdown][] in the Wikipedia
  
  [Markdown]: http://en.wikipedia.org/wiki/Markdown
  

• Paragraphs

  <p>This is one paragraph.</p>
  <p>This is the next one.</p>
  

  are written more naturally by leaving an empty line between the paragraph blocks

  This is one paragraph.
  
  This is the next one.
  

• An unordered list

  <ul>
    <li>apple</li>
    <li>banana</li>
    <li>cherry</li>
  </ul>
  

  is much more conveniently written

  * apple
  * banana
  * cherry
  

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 ³

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:

• Inline code like <code>1+2=3</code> is written as `1+2=3`

• If we want a code block, say

  if x == y
  then True
  else False
  

  to appear as it is, we can wrap it in a <pre>...</pre> tag. Markdown converters use <pre><code>...</code></pre>, instead, i.e.

  <pre><code>if x == y
  then True
  else False
  </code></pre>
  

  In Markdown, this can be achieved much easier by just indenting each line of the according block by 4 or more spaces (or alternatively by one or more tabs)⁴ and write

      if x == y
      then True
      else False
  

  Besides, it is possible to use all characters without replacing them by HTML entities. For example, suppose we want a piece of text that renders in the browser as

  if ($x < 7) {
    echo "$x is smaller than seven";
  }
  

  then we would have to encode this in HTML as

  <pre><code>if ($x &lt; 7) {
    echo &quot;$x is smaller than seven&quot;;
  }
  </code></pre>
  

  But in Markdown, we can just write the initial text block itself (indented by say 4 spaces).

      if ($x < 7) {
        echo "$x is smaller than seven";
      }
  

• A blockquote

  <blockquote>
    The biggest source of inspiration for Markdown's syntax is the format of plain text email.
  </blockquote>
  

  is written in email style by putting a > (an a space symbol) in front of the quoted text passages

  > The biggest source of inspiration for Markdown's syntax is the format of plain text email.
  

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. ⁵ 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.⁶

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. ⁷ 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:

• codedown --help=codes

  displays the list of all types of code implemented in the current version. The response covers at least the following: SCHEME, BASH, LATEX_CODE, PERL, PYTHON, RUBY, SML, OCAML, SQL, HTML_CODE, XML_CODE, C, CPP, JAVA,SCALA, JAVASCRIPT, PHP, HASKELL, LISP.

• codedown --help=CODE

  displays the two or three syntax rules for the document generation of the given CODE, where CODE is one of the members from the previous list of codes. The CODE value is case insensitive, e.g. JavaScript, JAVASCRIPT, javascript etc. are considered the same.

  We will soon explain how the answer is to be interpreted, but here is an example:

  codedown --help=scheme
  

  returns

  Markdown document lines in SCHEME:
  +---------------------------------------+
  | ; ; ... one line of Markdown text ... |
  +---------------------------------------+
  Literal SCHEME code blocks:
  +------------------------------+
  | ;;;BEGIN;;;                  |
  | ... lines of SCHEME code ... |
  | ;;;END;;;                    |
  +------------------------------+
  

  Another example call

  codedown --help=sql
  

  returns

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

• codedown --help=symbols

  i.e. a help call with the symbols value finally provides a tabular overview of all implemented types of code and all the original and modified comment symbols involved. The response of this help call is shown and explained below.

• codedown --help

  finally is the general help call, that also lists the previous help options.

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.⁸ Others only know block comments, such as SML and SQL. And languages like C and Haskell have both. ⁹

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

3.2.3.3 For example: document generation in C

3.2.4 Good style recommendations

3.3 Code generation or literal programming

4 Pandoc CodeDown

5 Appendix: Installation

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:

• Markdown as the primary document format

• document types, which are all the other target document formats supported by Pandoc, including: HTML, LaTeX, ConTeXt, PDF¹⁰, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, textile, groff man pages, Emacs org-mode, EPUB ebooks, JSON, RST, and slide shows with S5 and Slidy.

  For more information on the currently supported target document formats, check out one of the following help calls

  codedown -h pandoc
  codedown --help=pandoc
  

  which in turn is the same as a call of pandoc --help.

• code types, the different code programming language, including scheme, bash, Perl, Python, Ruby, SML (i.e. Standard ML), OCaml, SQL, XML, C, Cpp (i.e. C++), Java, Scala, JavaScript, PHP, Haskell, Lisp.

  Some of the document types are also code types, namely LaTeX, HTML and XML. But if they are considered as such, we attach a _code suffix to the name, i.e. the values are LATEX_CODE, HTML_CODE and XML_CODE.

  The list of all possible code types is shown by calling one of the following two help commands

  codedown --help=codes
  codedown -h codes
  

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.¹¹

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 ¹²

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

• The help option

  • --help or -h

    shows a general help message with the syntax of the codedown command

  • --help=codes or -h codes

    shows the list of supported types of code

  • --help=docs or -h docs

    shows a list of the supported document formats (there are more; see pandoc --help)

  • --help=symbols or -h symbols

    prints a the table with the comment symbols and CodeDown symbols for each supported type of code.

  • --help=version or -h version

    prints the version number of the currently running CodeDown and Pandoc versions.

  • --help=pandoc or -h pandoc

    prints the help message which is generated by a call of pandoc --help

  • --help=CODE or -h CODE

    shows the CodeDown document conversion rules for the given CODE, i.e. one of the supported types of code.

• The essential core options

  • --from=FORMAT or -f FORMAT (or alternatively --read=FORMAT or -r FORMAT)

    specifies the format of the input source. If this option is not specified, codedown first attempts to determine it from the extension of the (first) file specified by the --input (or -i) option. If this fails, too, then the FORMAT is set to markdown as the default input.

  • --to=FORMAT or -t FORMAT (or alternatively --write=FORMAT or -w FORMAT)

    the format of the output target. If this option is not specified, codedown first attempts to determine it from the extension of the file specified by the --ouput (or -o) option. If this fails, too, then the FORMAT is set to markdown as the default output.

  • --input=FILE_1,...,FILE_N or -i FILE_1 ... FILE_N

    specifies the input text. If the list of files is empty, the input is set to standard user input. If there is more the one file in the list, the contents of these files are concatenated.

    Note, that this is the only CodeDown option that has no equivalent in Pandoc. There, the input files are listed as such, without a preceding --input or -i key. (There is however a Pandoc key -i, which is short for --incremental, and that makes list items in Slidy or S5 slideshows to be displayed incrementally. If you want to control this Pandoc option from a codedown call, you have to use the long --incremental.)

  • --output=FILE or -o FILE

    defines the file for the output of the conversion. If FILE does not exist, yet, it will be created, otherwise it will be overwritten. If this option is not specified, all output goes to the standard output (except when the target format is set to odt, epub or pdf).

  A special case is the possibility to set one format to code. If the source format is set to code (i.e. --from=code) and the target format is markdown, then the whole input is put into a single code block. This can be useful if you need to display an entire source file in standard CodeDown layout. Conversely, if --from=markdown and --to=code then the code blocks (lines preceded with > plus 5 spaces, at least) are extracted as code blocks, while everything else is ignored.

• The additional Pandoc options

7 Appendix: Haskell implementation

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

• comment line denotes the native line comment symbol of the given language, if there is one.

• comment begin and comment end contain the native block comment symbols of the given language.

• doc line denote the CodeDown symbol for Markdown document lines. This is only defined, when the language has a comment line symbol "x", and in that case, the default rule for the CodeDown symbol is "x x" (i.e. x, space, x, space). Note, that this symbol has to be placed at the beginning of a line.

• doc begin and doc end are the delimiters for Markdown document blocks. These are only defined, when the language has provides block comments. Note, that each of the two delimiters has to commence a line.

• literal begin and literal end are the delimiters for literal code blocks. Again, each delimiter has to be at the beginning of a line.

Note, that

• Perl, Ruby and Python do have block comments, but they are not used as plain comments but have their own markup syntax and function.

9 Appendix: Links and resources

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

• Pandoc

  The ............

• Markdown

  John Gruber ..........

• CodeDown

  Home ....