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?
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 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).
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
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.
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.
Shopping list:
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.
References
- "Ain't no body got time for that"
- http://en.wikipedia.org/wiki/Markdown
- http://daringfireball.net/projects/markdown/
- http://daringfireball.net/projects/markdown/syntax
- https://guides.github.com/features/mastering-markdown/
- http://en.wikipedia.org/wiki/Markdown#Example
