GRM is a GeneRic Markup language

GRM is a configurable markup language for structuring text. It is aimed to be:

as flexible as XML;
as simple to parse as JSON;
as lightweight to write as Markdown.

An example of what is GRM

Let's say you are a student and you want to write your lessons in plain text. You want to export them as a local static website with links between lessons, a web design as fancy as this current website, flashy mathematical equations and diagrams all over the place. You want full control. In that case GRM is the right markup syntax for you.

We show step-by-step how to achieve this goal.

Define how you structure your documents

You define your own named nodes and their semantic. Named nodes can also have attributes. GRM in this regards is similar to XML.

Below is an excerpt of one of your lessons. The extension file for GRM documents is by convention .grm so you name your lesson quadratic-equation.grm. Let's compare this lesson written in GRM with its form in XML or JSON.

quadratic-equation.grm

{title Quadratic equation}

{p A {bold [color="red"] quadratic equation} is an equation with the following form.}

{math-figure
	ax^\{2\} + bx + c = 0
}

# TODO: write the solution equations.

{p If {math-inline a < 0} then the solution is an imaginary number.}

quadratic-equation.xml
<root>
	<title>Quadratic equation</title>

	<p>A <bold color="red">quadratic equation</bold> is an equation with the following form.</p>

	<math-figure>
		ax^{2} + bx + c = 0
	</math-figure>

	<!-- TODO: write the solution equations. -->

	<p>If <math-inline>a &lt; 0</math-inline> then the solution is an imaginary number.</p>
</root>


quadratic-equation.json
[
	{
		"name": "title",
		"attributes": {},
		"children": [
			"Quadratic equation"
		]
	},
	"\n\n",
	{
		"name": "p",
		"attributes": {},
		"children": [
			"A ",
			{
				"name": "bold",
				"attributes": {
					"color": "red"
				},
				"children": [
					"quadratic equation"
				]
			},
			" is an equation with the following form."
		]
	},
	"\n\n",
	{
		"name": "math-figure",
		"attributes": {},
		"children": [
			"ax^{2} + bx + c = 0\n"
		]
	},
	"\n\n\n\n",
	{
		"name": "p",
		"attributes": {},
		"children": [
			"If ",
			{
				"name": "math-inline",
				"attributes": {},
				"children": [
					"a < 0"
				]
			},
			" then the solution is an imaginary number."
		]
	},
	"\n"
]

A GRM document is collection of nodes: named nodes and text nodes. A named node starts by a { followed by its name then optionally its attributes between [ and ] followed by its child nodes and finally ends by a }. A Text node is just text. All in all, GRM is very similar to XML but with a more lightweight syntax.

Special characters must be escaped when you want to represent them as texts. To do that, simply put an \ before them. In the example, we escape the { and } in the math-figure node. This is way less cumbersome than how you escape characters in XML.

And finally you can put comments in your document. Put an # and the rest of the line is a comment ignored by the GRM parser. Comments are great! Comment your documents!

Write less with marks

If you write a lot of mathematical equations, you certainly do not want to write {math-figure ...} or {math-inline ...} constantly. Here comes the concept of marks to save your fingers.

Marks are characters you define to represent a named node. They are shortcuts to nodes. You define a mark start character and a mart end character, and everything between them are considered as children of the node it represents. You can use any visible characters, even emojis, as long as they are not special characters nor used to define other marks.

So let's define two marks for your example:

math-figure will be represented with a pair of £;
math-inline will be represented with a pair of $.

The lesson can now be written as the following.

Before

{title Quadratic equation}

{p A {bold [color="red"] quadratic equation} is an equation with the following form.}

{math-figure
	ax^\{2\} + bx + c = 0
}

# TODO: write the solution equations.

{p If {math-inline a < 0} then the solution is an imaginary number.}

After

{title Quadratic equation}

{p A {bold [color="red"] quadratic equation} is an equation with the following form.}

£
	ax^\{2\} + bx + c = 0
£

# TODO: write the solution equations.

{p If $a < 0$ then the solution is an imaginary number.}

