docs rework

vns-docs/docs/tutorials/basic_tutorial.md

@@ -1,31 +1,47 @@
 # Basic Tutorials:
 
-### The Basics of VNS
+## The Basics of VNS
 
-VNS are written in a plain text file with the `.vns` extension. Imagine a script filled with descriptions, dialogues, and choices. VNS uses special tags to turn this script into an immersive experience, complete with characters, backgrounds, music, and branching narratives.
+VNS (Visual Novel Script) is a scripting language used to create interactive visual novels. These scripts are written in plain text files with the `.vns` extension. Imagine crafting a story filled with descriptions, dialogues, choices, and multimedia elements like images and music. VNS uses special tags to transform your script into an immersive experience featuring characters, backgrounds, music, and branching narratives.
 
-### **Let's dive into the building blocks:**
+## Let's dive into the building blocks:
 
-**1. The tag party:**
+### 1. Tags:
+Tags are the core elements of VNS. They instruct the program on how to display content. Enclosed in square brackets, tags help define scenes, characters, backgrounds, and more.
 
-Tags are the secret sauce of VNS. They tell the engine what to display.
+### 2. Essential tags:
 
+Here are some of the most commonly used tags in VNS:
 
+- **ID:** `[id]string`
 
-**2. Essential tags:**
+  Defines the unique identifier of the script.
 
-- **ID:** `[id]string` defines the ID of the script
-- **Language:** `[language]string` specifies the language of the script.
-- **Section:** `[section]string` specifies the section of all the following dialogues.
-- **Background Image:** `[bgi]string` specifies the background image for the current and following dialogues.
-- **Background Music:** `[bgm]string` specifies the background music for the current and following dialogues.
-- **Show Character(s):** `[show]*string(s)` introduce the character to the current and following dialogues.
+- **Language:** `[language]string`
 
+  Specifies the language of the script.
 
+- **Section:** `[section]string`
 
-**3. A glimpse into storytelling:**
+  Denotes a new section in the script.
 
-Imagine this simple scene:
+- **Background Image:** `[bgi]string`
+
+  Sets the background image for the current and subsequent dialogues.
+
+- **Background Music:** `[bgm]string`
+
+  Sets the background music for the current and subsequent dialogues.
+
+- **Show Character(s):** `[show]string(s)` 
+
+  Introduces (new) character image(s) to the scene.
+
+### 3. A glimpse into storytelling:
+
+Let's put these tags into action with a simple example.
+
+#### Example Script
 
 ```vns
 [id]1
@@ -34,13 +50,27 @@ Imagine this simple scene:
 
 [bgm]music1.ogg
 [bgi]bg1.png
-[show]example.png
+[show]character.png
 
-Example:
+Alex:
 - Hellow world!
 ```
 
-Restult:
+#### Explanation
+
+- `[id]1`: Sets the script ID to "1".
+- `[language]English`: Specifies that the script is in English.
+- `[section]dialog_example`: Begins a new section called "dialog_example".
+- `[bgm]music1.ogg`: Plays "music1.ogg" as background music.
+- `[bgi]bg1.png`: Displays "bg1.png" as the background image.
+- `[show]character.png`: Shows "character.png" on the screen.
+- `Alex:`: Indicates that the following dialogue is spoken by "Alex".
+- `- Hello, world!`: The dialogue line spoken by the character.
+
+#### Expected Output
+
+When compiled, the script should produce a JSON representation like this:
+
 ```json
 {
     "compiler": {...},
@@ -50,26 +80,26 @@ Restult:
                 "background_image": "bg1.png",
                 "background_music": "music1.ogg",
                 "character_images": [
-                    "example.png"
+                    "character.png"
                 ],
                 "contents": [
                     "Hellow world!"
                 ],
-                "narrator": "Example"
+                "narrator": "Alex"
             }
         }
     },
     "id": "1",
     "language": "English"
 }
 ```
-See how tags build a scene, introduce characters?
+This JSON structure represents how the script is interpreted, showing the background, music, characters, and dialogue content.
 
 
 
-**Ready to explore more?**
+## Ready to explore more?
 
-This is just the beginning! Check out the VNS documentation for in-depth details. Remember, practice makes perfect. Start simple, experiment, and most importantly, have fun creating your unique stories!
+This is just the beginning! Check out the documentation for in-depth details. Remember, practice makes perfect. Start simple, experiment, and most importantly, have fun creating your unique stories!
 
 
 

