This section summarizes the main features of Remark.
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.
The Remark syntax is just a slightly extended version of the Markdown syntax. This syntax fulfills the following goals:
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 library.
Remark extends the Markdown syntax with Latex math and AsciiMath syntaxes.
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}$.
The solution to the quadratic equation in AsciiMath is . The solution to the quadratic equation in Latex is .
Remark integrates the browsing of source code into the documentation. When viewing source code, it is color-encoded using the 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:
int square(int x)
{
return x * x;
}
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 Conversion.py (a Python source code file of Remark):
# Description: Conversions between Remark, Markdown, and html
# Documentation: algorithms.txt