Introduction to MarkIt v03

Introduction

This is an introduction to the MarkIt markup language. MarkIt is a prototype of markup language made to balance leaks in the existing markup languages such as MarkDown1 or ReST2. MarkIt is developed with the Haskell3 programming language for a fast development and to enhance performance, reliability and portability.

The aim of MarkIt is to provide a common markup language to generate :

MarkIt can handle various of document formatting and structures such as :

The basic way to use MarkIt is :

  1. Write a text file in the MarkIt format with any text editor.

  2. Read the file with the parser program to test it and detect some errors.

  3. Generate the output file with a dedicated compiler for :

    • HTML document.

    • LaTeX .tex file to be compiled with pdflatex or xelatex.

    • ODT OpenDocument readable with LibreOffice or MSOffice.

    Standards kind of documents are provided for several usages:

    Article
     
    Report / 

    to write a more complex document containing several chapters, preambles, postambles and possibly annexes4.

    Book
     

Document structure

File Header

The file header is the very first part of a document.

The file header contains informations about the document creation. The common informations are :

It is separated from the content of the document by 3 dashes ---

The header of this document is defined like this :

---
title: Introduction to MarkIt v03
authors: Jean-Luc JOULIN
date : 2021/04/21
keywords:MarkIt, Presentation, LaTeX, Markdown, ReST, Markup, Math, Engineering
docref:introduction-to-markit-v03
---

Blocks

The document is made of blocks which provide a specific behaviour to the document separated by at least 1 blank line.

The main blocks are :

Inlines

Inlines are the content of blocks and can be freely used inside of them. They provide functions to :

Details of elements

Blocks elements

Blocks are the basics way to organize the code. Blocks are separated by 1 or more blanklines and have a different behaviour on the output.

Blocks are made of inlines (see bellow) and must be used with the same indentation.

Paragraphs

This is the basic block. It is composed by many lines of strings. This is a example of paragraphs:

Blocks are the basics way to organize the code.
Blocks are separated by 1 or more
blanklines and have a different behaviour
on the output.

Blocks are made of inlines (see bellow)
and must be used with the same indentation.

To begin another paragraph, leave 1 or more blanklines between two paragraphs.

Header blocks

The header blocks are used to structure the document by defining sections.

A header is defined by giving a title underlined by a serie of unique chars. According to the char, the level of the section is different.

Section
#######

Sub section
===========

Sub sub section
---------------

Sub sub sub section
^^^^^^^^^^^^^^^^^^^

At this time, only four level of section can be defined in a MarkIt file. This can be changed in the future.

Bullet list blocks

A bullet list can be produced by using a succession of asterisk (*) followed by a incremented list of block. The asterisk musn't be indented5.

The kind of bullet is set by the style of the document in the writing process and can't be changed by the user6.

This an example of bullet list :

* First element in the bullet list.

* Second element in the bullet list.
  More information about the element.
  
  More information.

Numbered list blocks

