Introduction to MarkIt

Ceci est une introduction a MarkIt, un langage de marquage que je développe depuis Février 2019.

Ci dessous les liens vers les premières version du document au format ODT, LaTeX et HTML:

Ci dessous les liens vers la version mise à jour du document avec une prise en charge expérimentale des formules mathématiques et des tableaux:

Introduction to MarkIt
Introduction to MarkIt

Introduction to MarkIt

Jean-Luc JOULIN

Keywords : MarkIt, Presentation, LaTeX, Markdown, ReST, Markup

Introduction

This is the 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 :

  • LaTeX documents

  • HTML web pages

  • Open document files (ODT).

  • Docx documents (possibly).

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

  • Bullet lists.

  • Numbered lists.

  • Code snippets.

  • Figures.

  • Inlines images.

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.

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 :

  • Document title (Mandatory)

  • Name of the author (Mandatory)

  • Date of creation (Mandatory)

  • Keywords (Optional)

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↩
authors:·Jean-Luc·JOULIN↩
date·:·15/06/2019↩
keywords:MarkIt,·LaTeX,·Markdown,·...↩
---↩

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 :

  • Text paragraphs

  • Lists

  • Titles and subtitles

  • Environments

Inlines

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

  • Modify the text styles.

    • Bold font.

    • Italic.

    • Underlined.

    • ...

  • Make references to other elements.

    • Link to websites.

    • References to figures or titles.

    • Bibliography.

  • Add inlines images.

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↩
---------------↩

At this time, only three 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 indented4.

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

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 indented4.

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

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 :

  • footnotes command ^[identifier].

  • substitutions command :[identifier].

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: : 

allow the user to set the picture width.

:title: : 

Set the figure title.

:ref: : 

Set a reference to the figure.

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 format6 :

  • PNG For non destructives images (schemes, snapshots, ...).

  • jpeg For photography.

  • eps will be available with some improvements.

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)↩

References

It is possible to create link to some parts of the document with the command #[ref]. The reference must be a valid reference to a figure, or a section

Here are some reference to parts of this article.

Reference to figure 3 : figure 3

Reference to figure 1 : figure 1

Reference to section "Introduction" : §1

Reference to subsection "Blocks elements" : §3.1

Reference to subsubsection "Footnotes" : §3.2.10

Reference to subsubsection "Bullet list blocks" : §3.1.3

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 picturewarning symbolradioactive 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 replacement block.

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

Missing features

At this time, many features are missing or not fully functional.

Arrays

The main goal of MarkIt is to provide a standard support of arrays for scientific and engineering purpose.

Arrays are not supported at all at this time.

Mathematic formulas

The main goal of MarkIt is to provide a standard support of mathematic formulas for scientific and engineering purpose.

Math formulas are not supported at all at this time.

They will be probably used inside $$ like LaTeX but with a language closer than libre office than LaTeX7


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.

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

5.

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,...)

6.

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.

7.

I assume that if you're ok to deal with LaTeX math formulation, you're ok to deal with the whole LaTeX environment directly.