% The CodeDown Manual % bucephalus.org % August 2011 # Introduction ## 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.^[This is entirely thanks to John MacFarlanes Pandoc, that does all the hard work hidden behind the scenes.] * 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](#appendix-installation) and [use](#appendix-the-codedown-user-manual) it. ## 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](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](http://JohnMacFarlane.net/pandoc)^[Compare to the simplicity of CodeDown, Pandoc is a huge and very sophisticated program written by [John MacFarlane](http://JohnMacFarlane.net), which does all the heavy conversion work between the different document formats.] is merged into CodeDown. [Pandoc CodeDown](#pandoc-codedown) thus explains the options. At the end, a couple of appendices summarize certain aspects or give additional hints: the [installation](#appendix-installation), a [`codedown` user manual](CodeDown.html#appendix-the-codedown-user-manual), an overview of the [Haskell implementation](CodeDown.html#appendix-haskell-implementation), the [table of code symbols](CodeDown.html#appendix-table-of-code-symbols) and a list of useful [Links and resources](CodeDown.html#appendix-links-and-resources). # 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. ## Markdown syntax, part 1 * __Emphasized__ text like `this` is simplified to `_this_` (alternatively, `*this*` is also possible) * __Strongly emphasized__ parts like `that one` is simplified to `__that one__` (or `**that one**`) * To produce __headers__ like

Header One

Header Two

Header Three

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 Markdown 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__

This is one paragraph.

This is the next one.

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__ is much more conveniently written * apple * banana * cherry ## A typical example For example, suppose we want to publish a HMTL file `example.html` with the following content: >

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

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 ^[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.] codedown --from=markdown --to=html --output=example.html --input=example.markdown ## 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 `1+2=3` 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 `
...
` tag. Markdown converters use `
...
`, instead, i.e. 
if x == y
        then True
        else False
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)^[There is yet another version for code blocks in Markdown, but only in the extended Markdown version of Pandoc, namely [delimited code blocks](http://johnmacfarlane.net/pandoc/README.html#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.] 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 
if ($x < 7) {
          echo "$x is smaller than seven";
        }
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__
The biggest source of inspiration for Markdown's syntax is the format of plain text email.
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. ## 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](CodeDownManual.html) was originally written in Markdown and then converted to HTML. ^[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`.] The source text [CodeDownManual.markdown](CodeDownManual.markdown) should thus be a good example for the ease and beauty of the Markdown syntax (in the extended Pandoc version). # 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. ## 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 ### 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). ### 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.^[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.] 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 
... some PHP code ...
         ... more PHP code ...
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. ### An example The following PHP code 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

The mother of all programs

