From f24b25fc4ed8f304397be7d43f62428be1e260ff Mon Sep 17 00:00:00 2001
From: Vladimir Kalnitsky <klntsky@gmail.com>
Date: Thu, 14 Nov 2024 16:08:26 +0400
Subject: [PATCH] Add syntax reference

---
 docs/index.md  |  6 ++++--
 docs/syntax.md | 51 +++++++++++++++++++++++++++++++++++++-------------
 mkdocs.yml     |  1 +
 3 files changed, 43 insertions(+), 15 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 482c330..89c475d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -52,13 +52,15 @@ Quick example:
 
 A module system and a package system enable parameterized prompt reuse and publishing.
 
+`hello.metaprompt`:
+
 ```metaprompt
-# hello.metaprompt:
 Hello, [:what]!
 ```
 
+`main.metaprompt`:
+
 ```metaprompt
-# main.metaprompt:
 [:use ./hello :what=world]
 ```
 
diff --git a/docs/syntax.md b/docs/syntax.md
index 9627419..36a17d8 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -1,6 +1,6 @@
 # Text
 
-A prompt is usually a valid metaprompt:
+A textual prompt is usually a valid metaprompt:
 
 ```metaprompt
 Hi, LLM! How are you feeling today?
@@ -16,8 +16,8 @@ Here's a variable: [:variable_name].
 If a variable is used before first assignment, it is treated as a required
 prompt parameter automatically.
 
-[:variable_name=it can be reassigned to any value, however.
-Including a value containing its old value: [:variable_name] or referencing [:other] variables]
+[:variable_name=it can be reassigned to any value, however]
+[:variable_name=Including a value containing its old value: [:variable_name]]
 ```
 
 # Comments
@@ -40,47 +40,72 @@ Including a value containing its old value: [:variable_name] or referencing [:ot
  :then this...
  :else that...
 ]
+```
 
-[# ^ This expression will be expanded at runtime.
+`:if` expressions will be expanded at runtime.
 
 First, the following text will be fed to an LLM:
 
+```
 Please determine if the following statement is true.
 Do not write any other output, answer just "true" or "false".
 The statement: the sky is sometimes blue
+```
 
 The answer will determine the execution branch.
 If the answer is not literally "true" or "false",
 an exception will be thrown after a few retries
-]
-```
 
 # Meta-prompting
 
 ```metaprompt
 LLM says: [$ Hi, LLM! How are you today?]
-
-[# ^^^ this prompt will be executed and its output will be inserted
-at its position during expansion ]
 ```
 
-A more inspiring example:
+The `[$` prompt will be executed and its output will be inserted
+at its position during expansion. This enables powerful techniques
+of prompt rewriting:
 
 ```metaprompt
-[$ Improve this LLM prompt: [:prompt]]
+[$ [$ Improve this LLM prompt: [:prompt]]]
 ```
 
+Notice the double nesting of `[$` - the improved prompt will be fed back into an LLM.
+
 # Modules
 
+Every `.metaprompt` file is a function.
+
+Unbound variables used in a file are its parameters, that must be provided.
+
+```metaprompt
+Hello, [:what]! [# `what` is a parameter ]
+[:who=you] [# `who` is NOT a parameter, because it is assigned before first use]
+How are [:who] feeling today?
+```
+
+## File imports
+
+This expression will include `./relative-import.metaprompt` file (relative to the directory of the file, NOT to the current working dir).
+
 ```metaprompt
 [:use ./relative-import]
-[:use package-name/directory/module]
+```
 
-With parameters:
+## Package imports
 
+**NOT IMPLEMENTED**
+
+## Passing parameters
+
+```
 [:use ./relative-import
  :someParameter= arbitrary value, potentially using
    any other MetaPrompt constructs
  :otherParameter= another value
 ]
 ```
+
+## Special variables
+
+- `MODEL` - used to determine active LLM id.
diff --git a/mkdocs.yml b/mkdocs.yml
index 43715db..8cbdbaa 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -21,6 +21,7 @@ markdown_extensions:
 
 nav:
   - Home: index.md
+  - Syntax: syntax.md
   # - Getting Started:
   #     - Introduction: getting_started/introduction.md
   #     - Installation: getting_started/installation.md