vns-docs/docs/tutorials/comments_and_notes.md

@@ -6,7 +6,7 @@
 // Comments are essential for readability and maintenance.
 ```
 
-Comments are lines of text in a script that are not executed by the compiler. They are used to annotate the code for better understanding by developers, collaborators, and future maintainers. Comments can include explanations of script logic, TODOs, or any relevant information regarding the script's functionality or design.
+Comments are lines of text in a script that are ignored during execution. They provide helpful annotations, making the code more understandable to developers, collaborators, and future maintainers. Typical uses of comments include explaining code logic, outlining TODOs, and offering relevant insights into the script’s functionality or design.
 
 # Notes:
 
@@ -16,4 +16,4 @@ Comments are lines of text in a script that are not executed by the compiler. Th
 # They are retained in the source file and can provide context for future modifications.
 ```
 
-Notes serve a purpose similar to comments but are often more informal and targeted at specific discussions or reminders. They can include explanations, insights, or reminders for developers working on the scripts. Unlike comments, which are typically removed during compilation , notes are retained in the source file to provide ongoing context.
+Notes serve a purpose similar to comments but are often targeted at specific dialogue instances or sections within the code. They can include explanations, insights, or reminders for developers working on the scripts. Unlike standard comments, which are typically ignored or removed during compilation or execution, notes will be processed and retained to provide ongoing context.

vns-docs/docs/tutorials/dialogues.md

@@ -8,9 +8,13 @@ Character name:
 - Additional dialogue text
 ```
 
-Each dialogue begins with the name of the character speaking, followed by a colon. Subsequently, the dialogue lines are presented with a hyphen and a space at the beginning of each line.
+Each section starts with the character's name followed by a colon. The dialogue lines are then listed with a hyphen and a space before each line. This clear structure helps maintain readability and ensures it’s easy to track the speaker throughout the script.
 
-This format ensures clarity and consistency in representing conversations within the script. By adhering to this structure, it becomes easier for readers to follow the flow of dialogue and understand who is speaking at any given moment. Additionally, the use of consistent formatting aids in maintaining the script's readability and comprehensibility.
+## Key Points:
+
+- **Character Name**: Placed at the start of the dialogue block, followed by a colon.
+- **Dialogue Line(s)**: Begin with a hyphen and space before each line of dialogue.
+- **Consistency**: Using this consistent structure enhances the script’s flow and makes conversations easy to follow.
 
 ### Example:
 
@@ -19,3 +23,5 @@ Mabel:
 - Hello, my name is Mabel!
 - How are you doing today?
 ```
+
+By adhering to this format, the script remains organized, making it simpler for readers to navigate through conversations and understand the speaker at all times.

vns-docs/docs/tutorials/tags/bgi.md

@@ -1,5 +1,16 @@
 # Background image:
 
-`[bgi]string`, ex: `[bgi]bg1.png`
+Specifies the background image for the current and following dialogues.
 
-Specifies the background image for the current and following dialogues.
+### Syntax
+
+```
+[bgi]string
+```
+
+### Example
+
+```vns
+[bgi]park.png
+```
+This sets the background image to "park.png" located in the specified directory.

vns-docs/docs/tutorials/tags/bgm.md

@@ -1,5 +1,17 @@
 # Background music:
 
-`[bgm]string`, ex: `[bgm]bgm1.ogg`
-
 Specifies the background music for the current and following dialogues.
+
+### Syntax
+
+```
+[bgm]string
+```
+
+### Example
+
+```vns
+[bgm]theme.mp3
+```
+
+This sets the background music to "theme.mp3" located in the specified directory.

vns-docs/docs/tutorials/tags/block.md

@@ -2,4 +2,19 @@
 
 `[block]`
 
-The player can't go back to the previous conversation.
+Prevents the player from returning to the previous conversation.
+
+### Syntax
+
+```
+Me:
+- I will only say this once.
+- I like you!
+...
+
+[block]
+
+...
+Me:
+- And I will not say it one more time.
+```

vns-docs/docs/tutorials/tags/display.md

@@ -1,5 +1,19 @@
 # Display character(s):
 
