Update documentation (#638)

Author: mandel

docs/README.md

@@ -440,20 +440,20 @@ See [PDL Language Tutorial](https://ibm.github.io/prompt-declaration-language/tu
 
 ## Debugging Tools
 
-## Live Explorer
+### Live Explorer
 
 PDL has a Live Explorer to help in program understanding given an execution trace.
 To produce an execution trace consumable by the Live Explorer, you can run the interpreter with the `--trace` argument:
 
 ```
-pdl --trace <file.json> <my-example>
+pdl <my-example> --trace <my-example_trace.json>
 ```
 
 This produces an additional file named `my-example_trace.json` that can be uploaded to the [Live Explorer](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. The Live Explorer shows a timeline of execution and a tile for every block. By clicking on a tile, the user can discover more information such as input/context/output for LLM calls. It also provides the ability to re-run a block for eventual live programming.
 
 This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Explorer, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.
 
-## Trace Telemetry
+### Trace Telemetry
 
 PDL includes experimental support for gathering trace telemetry.  This can
 be used for debugging or performance analysis, and to see the shape of prompts sent by LiteLLM to models.

docs/tutorial.md

@@ -306,25 +306,31 @@ Bob lives at the following address:
 ##  Parsing the output of a block
 
 As we saw in the previous section, it is possible to use the `parser: json` setting to parse the result of a block as a JSON.
-Other possible values for `parser` are `yaml`, `jsonl`, or a regular expression.
+Other possible values for `parser` are `yaml`, `jsonl`, or `regex`.
 
-The following code shows an example of a regular expression parser:
+The following example extracts using a regular expression parser the code between triple backtick generated by a model:
 ```yaml
 --8<-- "./examples/tutorial/parser_regex.pdl"
 ```
 
-See [here](https://docs.python.org/3/library/re.html) for more information on how to write regular expressions.
-We support the following operations (indicated with the `mode` field):
+We support the following operations with the`regex` parser (indicated with the `mode` field):
+
+- `fullmatch` (default)
 
-- search
+- `search`
 
-- match
-  
-- fullmatch
+- `match`
+    
+- `split`
 
-- split
-  
-- findall
+- `findall`
+
+Here is an example that is using `findall`:
+```yaml
+--8<-- "./examples/tutorial/parser_findall.pdl"
+```
+
+See [here](https://docs.python.org/3/library/re.html) for more information on how to write regular expressions.
 
 ##  Calling code
 
@@ -392,7 +398,7 @@ PDL allows programs to be defined over multiple files. The `import` block allows
 following [example](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/import.pdl):
 
 ```yaml
---8<-- "./examples/tutorial/include.pdl"
+--8<-- "./examples/tutorial/import.pdl"
 ```
 
 which imports the following [file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/import_lib.pdl):

examples/tutorial/parser_regex.pdl

@@ -1,14 +1,10 @@
-description: Hello world with parser using regex
-text:
-- model: ollama/granite-code:8b
-  parameters:
-    temperature: 0
-  input: "Hello,"
-  parameters:
-    # Tell the LLM to stop after generating an exclamation point.
-    stop: ['!']
-  spec: {"name": str}
-  parser:
-    spec:
-      name: str
-    regex: '\s*(?P<name>.*)\s*'
+description: Parse a block output using a regex
+defs:
+  output:
+    model: ollama/granite-code:8b
+    input: Write a Python function that perform the addition of two numbers.
+    parser:
+      spec:
+        code: str
+      regex: (.|\n)*```python\n(?P<code>(.|\n)*)```(.|\n)*
+text: ${ output.code }

tests/results/examples/tutorial/parser_regex.0.result

@@ -1 +1,2 @@
-{"name": "Hello"}
+def add(a, b):
+    return a + b