Hamill
++
This document describes in English the Hamill language. La documentation en français est disponible ici.
+Hamill is a lightweight markup language like Markdown, Textile, AsciiDoc or reStructuredText, to write documentation in a text file with structure information (headings, divisions, paragraphs) and formatting (bold, italics…).
+Its lightweight syntax makes it easier to read the text file directly than the corresponding HTML file. Hamill dœs, however, provide a tool for transforming a Hamill file (extension .hml) into an HTML file (extension .html).
Its syntax is both easier and more complete than that of the original Markdown from 2004.
+Hamill has been around since 2020, is currently at version 2 since 2022 and has two implementations that produce the same result:
+-
+
- the one in JavaScript with NodeJS is hosted by NPM: Hamill JS, +
- the one in Python 3 is hosted on PYPI: Hamill PY. +
The project's source code is available on GitHub.
+You can try it directly online
+The current version is 2.0.5. Hamill is released under the MIT license.
+Damien Gouteux 2020-2024
+This page has been translated from French to English with the help of DeepL Translator.
+Contents
+-
+
- Use +
- Comments, HR and BR +
- Titles +
- Text formatting +
- Div, p and span +
- Details +
- Code +
- Lists +
- Definition lists +
- Tables +
- Links +
- Images +
- Constants +
- Variables +
- Including HTML files +
- Linking to a CSS or JavaScript file +
- Special +
Use
+Hamill comes in the form of two scripts: hamill and weyland (extension .mjs for the JavaScript version and .py for the Python version). Weyland handles the lexical and syntactic analysis of the various languages, while Hamill transforms the Hamill file (.hml extension) into a document made up of several nodes. This document is then translated into HTML. To do this, Hamill is used on the command line:
++node.exe hamill.mjs +python.exe hamill.py ++
By default, it will display the help menu detailing the various commands available.
++Running Hamill v2.0.5 +--- +> Use hamill.mjs --process (or -p) <input config filepath> to convert the HML file to HTML + The file must be an object {} with a key named targets with an array value of pairs : + ["inputFile", "outputDir"] +> Use hamill.mjs --tests (or -t) to launch all the tests (99). +> Use hamill.mjs --eval (or -e) to run a read-eval-print-loop from hml to html +> Use hamill.mjs --help (or -h) to display this message ++
-
+
--process or -p: launches the translation of one or more hamill files into HTML. You must specify the path to a config file.
+ --tests or -t: launches the test suite.
+ --eval or -e: to launch a command prompt to enter hamill and see the result translated directly into HTML. Useful for testing.
+ --help or -h: to display this message (default behavior)
+
The configuration file is a JSON file with an object as its root. This object must have a targets key which is a list of pairs, the first element indicating the target hamill file, the second element indicating the directory where to put the result of the transformation into HTML. The result will have the same filename as the target hamill file, except that its extension will be .html instead of .hml. If the first element is the string "comment", this pair will be ignored.
++{ + "targets": [ + [ + "comment", + "Root pages" + ], + [ + "./input/index.hml", + "../" + ] + ] +} ++
Comments, HR and BR
+Comments can be made by putting !rem or §§ at the beginning of the line, and the entire line is then a comment.
+!rem This is a comment+
+§§ This is another comment
+
A line that is entirely a comment will be exported as HTML if the EXPORT_COMMENT variable is set to true.
A horizontal line can be made with a line consisting only of - of length greater than or equal to 3.
+---+
+
+
You can force a line break with ## surrounded by a space before and after it, and not at the beginning of the line (otherwise it's a title):
+this is a line break ##.+
+
this is a line break
.
Titles
+A number of # is placed at the beginning of the line, corresponding to the level of the title you want.
+### Level 3 title+
+
Text formatting
+-
+
- **bold**: to make bold (tag b) +
- !!bold!! for bold (tag strong) +
- ''italic'': to italicize (tag i) +
- //italic//: to italicize (tag em) +
- --
stroke--: to strike through
+ - __underlined__: to underline +
- ^^exponent^^: to put in superscript +
- %%index%%: to set an index +
- To escape a special character, use
\.
+
Div, p and span
+-
+
{{#id .class}}: on a single line, to define a div with an id and/or a class.
+ {{begin}}: on one line, to open a div without id or class.
+ {{end}}: on one line, to close an open div.
+ {{#id .class}} content: in a paragraph, specifies the paragraph id and/or class.
+ {{#id .class content}}: in a paragraph, specifies a span with an id and/or class.
+
+!css span.spoiler {background: black; user-select: none;}+
+!css span.spoiler:active {background: lightgrey; user-select: none;}
+This is text with a hidden part: {{.spoiler Darth Vader is Luke's father}}. To avoid spoilers.
+
This is a text with a hidden part: Darth Vader is Luke's father. To avoid spoilers.
+Details
+-
+
- Write
<<xxx -> yyy>>to open a short note. You can put an id and a class before xxx with#idand.class.
+ - Write
<<xxx>>to open a long note. put an id and a class before xxx with#idand.class.
+ - Write
<<end>>to close a long note. You can call up the id and class, but this has no meaning for Hamill.
+
+<<This is a short note.+
+
<<Short note → This is a short note.
++<<Long note+
+* This is a long note
+* With Hamill in it ##
+<<end>>
+
Long note
+-
+
- This is a long note +
- With Hamill in it +
Code
+We use @@for inline code@@. Hamill has a syntax colorizer for Python and JSON, so we specify : @@python def function(par1, par2)@@.
For a block of code, there are two solutions:
+You can start with a line containing only @@, followed by the language you want, and then continue with lines containing @@ at the beginning, up to a line containing only @@. For example:
+@@python+
+@@# This is a comment
+@@def function(par1, par2):
+@@ return "This is a function"
+@@
+
Gives :
++# This is a comment +def function(par1, par2): + return "This is a function" + ++
You can also make a line with only @@@ followed by the language you want, then lines with nothing up to a line with only @@@. For example:
+@@python+
+# This is a comment
+def function(par1, par2):
+ return "This is a function"
+@@@
+
Gives :
++# This is a comment +def function(par1, par2): + return "This is a function" ++
Lists
+-
+
*for an unnumbered list
+
-
+
+for a numbered list, item 1/2
+ +item 2/2
+
-
+
-for an inverted numbered list, item 1/2
+ -item 2/2
+
Definition lists
+-
+
- $ indicates a definition list. The definition is followed directly by spaces. +
+Cuirassier + heavily equipped mounted soldier ++
-
+
- Cuirassier +
- heavily equipped mounted soldier +
Tables
+-
+
- A table is written as follows:
|col1|col2|col3|
+ - The title line must be the first and separated from the others by a line of dashes:
|----|
+
| This | is | a | table |
|---|---|---|---|
| My | table | is | pretty |
You can, of course, add text modifiers, links or an image to an array.
+| This | is | a | table |
|---|---|---|---|
It  | is | a | table. |
You can also center a box by following the opening column with = and right-aligning with > :
| Left and also very long | Centered | Right |
|---|---|---|
| Right | Centered | Left and also very long |
You can also specify a colspan with #cVALUE# for example: #c3# and combine with centering =#c3# :
| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Centered and colspan=3 | ||
LIMITATION: no lists in a table
+Links
+-
+
- We use square brackets +
- The first "direct" form is
[[URL]],[[REF]],[#ID]. The URL, REF or ID will be displayed.
+ - The second form, called "named", is written
[[ displayed name -> URL | REF | #ID ]]or[ displayed name -> REF ].
+ - A URL begins with
http://orhttps://.
+ - A REF is defined by a line of the form
::code:: http://...
+ - A special form of the named is if REF is only
#as[[ displayed name -> # ]]: Hamill then tries to do on the transformed displayed name or, if the anchor dœsn't exist, the displayed name directly.
+ - Titles are automatically transformed into anchors by replacing spaces with - and lower-casing them: thus The Games becomes the-games. +
Images
+-
+
- We use parentheses
((url))like :((my_image.png))
+ - You can define a default directory where images will be taken with the variable
DEFAULT_FIND_IMAGE.
+
Constants
+Constants can be defined by putting !const at the beginning of the line. Constants can be defined anywhere in the document, but only once.
Some constants are predefined but have no value, so they can be defined once again:
+-
+
!const TITLE=titleto define the page title
+ !const ICON=iconto define an icon for the page
+ !const LANG=langto define the language used in the page
+ !const ENCODING=encodingto define the language used in the page, default is utf-8
+ !const BODY_CLASS=classto define the body class
+ !const BODY_ID=idto define body id
+
Some constants are predefined with a value, so cannot be redefined:
+-
+
!const VERSIONthe Hamill version used
+ !const NOWdisplays the day, month and year in a string in the format: Wednesday April 24, 2024.
+
For the display of the day in the week, only English and French are managed according to the LANG constant.
Variables
+Variables can be defined by putting !var at the beginning of the line. You can change the value of a variable by redefining it in the document as many times as you like.
-
+
!var EXPORT_COMMENT=true/falsespecifies whether comments will be exported as HTML or not
+ !var PARAGRAPH_DEFINITION=true/falsespecifies whether definition list dd's should be set in p tags
+ !var DEFAULT_CODE=python/jsonsets the default syntax highlighting of the code (none by default)
+ !var NEXT_TAB_ID=idsspecifies the id of the next array
+ !var NEXT_TAB_CLASS=clsspecifies the class of the next array
+ !var DEFAULT_PAR_CLASS=clsspecifies the default class of all following paragraphs
+ !var DEFAULT_TAB_CLASS=clsspecifies the default class for all subsequent tables
+ !var DEFAULT_FIND_IMAGE=pathspecifies a directory in which to fetch default images
+ !var NEXT_CODE_ID=idsspecifies the id of the next code block
+ !var NEXT_CODE_CLASS=clsspecifies the class of the next code block
+
If NEXT_TAB_CLASS and DEFAULT_TAB_CLASS are defined, the value of NEXT_TAB_CLASS will be used.
Including HTML files
+You can include an HTML file with !include at the beginning of the line. The content of the file will be copied directly into the document.
Linking to a CSS or JavaScript file
+We can link our document to a CSS or JavaScript file with the !require command at the beginning of the line.
The link to a required CSS (.css) file is automatically placed at the head of the HTML document.
+The link to a required JavaScript file (.js or .mjs) is automatically placed at the top of the HTML document.
+Special
+-
+
!css css-codeallows you to add css code
+ !html html-codeadds html code
+