A numbered list can be produced by using a succession of sharps sign (#) followed by a incremented list of block. The sharps musn't be indented5.

The kind of numbering is set by the style of the document in the writing process and can't be changed by the user6.

This an example of numbered list :

# First element in the numbered list.

# Second element in the numbered list.
  More information about the element.
  
  More information.

Replacement blocks

Replacement block are used to describe a piece of document which can be called anywhere in the document by :

A replacement block begin with [identifier]: and is followed by an increment list of blocks. Here is an example of substitution block :

[identifier]:
  This is different from other markup languages
  where the asterisk must be indented.

Figure environment

The figure environment allow the user to place a picture inside the document with various options to tweak the final result. The allowable options are :

:width:
 
:title:
 
:ref:
 

The following code snippet is used to generate the figure bellow.

::figure
  :file: EPR-854x569.jpg
  :title: A photography of the EPR vessel in jpeg format (default width)
  :ref: firstfigure

::figure
  :file: IRSN-schema-cuve-EPR.png
  :title: A scheme of the EPR vessel in png format (width = 50% of line width)
  :ref: secondfigure
  :width: 50%

::figure
  :file: cuve-epr_image.jpg
  :title: Another photography of the EPR vessel in jpeg format (fixed width to 2 centimeter)
  :ref: anotherfigure
  :width: 2cm
Figure 1 : A photography of the EPR vessel in jpeg format (default width)
Figure 2 : A scheme of the EPR vessel in png format (width = 50% of line width)
Figure 3 : Another photography of the EPR vessel in jpeg format (fixed width to 2 centimeter)

MarkIt support these commons images format7 :

Text Style (Inlines)

Bold text

The text can be written with a bold font by surrounding it with two asterisks ** like this **bold text**. It give the following result:

Normal text and some bold text

Emphasis

The text can be written with a emphasis font by surrounding it with one asterisks * like this *emphased text*. It give the following result:

Normal text and some emphased text

Underlined

The text can be underlined by surrounding it with two underscores _ like this __underlined text__. It give the following result:

Normal text and some underlined text

Strikeout

The text can be striked out by surrounding it with two tildes ~ like this ~~underlined text~~. It give the following result:

Normal text and some striked out text

Underscript (indice)

The text can be written with a undercript font size by surrounding it with one underscore _ like this _underscript text_. It give the following result:

Normal text and some underscript text

Superscript (exponent)

The text can be written with a superscript font size by surrounding it with one circumflex ^ like this ^superscript text^. It give the following result:

Normal text and some superscript text

External links can be included with the command @[link](text). External links can be websites addresses or filepaths.

The text can handled all the text styles available.

This is some examples of links: Link to my personnal website and Another link to my personnal website with markups

generated with the commands :

@[http://www.jeanjoux.fr/](Link to my personal website)

@[http://www.jeanjoux.fr/](Another *link* to _my_ **personal website** with markups)

Links allow the user to create a connexion to a reference or (IDentifier). It's possible to link to :

Here are some links to parts of this article.

Link to figure 3 : figure 3

Link to figure 1 : figure 1

Link to section "Introduction" : §I

Link to subsection "Blocks elements" : §III.1

Link to subsubsection "Footnotes" : §III.2.k

Link to subsubsection "Bullet list blocks" : §III.1.c

Link to the reference section : !!! ID introduction-to-markit-v03:ref not found !!!

References

It is possible to create a reference to some parts of the document with the command #[ref] and refere to it anywhere with @[ref]

Inlines images

An inline image can be included in a paragraph with the command ![]()

An inline image has its height fixed to the font size and cannot be changed. This is some examples thumb
 
up
 
picture
warning
 
symbol
radioactive
 
symbol
of inline image.

These image have their height fixed because they are included in a text. A specific case of inlines image exist when they are in paragraph without any text. In this case image have their width adjusted to a given width proportionally to the number of images.

This is an example of this specific case:

thumb
 
up
 
picture
warning
 
symbol
radioactive
 
symbol

generated with the command :


![thumb-up.png](thumb up picture)
![warning.png](warning symbol)
![radioactive2.png](radioactive symbol)

Note that inlines images can't be referenced and linked in the document. That's another difference with figures.

Footnotes

Footnotes can be included by using the command ^[footnote identifier]. Footnotes identifiers are uniques and are used to identify the footnote. The footnote must be described in a footnote block.

If the footnote identifier is missing, an error is throw by the MarkIt parser

Fields

Fields can be used to place value inside a note. A field can contain only a string of char and is made to put a value inside a document8.

Fields are designed to be set outside the MarkIt file in another definition file.

If a field is not defined, it will be shown in the final doc as the field name surrounded by <$ and $>.

For an exemple the field $[field1] hold : <$field1$>

The field $[field2] hold : <$field2$>

The field $[field3] hold : <$field3$>

The field $[field4] is not defined : <$field4$>

Mathematic formulas

The main goal of MarkIt is to provide a standard support of mathematic formulas for scientific and engineering. Mathematic formulas can be written within $ using a specific language nearest from this used in Libre Office than LaTeX9.

Like images, math behaviour is different when written inside a paragraph or outside.

This is some inlines formulas x2a2+y2b2=1, a=110a=55, 13x2dx and below some math formulas in block style.:

x 2 a 2 + y 2 b 2 = 1 a = 1 10 a = 55 1 3 x 2 d x = [ x 3 3 ] 1 3 = 27 3 - 1 3 = 26 3 1 3 x 2 d x cos 2 ( α ) + sin 2 ( α ) = 1

uv=(u2v3-u3v2u3v1-u1v3u1v2-u2v1)

Arrays

A basic support for arrays is provided by MarkIt

Header 1

Header 2

Header 3

Header 4

Line 2

412.7

47235.45

the
 
Haskell
 
logo

Line 3

478.25

91.2

A very simple trigonometric math formula

cos 2 ( α ) + sin 2 ( α ) = 1

Line 4

762.74

915.45

35.2

Header 1

Header 2

Header 3rv ervew vervw

Header 4

Line 2

412.7

47235.45

the
 
Haskell
 
logo

Line 3egg seg

478.25

91.2

A very simple trigonometric math formula

cos 2 ( α ) + sin 2 ( α ) = 1

Line 4

762.74

915.45

35.2 ef zef ezg zgreg z


Notes

1.

Markdown is limited because it cannot handle array and internal links natively.

2.

ReST has no precise standard and reST is used by the Sphinx documentation tool and the docutils utilitie.

3.

Haskell is truly a very powerful programming language. It is reliable, efficient, strong and statically typed and even its logo the
 
Haskell
 
logo
is stylish. Have a look on its website to have more informations about Haskell.

4.

Not implemented yet!

5.

This is different from other markup languages where the asterisk must be indented.

6.

This is different from other markup language where the kind of bullet and numbering is set by the user (* for a bullet, - for a hyphen, I. for a roman numbering,…)

7.

This small number of format is due to some limitations with the output writers and the wish to homogenize the formatting of the documents.

  • PDF images can be used with LaTeX but not with LibreOffice.

  • wmf can be used with LibreOffice but can't be used by LaTeX.

  • Many other image formats are obsolete or too fewly used.

8.

At this time, it is not possible to format fields to a specific format such as scientific/ingeneer notation. But this feature will be implemented soon.

9.

I assume that if you're ok to deal with LaTeX math formulation, you're ok to deal with the whole LaTeX environment directly and you don't need to use MarkIt