Markdown syntax
===============

[[Parent]]: remark_syntax.txt

Here we provide a brief tutorial to the Markdown syntax
which is the basis on which Remark syntax has been built.
We provide an external link to complete documentation below. 

Markdown syntax
---------------

### Normal text

Normal text is generated simply by writing some.
Note that in Markdown new-lines do not start new lines
in the output. That needs an empty line.  

	Once upon a time there was an apple-worm...
	It was a very green apple-worm.
	
	Its home was built into a red apple. 

This produces:

Once upon a time there was an apple-worm...
It was a very green apple-worm.
	
Its home was built into a red apple. 

### Emphasized text

Emphasis can be added by using surrounding 
underlines:

	It was a _very_ green apple-worm.
	
	It was a __very__ green apple-worm.

	It was a ___very___ green apple-worm.
	
This produces:	

It was a _very_ green apple-worm.

It was a __very__ green apple-worm.

It was a ___very___ green apple-worm.

### Headings

The headings corresponding to html heading levels 1, 2, and 3,
respectively, are denoted as follows:

	Remark syntax
	=============
	
	Markdown syntax
	---------------
	
	### Headings

It would confusing to show here what these produce.
Instead, look at the corresponding headings on this page as 
examples of these headings.

### Verbatim content

Verbatim content can be written by indenting
the text. For example, this:

		Indented text.

produces this:

	Indented text.

The verbatim content is what we are using on this
page to demonstrate the syntax such that it isn't
interpreted as Remark code. In Remark, the indentation
is used invoke the indentation macro, which defaults
to the [Verbatim][VerbatimMacro]] macro.

[VerbatimMacro]: [[Ref]]: Verbatim_Macro.txt

### Tables

This

	First Header  | Second Header
	------------- | -------------
	Content Cell  | Content Cell
	Content Cell  | Content Cell

produces this:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

### Definition lists

This

	Apple
	:   Pomaceous fruit of plants of the genus Malus in 
	    the family Rosaceae.
	
	Orange
	:   The fruit of an evergreen tree of the genus Citrus.

produces this:

Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.

Orange
:   The fruit of an evergreen tree of the genus Citrus.

### Abbreviations

This

	The HTML specification 
	is maintained by the W3C.
	
	*[HTML]: Hyper Text Markup Language
	*[W3C]:  World Wide Web Consortium

produces this:

The HTML specification 
is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

### Links in Markdown

Links are created as follows:

	[Remark syntax][1]
	
	[1]: remark_syntax.htm

Here we have mimicked the way literature is cited
in scientific publications. However, instead of '1' there
could be an arbitrary link name. The previous
produces:

[Remark syntax][Remark_Syntax]

[Remark_Syntax]: remark_syntax.htm

### Links in Remark

While the Markdown linking mechanism is fine
(and required) for external links, you will want 
to use the Remark linking mechanism for links internal
to the documentation. This is because it is
able to automatically fetch information about the
target file, helping to keep the documentation in sync. 
For example:

	[[Link: remark_syntax.txt]]  
	
	[[FileLink: remark_syntax.txt]]
	
	[[DirectoryLink: remark_syntax.txt]]

produces:

[[Link: remark_syntax.txt]]  

[[FileLink: remark_syntax.txt]]

[[DirectoryLink: remark_syntax.txt]]  

When you need to give links specific names, use the following
syntax:

	[Remark syntax][2]
	
	[2]: [[Ref: remark_syntax.txt]]

This will produce:

[Remark syntax][2]

[2]: [[Ref: remark_syntax.txt]]

Remark linking relies on the [file searching algorithm][file-search], which 
is important to make the documentation robust to changes
in the directory structure.

[file-search]: [[Ref: file_searching_algorithm.txt]]

Links
-----

[Complete Markdown syntax documentation][Markdown_Syntax]

[Markdown_Syntax]: http://daringfireball.net/projects/markdown/syntax
