main_features.txt

Main features
=============

[[Parent]]: user_documentation.txt

This section summarizes the main features of Remark.

Unicode source files 
--------------------

The documentation in Remark is written in plain UTF-8 text files. UTF-8 is a (Unicode) 
text encoding scheme which is compatible with ASCII encoding in the sense that ASCII 
encoded text files are automatically valid UTF-8 text files. However,
in contrast to ASCII text files, a UTF-8 text file can also represent
the more exotic characters if needed. A UTF-8 text file consists of a sequence 
of Unicode characters, which you can edit using any plain-text editor.

Human-readable content description 
----------------------------------

The Remark syntax is just a slightly extended version of the 
[Markdown][Markdown] syntax. This syntax fulfills the following goals:
 
 * The representation is decoupled from the content.  
 * The content description is as human-readable as possible.
 * There is minimal redundancy. 

The first item means that the Remark syntax covers only structural matters 
(e.g. a section, a sub-section, a table, emphasis, etc.). The 
representation of the content (colors, fonts, etc.) can be 
arbitrarily changed later without touching the content (using _Cascading
Style Sheets_). Here's an example of the Remark syntax from the source of this page:

	### Human-readable, non-redundant content description 
	
	The Remark syntax is just a slightly extended version of the 
	[Markdown][Markdown] syntax. This syntax fulfills the following goals:
 
	 * The representation is decoupled from the content.  
	 * The content description is as human-readable as possible.
	 * There is minimal redundancy. 

The source code is first converted from Remark syntax to Markdown syntax
by expanding the Remark macros. After that the Markdown syntax is converted 
to html using the [Python Markdown][PyMarkdown] library. 

[Markdown]: http://daringfireball.net/projects/markdown/
[PyMarkdown]: http://www.freewisdom.org/projects/python-markdown/

Human-readable mathematics
--------------------------

Remark extends the Markdown syntax with Latex math and AsciiMath syntaxes. 

[[Example]]:
	The solution to the quadratic equation in AsciiMath is ''x = (-b +- sqrt(b^2 - 4ac)) / (2a)''.
	The solution to the quadratic equation in Latex is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.
	
Color-encoding of source code
-----------------------------

Remark integrates the browsing of source code into the documentation.
When viewing source code, it is color-encoded using the [Pygments][Pygments]
Python library. As an example, here's how to embed a source code 
snippet (C++ code):

	[[CppCode]]:
		int square(int x)
		{
			return x * x;
		}

And here's how it looks like:
		
[[CppCode]]:
	int square(int x)
	{
		return x * x;
	}

[Pygments]: http://pygments.org/

Automatic generation of links
-----------------------------

Usually each document in documentation can be given a title or some 
kind of a description. When building documentation manually, one
faces the task of building links between documents and naming
each of them with the description of the target document.
This becomes a maintenance problem very quickly because the link 
descriptions will need to be corrected every time the target 
document's description changes. Remark solves this problem by
embedding to each document its description. This way links can be
named automatically by fetching the description of the target
document. 

Most often a documentation has a tree structure. This means that each 
document has a well-defined parent document with the subject of the 
matter generalizing towards the parent. Again, when building links
between parents and children, one is faced with a maintenance problem:
if one changes a parent of a document, then one should remember to
remove a link from the old parent and insert a link to the new parent.
Remark solves this problem by embedding to each document its parent.
This way the links between a parent and a child can be generated
(and named) automatically. 

Documentation files such as this page have their descriptions set to 
their first heading from the top. Their parent documentation is given
like this:

	[[Parent]]: name_of_parent.txt 

The description and parent documentation for a source code file are 
embedded into it using comments. For example, here's
what reads at the start of the file [[FileLink: Conversion.py]] 
(a Python source code file of Remark):

	# Description: Conversions between Remark, Markdown, and html
	# Documentation: algorithms.txt