doc: misc improvements - WIP

docs/src/SUMMARY.md

@@ -1,11 +1,11 @@
 # Summary
 
 - [Introduction](./introduction.md)
-    - [Installation](./installation.md)
-    - [Terminology](./terminology.md)
-    - [Syntax](./syntax.md)
-    - [Settings](./settings.md)
-    - [FAQ](./faq.md)
+  - [Installation](./installation.md)
+  - [Usage](./usage.md)
+- [Terminology](./terminology.md)
+- [Syntax](./syntax.md)
+- [Settings](./settings.md)    
 - [Internal Functions](./internal-functions/overview.md)
     - [tp.config](./internal-functions/internal-modules/config-module.md)
     - [tp.date](./internal-functions/internal-modules/date-module.md)
@@ -20,6 +20,9 @@
     - [User Scripts](./user-functions/script-user-functions.md)
     - [System Commands](./user-functions/system-user-functions.md)
 - [Commands](./commands/overview.md)
-    - [Dynamic Commands](./commands/dynamic-command.md)
+    - [Interpolation Commands](./commands/interpolation-command.md)
     - [Execution Commands](./commands/execution-command.md)
-    - [Whitespace Control](./commands/whitespace-control.md)
+    - [Command Utilities](./commands/utilities.md)
+      - [Dynamic](./commands/dynamic-command.md)
+      - [Whitespace Control](./commands/whitespace-control.md)
+- [FAQ](./faq.md)

docs/src/commands/dynamic-command.md

@@ -1,4 +1,4 @@
-# Dynamic Commands
+# Dynamic Command Utility
 
 With this command utility, you can declare a command as "dynamic", which means that this command will be resolved when entering preview mode.
 
@@ -18,4 +18,4 @@ One "downside" of the preview mode is that it puts the rendered note in cache, t
 
 This means that your dynamic command will be rendered only once, when you open the note, but won't be refreshed after.
 
-If you want to refresh it, you must close the note to clear the cache and open it again.
+If you want to refresh it, you must close the note to clear the cache and open it again.

docs/src/introduction.md

@@ -1,8 +1,10 @@
 # Introduction
 