This is the first standard program 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!"
#### 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 ### 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/// | +---------------------------+ ## 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. ^[See the [CoreCodeDown.hs.html](CoreCodeDown.hs.html) documentation of the Haskell [CoreCodeDown.hs](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`.] 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. ### 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](#appendix-table-of-code-symbols). * `codedown --help` finally is the general help call, that also lists the previous help options. ### 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.^[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.] Others only know block comments, such as SML and SQL. And languages like C and Haskell have both. ^[In the implementation of the general document generators in the [CoreCodeDown.hs](CoreCodeDown.hs.html) 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.] ### 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. #### 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 // // 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 #### For example: document generation in Scheme
....continuehere..
#### For example: document generation in C
....continuehere..
### Good style recommendations
........continuehere ............................
## Code generation or literal programming
........continuehere ............................
# Pandoc CodeDown
........continuehere ............................
# Appendix: Installation
........continuehere ............................
# 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. ## 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](http://www.w3.org/TR/html40), [LaTeX](http://www.latex-project.org), [ConTeXt](http://www.pragma-ade.nl), [PDF](http://en.wikipedia.org/wiki/Portable_Document_Format)^[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.], [RTF](http://en.wikipedia.org/wiki/Rich_Text_Format), [DocBook XML](http://docbook.org), [OpenDocument](http://opendocument.xml.org) XML, [ODT](http://en.wikipedia.org/wiki/OpenDocument), GNU [Texinfo](http://www.gnu.org/software/texinfo), [MediaWiki](http://www.mediawiki.org/wiki/Help:Formatting) markup, [textile](http://redcloth.org/textile), groff [man](http://www.wikipedia.org/wiki/Man_page) pages, Emacs [org](http://orgmode.org)-mode, [EPUB](http://en.wikipedia.org/wiki/EPUB) ebooks, [JSON](http://json.org), [RST](http://en.wikipedia.org/wiki/ReStructuredText), and slide shows with [S5](http://meyerweb.com/eric/tools/s5) and [Slidy](http://www.w3.org/Talks/Tools/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](http://en.wikipedia.org/wiki/Scheme_(programming_language)), [bash](http://www.gnu.org/software/bash/bash.html), [Perl](http://perl.org), [Python](http://www.python.org), [Ruby](http://ruby-lang.org), [SML](http://standardml.org) (i.e. Standard ML), [OCaml](http://en.wikipedia.org/wiki/OCaml), [SQL](http://en.wikipedia.org/wiki/Sql), [XML](http://www.w3.org/XML/), [C](http://en.wikipedia.org/wiki/C_(programming_language)), [Cpp](http://en.wikipedia.org/wiki/C%2B%2B) (i.e. C++), [Java](http://en.wikipedia.org/wiki/Java_(programing_language)), [Scala](http://www.scala-lang.org), [JavaScript](http://en.wikipedia.org/wiki/JavaScript), [PHP](http://php.net), [Haskell](http://haskell.org), [Lisp](http://en.wikipedia.org/wiki/Lisp_(programming_language)). 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. ## 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.^[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.] ### 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 ^[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.] codedown -f JavaScript -t HTML -i Part1.js Part2.js -o Manual.html -s -c MyStyle.css ### 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
.....CONTINUEHERE........................................
# Appendix: Haskell implementation +----------------------------------------+--------------------------------------------+--------------------------------------------------+----------------------------------------------------------+ | Haskell module | Haddock documentation | CodeDown documentation in HTML | CodeDown documentation in Markdown | +========================================+============================================+==================================================+==========================================================+ | | | [CodeDownManual.html](CodeDownManual.html) | [CodeDownManual.markdown](CodeDownManual.markdown) | +----------------------------------------+--------------------------------------------+--------------------------------------------------+----------------------------------------------------------+ | [CodeDown.hs](CodeDown.hs) | [CodeDown.html](CodeDown.html) | [CodeDown.hs.html](CodeDown.hs.html) | [CodeDown.hs.markdown](CodeDown.hs.markdown) | +----------------------------------------+--------------------------------------------+--------------------------------------------------+----------------------------------------------------------+ | [CoreCodeDown.hs](CoreCodeDown.hs) | [CoreCodeDown.html](CoreCodeDown.html) | [CoreCodeDown.hs.html](CoreCodeDown.hs.html) | [CoreCodeDown.hs.markdown](CoreCodeDown.hs.markdown) | +----------------------------------------+--------------------------------------------+--------------------------------------------------+----------------------------------------------------------+ | [PandocCodeDown.hs](PandocCodeDown.hs) | [PandocCodeDown.html](PandocCodeDown.html) | [PandocCodeDown.hs.html](PandocCodeDown.hs.html) | [PandocCodeDown.hs.markdown](PandocCodeDown.hs.markdown) | +----------------------------------------+--------------------------------------------+--------------------------------------------------+----------------------------------------------------------+ # 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 | | | | | | | +------------+----------+---------+---------+--------+----------+--------+---------------+-------------+ | XML_CODE | | | | | | | +------------+----------+---------+---------+--------+----------+--------+---------------+-------------+ | 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.
...........continuehere......................
# Appendix: Links and resources .............................................. * [Pandoc](http://......) The ............ * [Markdown](http://.........) John Gruber .......... * [CodeDown](http://.....) Home ....