-`[display]*strings`, ex: `[display]character1.png character2.png`
+This command is used to display character images for current or upcoming dialogues. Unlike the `[show]` tag, which adds new character images while retaining existing ones, the `[display]` tag first clears any previously shown images before displaying the specified character image(s). This ensures that only the designated character images appear on the screen.
 
-Displays character images corresponding to the ongoing and forthcoming dialogues. Unlike the [show] tag, which introduces new character images in addition to existing character images, this tag will first clear any existing character images before introducing the designated character image(s).
+### Syntax
+
+```
+[display]image1 image2 ...
+```
+
+*image1*, *image2*, etc., represent the filenames of the character images to be displayed.
+
+### Example
+
+```vns
+[display]character1.png character2.png
+```
+
+In this example, any previously displayed images will be cleared, and the images `character1.png` and `character2.png` will be shown.

vns-docs/docs/tutorials/tags/end.md

@@ -1,5 +1,14 @@
-# Current dialogue branch ends here:
+# End of Current Dialogue Branch
 
-`[end]`
+The `[end]` tag is used to mark the conclusion of the current dialogue branch. Once this tag is encountered, the program will recognize that the dialogue or narrative path has finished.
 
-Marks the end of current dialogue branch.
+### Syntax
+
+```
+Me:
+- I guess this is the end of the story.
+
+[end]
+```
+
+By using `[end]`, you signal that no further dialogue or choices will follow in this particular branch, and the story can transition or conclude as necessary.

vns-docs/docs/tutorials/tags/hide.md

@@ -1,5 +1,33 @@
-# Hide character(s):
+# Hide Character(s)
 
-`[hide]*strings`, ex: `[hide]character1.png character2.png` or `[hide]*` for hiding all.
+The `[hide]` tag is used to remove character images from the screen, either selectively or all at once, for the current and subsequent dialogues.
 
-Hides the character(s) for the current and following dialogues.
+### Syntax
+
+```
+[hide]image1 image2 ...
+```
+
+*image1*, *image2*, etc., represent the filenames of the character images to be hidden.
+
+To hide all characters at once, use:
+
+```
+[hide]*
+```
+
+### Example
+
+```vns
+[hide]character1.png character2.png
+```
+
+In this example, the images `character1.png` and `character2.png` will be hidden, while other character images (if any) remain visible.
+
+Alternatively, using:
+
+```vns
+[hide]*
+```
+
+will hide all currently displayed character images.

vns-docs/docs/tutorials/tags/id.md

@@ -1,5 +1,19 @@
-# ID:
+# Script ID
 
-`[id]string`, ex: `[id]1`
+The `[id]` tag assigns a unique identifier to the current dialogue script file. Each script file must have a distinct ID to ensure proper identification and organization within the system.
 
-Specifies a (unique) ID for the current dialogue script file. Every script file must have an ID.
+### Syntax
+
+```
+[id]unique_identifier
+```
+
+*unique_identifier* is a string representing the unique ID for the script.
+
+### Example
+
+```vns
+[id]1
+```
+
+In this example, the script is assigned the ID `1`, ensuring it can be referenced and managed uniquely.

vns-docs/docs/tutorials/tags/label.md

@@ -1,5 +1,19 @@
-# Label:
+# Label
 
-`[label]string`, ex: `[label]jump_point1`
+The `[label]` tag is used to create a reference point within the dialogue script. This label can be targeted by branching commands, allowing the flow of the conversation to jump to this specific point.
 
-Creates a label for the branch command. The value will be used as the key for the subsequent conversation.
+### Syntax
+
+```
+[label]label_name
+```
+
+*label_name* represents the unique identifier for this point in the dialogue.
+
+### Example
+
+```vns
+[label]jump_point1
+```
+
+In this example, `jump_point1` serves as a reference label that can be used later to direct the conversation flow to this specific part of the script.

vns-docs/docs/tutorials/tags/language.md

@@ -1,5 +1,19 @@
-# Language:
+# Language
 
-`[language]string`, ex: `[language]English`
+The `[language]` tag defines the language used in the current dialogue script. Each script file must specify its language to ensure proper localization and presentation.
 
-Specifies the language of the current dialogue. Every script file must specifies a language.
+### Syntax
+
+```
+[language]language_name
+```
+
+*language_name* represents the name of the language being used in the script (e.g., English, Japanese, etc.).
+
+### Example
+
+```vns
+[language]English
+```
+
+In this example, the language for the script is set to English.