-[Templater](https://github.com/SilentVoid13/Templater) is a template language that lets you insert **variables** and **functions** results into your notes. It will also let you execute JavaScript code manipulating those variables and functions.
+[Templater](https://github.com/SilentVoid13/Templater) is a template plugin for Obsidian that lets you define and use templates to quickly create (parts of) notes. 
 
-With [Templater](https://github.com/SilentVoid13/Templater), you will be able to create powerful templates to automate manual tasks.
+Templater's variables and functions allow you to insert and flexibly format all kinds of dynamic content into your notes. You can even write your own scripts to connect to external APIs on the web or your local computer.
+
+Templater is one of the [most popular](https://obsidian.md/plugins?search=templater) Obsidian plugins because it's extremely useful if you often create (parts of) notes that are similar.
 
 ## Quick Example
 

docs/src/terminology.md

@@ -1,15 +1,48 @@
 # Terminology
 
-To understand how [Templater](https://github.com/SilentVoid13/Templater) works, let's define a few terms:
+To understand how Templater works, let's define a few terms:
 
-- A **template** is a file that contains **[commands](./commands/overview.md)**.
-- A text snippet that starts with an opening tag `<%`, ends with a closing tag `%>` is what we will call a **[command](./commands/overview.md)**.
-- A **function** is an object that we can invoke inside a **command** and that returns a value (the replacement string)
+## Template
 
-There are two types of functions you can use:
+A template is (just) an Obsidian note that contains 0 or more Templater [commands](#command). Templates should be located in a separate directory to separate them from regular Obsidian notes. The Templater plugin should be configured correctly so it knows where to find these templates.
 
-- [Internal functions](./internal-functions/overview.md). They are **predefined** functions that are built within the plugin. As an example, `tp.date.now` is an internal function that will return the current date.
-- [User functions](./user-functions/overview.md). Users can define their own functions. They are either [system command](./user-functions/system-user-functions.md) or [user scripts](./user-functions/script-user-functions.md).
+A template can have 0 commands, but most will have at least 1 command.
+
+## Command
+
+A **[command](./commands/overview.md)** is a bit of JavaScript code surrounded by an opening tag `<%` and a closing tag `%>`.
+
+```JavaScript
+<% tp.file.title %>
+<%* console.log('test') %>
+```
+
+The `<%` opening tag defines an ["interpolation command"](./commands/interpolation-command.md). 
+
+The `<%*` opening tag defines an ["execution command"](./commands/execution-command.md). 
+
+### Command utilities
+
+[Command utilities](./commands/utilities.md) allow you to change some of the behaviour of commands.
+
+## Code: Variables, functions, modules
+
+The code between the tags of a command is JavaScript code. This code will be run by Templater. If the command is an [interpolation command](./commands/interpolation-command.md) it will be replaced by the result of the JavaScript code. If the command is an [execution command](./commands/execution-command.md) the command will only run. If an execution command needs to change the content of the note that behaviour needs to be defined in the command.
+
+
+
+
+
+
+
+
+A **function** is something we can "invoke" or "call" inside a **command**. Templater has built-in functions and you can define your own.
+
+
+There are different types of functions you can use:
+
+- [Internal functions](./internal-functions/overview.md) are predefined functions that are built-in to Templater. For example, `tp.date.now` is an internal function that will return the current date.
+- [User functions](./user-functions/overview.md) are functions defined by a user. User functions can be [script user functions](./user-functions/script-user-functions.md) or [system command user functions](./user-functions/system-user-functions.md).
 
 ### Example
 
@@ -20,4 +53,4 @@ Yesterday: <% tp.date.yesterday("YYYY-MM-DD") %>
 Tomorrow: <% tp.date.tomorrow("YYYY-MM-DD") %>
 ```
 
-We'll see in the next part the syntax required to write some commands.
+

docs/src/usage.md

@@ -0,0 +1,69 @@
+# Usage
+
+Templater can be used in different ways. You can follow along with the examples on this page.
+
+## Creating a template
+
+To use Templater you create and use special Obsidian notes that contain 1 or more [commands](./terminology.md). These template notes should live in a separate directory, `Templates/` for example.
+
+#### Try it
+
+In your vault make a directory called `Templates/` and create a note called `Example` in it.
+
+Now configure Templater so the "Template folder location" setting points to this new directory.
+
+Copy-paste the following content into the template note: `Templates/Example`:
+```javascript
+<% tp.date.now("YYYY-MM-DD") %>
+```
+
+We're going to use this template in the next sections.
+
+## Using a template
+
+You can use a template in multiple ways.
+
+### When creating a new note
+
+You can create a new note using a template. You can do this using the **Templater: Create note from template** command. This command will show you the list of templates you've defined and lets you choose one. When you choose a template the following things will happen:
+
+- a new note will be created
+- the new note is called "Untitled" ([customizeable](./internal-functions/internal-modules/file-module.md#tpfilerenamenew_title-string))
+- the chosen template will be inserted into the new note
+- Templater will run (interpret/execute) all the commands in this new note
+- each command in the new note will either be replaced by something or disappear
+- the resulting note will not have any commands in it
+- the new note will be opened
+- the title of the note will be selected (so you can change it immediately)
+
+#### Try it
+
+Now try it yourself: trigger the [Obsidian Command Palette](https://help.obsidian.md/Plugins/Command+palette) and type "Create note from template" to find the **Templater: Create note from template** command. Select that command and then select the `Example` template.
+
+You should get a new note in your vault called `Untitled`. The first line of the note should be the current date in `YYYY-MM-DD` format.
+
+This way of using templates is practical for creating templates for whole notes. You can imagine having these kinds of templates for recipes, movie reviews and book summaries.
+
+### Inserting a template into the current note
+
+(Obsidian has a built-in command called **Templates: Insert Template** which is not part of Templater. You cannot use this to insert Templater templates.)
+
+Instead of creating a new note you can also *insert* a template into the note that you're currently editing.
+
+You can do this using the command **Templater: Open Insert Template Model** from the command palette. You can also trigger this command by clicking the Templater icon `<%` in the sidebar ribbon. This command will show you the list of templates you've defined and lets you choose one. When you choose a template the following things will happen:
+
+- the contents of the chosen template will be inserted into the currently active note, at the location of your cursor
+- each command in the current note will either be replaced by something or disappear
+- the resulting note will not have any commands in it
+
+#### Try it
+
+Create a new note called "Holiday". Write "before" on the first line. Then create an empty line. Write "after" on the last (3rd) line. Now put your cursor on the empty line and trigger the **Templater: Open Insert Template Model** command using the Command Palette or the Templater icon in the sidebar.
+
+The empty line in your note should be replaced by the current date in `YYYY-MM-DD` format.
+
+This way of using templates is useful when you write notes that often have similar parts. You can imagine having templates for [tables](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax#Tables), [diagrams](https://help.obsidian.md/Editing+and+formatting/Advanced+formatting+syntax#Diagram) or [embedding webpages](https://help.obsidian.md/Editing+and+formatting/Embedding+web+pages). After inserting the template you can then edit the inserted content as you need.
+
+---
+
+These are the basics of how to use Templater. The [next section](./terminology.md) will formally introduce the terminology used.