Daniel's Log Book: Open source tools to document your software projects. Part 1: Markdown

In the past weeks I've been preparing a set of three posts on tools for document your software projects. The main goal is to introduce the tool and not to make a complete wiki, so don't expect any detailed descriptions.

Do you document your software?

Most of the scientist when asked for their software project's documentation [1]

As a ~~wannabe~~ scientist I'm aware of the need of having reliable registers about all the work related to any scientific task, such as experiments, simulations, math, results, and so on. Most of the logs are taken either in paper or by type writting to digital documents (LaTex or equivalents). When the project involves software most of the scientist are not so familiar with tools as Doxygen or Sphinx(to mention a couple) due to the needed learning curve: "Ain't nobody got time for that!!". And all the "documenting" lies on tons of commented code lines which rarely will be seen when using the libraries and stuff. In the process of developing and documenting my software I became aware of several tools which could come in handy to other scientist/programmers. That is the motivation to review three tools

Markdown
Pandoc
Doxygen

MARKDOWN [2][3]

Markdown is intended to be as easy-to-read and easy-to-write as is feasible,and is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).[3]
Created in 2004 by John Gruber and Aaron Swartz[2] Markdown provides a easy way to create HTML formatted filesout of plain text. Once the markdown file is parsed, one obtains a pretty good looking html wich can be embeded or distributed with your software in order to make more friendly the project, (or uploaded to your blog ;) ).

Every markdown file consist of plain text file with extension .md or .mkd (or without any extension since the processor that receives the plaintext file detects the markdown format. But is good to have an extension).

Markdown basics [4][5]

A good summary of Markdown syntax is [5]

Headers

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag

Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

*You **can** combine them*

Lists

Unordered

* Item 1
* Item 2
* Item 2a
* Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
* Item 3a
* Item 3b

Links

http://github.com - automatic!
[GitHub](http://github.com)

Blockquotes

As Kanye West said:

> We're living the future so
> the present is our past.

Inline code

I think you should use an
`<addr>` element here instead.

A good markdown how-to is provided by github

Example text [2]

A good example of a Markdown text is

Heading
=======

Sub-heading
-----------

### Another deeper heading

Paragraphs are separated
by a blank line.

Let 2 spaces at the end of a line to do a
line break

Text attributes *italic*, **bold**,
`monospace`, ~~strikethrough~~ .

A [link](http://example.com).
<<< No space between ] and ( >>>

Shopping list:

* apples
* oranges
* pears

Numbered list:

1. apples
2. oranges
3. pears

The rain---not the reign---in
Spain.

The parsed output is

Heading

Sub-heading

Another deeper heading

Paragraphs are separated by a blank line.

Let 2 spaces at the end of a line to do a
line break

Text attributes italic, bold, monospace, ~~strikethrough~~.

A link.

Shopping list:

apples
oranges
pears

Numbered list:

apples
oranges
pears

The rain—not the reign—in Spain.

Parsing the document

To parse markdown formatted text you need to have markdown installed on your system. Debian based should have markdown on their official repositories (Debian Jessie - Testing has it)

# apt-get install markdown

Should do the job (obviously as root user).

To parse the text

$ markdown mymark.md > mymarkparsed.html

The html file can be opened with your favorite web browser.

Some remarks

Given that Markdown does not count with any standard[2] several software organizations have developed markdown versions adding new features. One example is the git-flavoured markdown syntax as decribed on [5]
Once the markdown is parsed, one obtains a pretty good looking html wich can be embeded or distributed with your software in order to make more friendly the project.