Maybe you would like to use a pair of $$ to represent a math-figure node. This is not possible in GRM: only one character can start a mark and only one character can end a mark. This is on purpose to avoid confusion. For example in Markdown we use a pair of * to put text in italics and we use a pair of ** to put text in bold. So what does ***important*** represent? Is important in italics then in bold or is it in bold then in italics? No one knows.

Use verbatim mark

Now that you have marks, it is way more convenient to write mathematical formulas but you still have one annoying issue: you still need to escape special characters such as { and }. To remove this problem, GRM has a concept of verbatim marks. When a mark is verbatim, anything between its start character and its end character is considered as text. This is a bit equivalent with <![CDATA[ ... ]]> in XML or with ``...`` in Markdown.

Now if you define your marks as verbatim marks, you do not need to escape characters in them anymore.

Before

{title Quadratic equation}

{p A {bold [color="red"] quadratic equation} is an equation with the following form.}

£
	ax^\{2\} + bx + c = 0
£

# TODO: write the solution equations.

{p If $a < 0$ then the solution is an imaginary number.}

After

{title Quadratic equation}

{p A {bold [color="red"] quadratic equation} is an equation with the following form.}

£
	ax^{2} + bx + c = 0
£

# TODO: write the solution equations.

{p If $a < 0$ then the solution is an imaginary number.}

Keep all your definitions in a definition document

GRM defines a markup syntax but it does not define any semantic. The developers of the software parsing your documents are the ones who choose the meaning of the nodes, their attributes and the marks. The developer may be you.

GRM has a concept of definition document. This document lists what nodes, attributes and marks can be used. An important note: this document is not mandatory but it is mostly an indication. Yet we encourage any developers using GRM to write one, this is very handy for documentation.

The extension file for GRM definition documents is by convention .grmd so you name your definition document definition.grmd.

definition.grmd

The definitions for writing a lesson.

{node [name="title"] The lesson title.}
{node [name="p"] A paragraph.}
{node [name="bold"]
	Display the text in a bold format.
	{attribute [name="color" optional] The color to use, the value can be a keyword or an hexadecimal value.}
}
{node [name="math-figure"] Math equations displayed as a figure. The equations are written in LaTeX format.}
{node [name="math-inline"] Same as "math-figure" but display the equations in the line.}

{mark [name="math-figure" start="£" end="£" verbatim]}
{mark [name="math-inline" start="$" end="$" verbatim]}

You are now ready to use GRM

This tour provides you all the necessary information to write your GRM document.

If you use an existing software which uses GRM documents, check the GRM definition document of this software to know the semantic it uses.

To get familiar with GRM, try our GRM to HTML converter.

You can download the archive of the last version of this project.

The repository contains:

This whole website.
Parsers as libraries for multiple programming languages.
The language specification in plain English. If we do not have a parser in your favorite programming language, do not panic because we also provide a complete test suite which also includes a step-by-step test suite to make parser development as smooth as possible!
Tools such as a Vim plugin for dealing with GRM documents.

Why GRM?

Maybe after reading the previous example you still do not know who is the audience for GRM or why you should use it. We will try to answer these questions.

For whom?

GRM is designed for people who write text. It was born from the fatigue of writing all the cumbersome tags in XML and HTML when writing documentation or web pages.

GRM is designed for programmers who want to make their own software if no solutions for their needs exist. It is a well defined and easy to parse language so it should not be difficult to write a crude parser once and for all if no parsers are available, and to integrate it in a project.

For which usage?

If your goal is to structure data which have precise types or values: use JSON or XML instead of GRM. GRM sees the document as a collection of nodes containing attributes and strings. GRM does not define things like numbers or booleans.

If your goal is to structure textual documents that should be interpreted as-is by various software: use Markdown, Org, HTML, LaTeX or any of the already existing markup languages. GRM does not define any structural semantic such as bold texts, headings or links.

Now if your goal is to write documents that should be exported in other formats and if you want to have control on how your documents are interpreted: GRM is the markup language for you. GRM is the perfect companion when you want to create your own static site generator or your knowledge management system.

License

All the content of this repository which include those web pages, the language design, the tests, the parsers and the tools, are in the public domain or, in jurisdictions where you cannot put anything in public domain, the content is under the Unlicense which is defined as follows.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <https://unlicense.org/>