HEML - Human Editable Markup Language (yet another)

XML files, while growing, can quickly become very difficult to edit using an average text editor or even a more advanced software development advanced editor. Graphical XML editors are very efficient to update a few attributes or elements but are not comfortable for long writing sessions.

Rich editors and modern word processing applications are very efficient to edit some well defined XML formats such as docbook and xhtml but are quite difficult to configure to any user format. Wiki formats (wkiktext, confluence, and others) are by designed efficient for on line ASCII editing then easy to handle with any text editor. But those formats are not as generic than XML and are not very helpful for anything else than document editing.

HEML design is inspired from wikitext but targets to be functionnaly equivalent to XML and allow editing of any kind of data, not only documents for human readers.

More than just a document format, combination of the include and table feature will help to migrate legacy data format (for now limited to ASCII format) to XML. Then the HEML processor performs as a revers XLS processor able to support easy translation from ASCII more or less delimited files to XML.

Because readable, it is as easy to track change, merge, than programming language source code, and software development tools can support HEML management, in particular build tools (make) and SCM (subversion, git, ...).

Main features are:

While processing, some layout information may be lost. Then, after automatic processing, it is not always possible to restore a document that is still optimised for human edition.

In a same way, some layout and special features are lost when translating document to XML format and the exact reverse process can't be realized.

Those two drawbacks make HEML a human editable Only markup language.

Full changelog is available from EGPI tasks and issues management.

Element's names starting with '?' character are handled as parser command. Currently supported commands are:

• %encoding: specify which character encoding to use to parse the file.
• %tab: defines the character count for one tab character while text computing indentation levels (see paragraph layout examples above).

The HEML table feature let concise tabular data writing and also import legacy CSV files. Some attributes are available to configure the parser behavior to handle the table content:

{?table %record=tableRowName %fields=field1,field2,field3
un		% un1		% un2
deux	% deux1	%	% deux3
trois	% trois1	% trois2 % trois3
}		
		

<tableRowName>
	<field1>un</field1>
	<field2>un1</field2>
	<field3>un2</field3>
</tableRowName>
<tableRowName>
	<field1>deux</field1>
	<field2>deux1</field2>
	<field3/>
	<f1>deux3</f1>
</tableRowName>
<tableRowName>
	<field1>trois</field1>
	<field2>trois1</field2>
	<field3>trois2</field3>
	<f1>trois3</f1>
</tableRowName>
		

{?table %record=tableRowName %style=attr %fields=field1,field2,field3
un		% un1		% un2
deux	%% deux2		% deux3
trois	% trois1	% trois2 % trois3
quatre	% quatre1
}
		

<tableRowName field1="un" field2="un1" field3="un2"/>
<tableRowName field1="deux" field2="" field3="deux2">deux3</tableRowName>
<tableRowName field1="trois" field2="trois1" field3="trois2">trois3</tableRowName>
<tableRowName field1="quatre" field2="quatre1"/>		
		

{?table %fieldSep=" \t" %token=true
a	b	c	d		e
1	        2	3	4
}
		

<tr>
	<td>a</td>
	<td>b</td>
	<td>c</td>
	<td>d</td>
	<td>e</td>
</tr>
<tr>
	<td>1</td>
	<td>2</td>
	<td>3</td>
	<td>4</td>
</tr>		
		

{?table %src=test.csv %fieldSep=;}
		

1;2;3;4;5;
;;;;;
;;III;;V;
a;b;c;d;e;f
		

<tr>
	<td>1</td>
	<td>2</td>
	<td>3</td>
	<td>4</td>
	<td>5</td>
</tr>
<tr/>
<tr>
	<td/>
	<td/>
	<td>III</td>
	<td/>
	<td>V</td>
</tr>
<tr>
	<td>a</td>
	<td>b</td>
	<td>c</td>
	<td>d</td>
	<td>e</td>
	<td>f</td>
</tr>		
		

Wiki markups are designed to allow easy in line edition from a simple text field. But the purpose is first to support documents writing. Trying to edit any kind of data like with XML is probably possible but leads to some kind of brainfuck like naming and coding convention above the standard markups to make any data processable.

See Wiki markup wikipedia page to know more about the many wiki markup languages.

YAML's basic purpose is very similar to HEML's one: enabling easy manual data edition. But it's primary focus is data, and promote lists to handle data. May be I didn't realized what YAML is before I started coding HEML. I just found YAML was not what I searched and hope HEML is more convenient particularly for documents writing. At least it is the case for me!

See also YAML home page.

Txt2tags can be view as wiki markup precursor and suffers the same limitation when used to edit data that are not readable documents.

JSON features are very close to YAML and like YAML seems more focused to complex data serialization support and not best suited to direct and manual document edition. It is directly related to javascript, even it is usable with any programming language thanks to the many libraries available.

See also JSON home page.

Of course, you can edit directly XML, HTML, XHTML... But it's quite boring because of its heavy markup (opening and ending tags, < and > for each, quotes for attributes). HEML is the same but requires fewer markups then less characters to type. Moreover, paragraph layout feature inspired from wiki markups and txt2tags keeps HEML document accessible to the human eye.