@the_dissidents/libemmm 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # libemmm
 
-This package contains the parser and language server for the `emmm` markup language. Will include renderers in the future.
+This package contains the parser and language server for the `emmm` markup language.
 
 ```sh
 npm install @the_dissidents/libemmm
@@ -28,7 +28,7 @@ let doc = emmm.parse(scanner, config);
 - `doc.messages` is the array of diagnostic messages.
 - You may want to call `doc.debugPrint(source)` to get a pretty-printed debug string of the AST.
 
-## Reference to `emmm` Syntax
+## A Semi-Technical Reference to `emmm` Syntax
 
 ![AST Structure](./doc-images/ast.svg)
 
@@ -60,7 +60,7 @@ This paragraph is NOT under foo, [.foo] but this immediately starts a new one un
 [.foo] ... and this is another block of foo.
 
 [.foo]
-[.foo] However, this is foo inside foo, since the outer foo hasn't encountered any block before the parser met the inner foo, which became the content of the outer one.
+[.foo] However, this is foo inside foo, since the outer foo hadn't encountered any block before the parser met the inner foo, which became the content of the outer one.
 
 [.foo]
 :--
@@ -164,7 +164,7 @@ A colon before the first argument states explicitly the beginning of that argume
 [**-define-inline** *name*:*args...*]  
 [**-define-inline** *name*:*args...*:(*slot*)]  
 
-> Define a new modifier. The first argument is the name. If more than one argument exist, and the last is enclosed in `()`, it is taken as the **slot name** (more on that later). The rest in the middle are names for the arguments.
+> Define a new modifier. The first argument is the name. If one or more arguments exist, and the last is enclosed in `()`, it is taken as the **slot name** (more on that later). The rest in the middle are names for the arguments.
 > 
 > Take content as the definition of the new modifier.
 
@@ -179,18 +179,26 @@ A colon before the first argument states explicitly the beginning of that argume
 
 > Not implemented yet
 
-[**-define-inline-shorthand** *opening*:*ending*:]  
-[**-define-inline-shorthand** *opening*:(*slot*):*ending*:]  
-[**-define-inline-shorthand** *opening*:(*slot1*):*mid1*:(*slot2*):*mid2*:(*slot3*)...:*ending*:]
+[**-define-inline-shorthand** *prefix*]  
+[**-define-inline-shorthand** *prefix*:(*slot*):*postfix*]  
+[**-define-inline-shorthand** *prefix*:*arg1*:*mid1*:*arg2*:*mid2*...]  
+[**-define-inline-shorthand** *prefix*:*arg1*:*mid1*:*arg2*:*mid2*...:(*slot*):*postfix*]  
 
-> Not implemented yet
+> Defines an inline shorthand. A shorthand notation consists of a prefix, zero or more pairs of argument and middle part, and optionally a slot and a postfix. You must specify a slot name if you want to use one, although you can specify an empty one using `()`. You may also specify an *empty* last argument, i.e. a `:` before the `]` that ends the modifier head, to make the postfix stand out better.
+> ```
+> [-inline-shorthand:\[!:url:|:():\]:] content
+> ```
+> This creates: `[!` argument:url `|` slot `]`
+> ```
+> [-inline-shorthand:\[!:url:|:text:\]:] content
+> ```
+> This creates: `[!` argument:url `|` argument:text `]`
+> 
+> Note the first shorthand has a slot, while the second doesn't. This means you can't put formatted content as text in the second shorthand.
 
-[**-push-notation**]  
-[**-pop-notation**]
+[**-use** *module-name*]
 
-> Pushes the current notation data (modifiers and shorthands) onto a stack, or pop the stack to revert to the situation before pushing.
->
-> This is useful, for example, when you implement a `[.table]` modifier and want to have a lot of shorthands for table rows and cells etc. that only function inside this modifier. In this case, functioning everywhere just doesn't make sense and pollutes the syntax.
+> Activates the definitions in a module for the whole document; see `[.use]`.
 
 ### Block modifiers
 
@@ -214,6 +222,14 @@ A colon before the first argument states explicitly the beginning of that argume
 > ```
 > Note the first, unnamed `.slot` refers to the slot of `q`.
 
+[**.module** *module-name*]
+
+> Causes the definitions in the content to become part of a **module**. They don't take effect outside the `[.module]` modifier *unless* activated by a `[.use]` or `[-use]` modifier.
+
+[**.use** *module-name*]
+
+> Activates the definitions in a module for the content *within this modifier*. Use `[-use]` to activate for the whole document instead.
+
 ### Inline modifiers
 
 [**/slot**]  
@@ -245,6 +261,8 @@ For strange edge cases of the basic syntax and the built-in configuration, see t
 
 ## Diagnostic Messages
 
+> Note: 'suggestions' are currently not being implemented
+
 |Code|Error|Suggestions|
 |---:|-----|-|
 |  1 | Syntax error: expecting <...>
@@ -257,11 +275,16 @@ For strange edge cases of the basic syntax and the built-in configuration, see t
 |  7 | Invalid entity in inline modifier definition
 |  8 | Reached recursion limit (<...>)
 |  9 | Slot modifier used outside a definition
+| 10 | Nested module definitions not allowed
+| 11 | Cannot use the same module inside its definition
+| 12 | A definition cannot be at once normal and preformatted
 
 |Code|Warning|Suggestions|
 |---:|-------|-|
 |  1 |Unnecessary newline(s)| *remove*
-|  2 | Block should begin in a new line to avoid confusion| *add a line break*
+|  ~~2~~ | ~~Block should begin in a new line to avoid confusion~~| ~~*add a line break*~~
 |  3 | Content should begin in a new line to avoid confusion | *add a line break*
 |  4 | Modifier already defined, overwriting
 |  5 | Undefined variable, will expand to empty string
+|  6 | Using this module will overwrite: <...>
+|  7 | <...> is already defined (as <...>), will be overwritten