gmd-syntax.ebnf

@startebnf

gMD = { "eol" }, { Paragraph
                 | List
                 | Table
                 | Pragma }, { "eol" };

(*- any syntactically or semantically incorrect sequence is treated as ordinary text.
- comments go from "//" to end of line and are not rendered.
- gmd documents are exclusively ecoded with UTF-8, -16 or -32.*)

Paragraph = Indent, [ HeadingMarker ], Text, "eol", { Indent, 
                                                      Text, 
                                                      "eol" }, "eol";

(*- the indentation of the leftmost character defines the indentation of the whole paragraph.
- the indentation over multiple lines defines the horizontal alignment of the whole paragraph.*)

HeadingMarker = "#", ( { "#" } 
                     | number, ".", [ number, { ".", number }, ["."] ]
                     | "$", ".", [ "$", { ".", "$" }, ["."] ] );

(*- automatic numbering is obtained by using the "$" character instead of manual numbers.*)

Text = { Tag
       | Calc
       | Link
       | Image
       | Secret
       | HorRuler
       | NewLine
       | Modifier
       | EscapedChar
       | "chr" };

(*- only control characters (with the exception of eol and tab) are not allowed.
- it is the resonsibility of the authors to not create messy documents using weird unicode characters.
- a tab is always interpreted as the equivalent of 4 spaces
*)

Tag = StartTag | EndTag;

(*- usage of undefined tag(name)s is not allowed.
- gMD has predefined and reserved tag(name)s.
- new tag(name)s are defined using tag definition pragma elsewhere in the document.
- html tags are not allowed. *)

StartTag = "<", TagName, [ ":", TagValue ], [ "/" ], ">";

(*- tags without "/" must have an end-tag. 
- tags with "/" are considered auto-closing and must have no end-tag.*)

EndTag = "<", "/", [ TagName ], ">";

(*- if given, tag name must be the same as in the opening tag. *)

Calc = "=", "[", [ Title, ":" ], Expression, "]", [ "<", ActualValue, ">" ];

