docs/vnrs_specification.md

@@ -8,9 +8,9 @@ Vinora Screenplay is plain text format for writing
 [visual novel](https://en.wikipedia.org/wiki/Visual_novel) screenplays.
 
 It's based on (and one-way compatible with) Markdown, simple markup language 
-developed by John Grubber and Aaron Swartz in 2004. It was developed to 
+developed by John Gruber and Aaron Swartz in 2004. It was developed to 
 simplify web pages writing.  
-While Markdown originally doesn't have specification (only `Markdown.pl`
+While Markdown originally doesn't have a specification (only `Markdown.pl`
 as a reference implementation), we use
 [CommonMark](https://spec.commonmark.org) for this role.
 
@@ -18,9 +18,9 @@ as a reference implementation), we use
 Vinora Screenplay is designed for use in the Vinora Engine. The goals of this
 visual novels engine is to be as simple and compatible as possible.
 
-Markdown is a popular format. There is a good change that you're already
+Markdown is a popular format. There is a good chance that you're already
 familiar with \**italic*\* or \_\___bold__\_\_ syntax. So, by making 
-Vinora Screenplay as Markdown-like language we fulfill both of our goals 
+Vinora Screenplay a Markdown-like language we fulfill both of our goals 
 (it's simple to use since it's known and it's compatible with dozens
 of existing Markdown interpreters).
 
@@ -59,7 +59,7 @@ carriage return, line feed, form feed.*
 
 **Line**  
 is a sequence of zero or more characters, that ends with newline 
-or End Of File (EOF) condition. Line which has zero characters or only 
+or End Of File (EOF) condition. Line that has zero characters or only 
 whitespace characters is called an **empty line**. 
 
 **Paragraph**
@@ -74,7 +74,7 @@ characters from ASCII is supported by nearly every computer.
 ## 2.2 Visual novels definitions
 (Only technical definitions goes here)
 
-**Visual novel** *(from [VNDB](vndb.org/d6))*  
+**Visual novel** (from [VNDB](https://vndb.org/d6))  
 A visual novel can be seen as a combination of a novel and a computer game:
 they're computer games with a large text based storyline and only little 
 interaction of the player.  
@@ -120,7 +120,7 @@ Since all possible symbols fit in UTF-32 (or any other
 Therefore, line buffer should be 320-512 bytes.
 
 
-**For example ( '__' symbolise two spaces):**
+**For example ( '__' symbolizes two spaces):**
 ```
 1   One-line chunk with some text and two spaces:__
 2
@@ -134,7 +134,7 @@ Therefore, line buffer should be 320-512 bytes.
 10
 11
 12
-13  It's doesn't matter how much empty lines are between chunks.
+13  It doesn't matter how many empty lines are between chunks.
 ```
 
 ## 3.2 Chunk types
@@ -248,4 +248,117 @@ Chapter screen chunks are working like Markdown headers:
 ```
 In-game, it would be chapter screen.
 
+### 3.2.4 Choice chunk
+With bullet points and link we can give player a choice:
+
+```markdown
+1   @ALICE__
+2   Should I go with Bob or Chloe?
+3
+4   + [I will go with Bob](bob_route.vnrs)
+5   - [(TODO) I will go with Chloe](chloe_route.vnrs) 
+6   * [Go alone](secret_route.vnrs){social<0}
+```
+
+In Markdown, it doesn't matter which sign you use (+ / * / +), but 
+in Vinora Screenplay they have their own functionality:
+
+'+' is for ordinary choices  
+'-' is for blocked choices. They are viewable but can't be chosen. It's
+useful for planning future chapters.  
+'\*' is for hidden choices. They are only viewable if the condition in  
+{} brackets is true.
+
+### 3.2.5 Link chunk
+Goto statements are considered harmful since 
+[1968](https://dl.acm.org/doi/epdf/10.1145/362929.362947). 
+
+Well, **sometimes** they are useful. More often they are harmful. 
+
+Good news is we can easily avoid them by using Markdown links:
+
+```markdown
+1   Let's call this a day...
+2
+3   + [](next_day.vnrs)
+```
+**Yes, it's just a single choice chunk.** 
+
+This is how we can go from one file to another. Writing anything *after*
+is kinda useless, since it can't be viewed anyway.
+
+
+### 3.2.6 Images chunk
+Markdown only supports images embedding, so this chunk exists solely for
+character sprites and backgrounds.
+
+```markdown
+1   ![](sprites/alice/normal.png){left}
+2   @ALICE__
+3   Hi there!
+4
+5   ![](sprites/bob/happy.png){right}
+6   @BOB__
+7   Hello, nice to meet you!
+8
+9   ![](bg/office/evening.png)
+```
+
+Images with `sprites` path work like sprites and `bg` works like 
+backgrounds. For both of them we can specify additional attributes
+through `{}`, but if no attributes specified engine should 
+automatically place characters without collision (from left to right).
+
+### 3.2.7 Media chunk
+This is for audio and video. Well, we can't embed them with Markdown,
+so we use link-like syntax:
+
+
+```markdown
+1   [](sound/bell.mp3)
+2   [](music/.mp3)
+3
+4   [](video/intro.mp4)
+```
+
+Any audio placed in `sound` directory would be played once. `Music` in 
+eponymous directory will be played on repeat.
+
+Any audio is playing in background, but `video` is played *instead* of
+text (and no layer can be over it). Video played once, then parser
+reads further.
+
+In HTML, they all will be embedded. User should click to play them, sadly. 
+
+### 3.2.8 Commentary chunk
+
+In Markdown, we have quotes with this kind of syntax:
+
+```markdown
+1  >This is a quote!
+```
+
+In Vinora Screenplay, they are used as comments. Parser will ignore it,
+unless he's working in `DEBUG` mode.
+
+### 3.2.9 Directive chunk
+
+Right now it's only used to change display mode from/to NVL/ADV.
+Syntax is double curlies:
+
+```markdown
+1  {{NVL}}
+```
+
+### 3.2.10 Literal chunk
+
+If you want dialog chunk to have no inline markup, you can wrap
+it with triple graves:
+
+```
+1  ```
+2  **This text will _be_ *printed* as it is**.
+3  ```
+```
+
 ## 3.3 Inline parser