(*- every expression produces a value
- no state and no sideeffects at all
- giving the expression a title results in the definition of an equally named variable
- these variables can be used within expressions 
- gMD has predefined functions that can be used within expression
- additional functions can be defined using pragmas 
- the actual values are calculated at store-time, not at load-time!
- dealing with cyclic dependencies is author's responsibility.*)

Link = "[", ( Title, "]", "<", ( URL | LinkName ), ">" 
            | ( URL | LinkName ), "]" ); 

(* - link name usage requires a named link definition (pragma) elsewhere in the document.*)

Image = "!", "[", ( URL | DataURI | ImageName ), "]";

(* - image name usage requires a named image definition (pragma) elsewhere in the document.*)

Secret = "§", "[", ( Title, "]", "<", Base64EncryptedText, ",", Base64KeyFingerprint, ">" 
                   | SecretName, "]" ); 

(*- secret name usage requires a named secret definition (pragma) elsewhere in the document *)

Modifier = ( "**"
           | "~~"
           | "^^"
           | "__" );

(*- the sequence "**" is for bold on/off, "\~\~" is for italic on/off, "^^" is for suberscript on/off, "__" is for subscript on/off.*)

HorRuler = ( "-----"
           | "=====" );

(*- thin line: using "-" 
- thick line: using "="
- the lenght must be exact 5 characters*)

NewLine = "↵";

(*- unicode "downwards arrow with corner leftwards" (U+21B5). *)

EscapedChar = "\", "chr";

(*- escaped characters (preceeded by '\') are treated as ordinary characters and will be excluded from syntax analysis *)

List = ListItem, "eol", { ListItem, "eol" }, "eol";

ListItem = Indent, ListMarker, Text, { "eol", Indent, Text };

ListMarker = ( number, "."
             | letter, ")" 
             | "$", ( "." | ")" ) 
             | "*" 
             | "-" );

(*- manual numbered item: starts with number followed by ".". 
- manual alphabetical item: starts with letter followed by ")". 
- automatic numbered item: starts with "$" followed by "."; increments the preceeding item, default is 1. 
- automatic alphabetical item: starts with "$" followed by ")"; increments the preceeding item, default is a. 
- bullet list: starts with "*"
- dashed list: starts with "-" *)

Table = Row, "eol", { Row, "eol" }, [ TableFooter, "eol" ], "eol"; 

Row = [ RulerLine, "eol" ], ContentLine, { ">", "eol", ContentLine }; 

(*- multi-line rows are possible by the continuation-character ">" at the end of a content line. *)

TableFooter = RulerLine, [ "eol", FooterLine, { "eol", FooterLine }, "eol", RulerLine ], "eol" ;

RulerLine = "|", CellRuler, "|", { CellRuler, "|" };

ContentLine = "|", [ CellSpan ], Text, "|", { [ CellSpan ], Text, "|" };

(*- each cell can start with a colspan/rowspan definition.*)

FooterLine = "|", Text, "|";

(*- the footer line is reserved for future use and not allowed yet.*)

CellRuler = ( ":"
            | "="
            |"-" ), ( "=" 
                    | "-" ), { "=" | "-" }, ( ":"
                                            | "="
                                            | "-" );

(*- a ruler with "=" characters defines the cell above as header cell.
- a ruler with "-" characters defines the cell above as normal cell.
- a ruler with ":" defines the alignment for all cells below (until the appearance of the next ruler with ":").
- left-align: ruler starts with ":", right-align: ruler ends with ":", center-align: ruler starts and ends with ":".
- mixed usage of "=" and "-" is not allowed.*)

CellSpan = ( "/", [ number ], [ ">", [ number ] ] 
           | ">", [ number ] );

(*- colspan: starts with ">" followed by the number of columns to span; no number means 1.
- rowspan: starts with "/" followed by the number of rows to span; no number means 1.*)

Pragma = "$", ( IncludeDirective
              | TagDefinition 
              | NamedLinkDefinition
              | NamedImageDefinition
              | NamedSecretDefinition
              | FunctionDefinition ), ";";

(*- pragmas are not rendered.*)

IncludeDirective = "include", URL, [ "between", StartDelimValue, [ "and", EndDelimValue ] ];

(*- the document is processed after all includes have been loaded.
- the included file(s) are rendered as normal contents of the document.
- if start (and also end) delimiters are given, only the protion behind start (and also before end) is loaded.
- dealing with dependencies beween includes is author's responsibility.*)

TagDefinition = "tag", Identifier, ( [ "=", DefaultValue ] | ":", TagComposition);

(*- overriding of already defined or reserved tag(name)s is forbidden.
- gMD has predefined and reserved tag(names)s.
- DefaultValue is used in case no value is given.*)

TagComposition = TagName, [ "=", ActualValue ], { "+", TagName, [ "=", ActualValue ] };

(*- composed tags are made by one or more already defined tags.
- composed tags can be used only by ńame without assigning individual actual values.
- if not given, the actual value is becoming the default value for this tag.*)

NamedLinkDefinition = "link", Identifier, "=", URL;

(*- overriding of already defined link name is forbidden.*)

NamedImageDefinition = "image", Identifier, "=", ( URL | DataURI );

(*- overriding of already defined image name is forbidden.*)

NamedSecretDefinition = "secret", Identifier, "=", Base64KeyFingerprint, ",", Base64EncryptedText;

(*- overriding of already defined secret name is forbidden.*)

FunctionDefinition = "function", Identifier, "(", [ FormalParameters ], ")", ":", "{", { Statement, ";" }, "}";

FormalParameters = ? not yet specified ?;
Statement = ? not yet specified ?;
Expression = ? not yet specified ?;
Value = ? not yet specified ?;
number = ? not yet specified ?;

@endebnf