From 834b83c9616e7a43accc16d3ca178bc2b616da24 Mon Sep 17 00:00:00 2001
From: John Mettraux <jmettraux@gmail.com>
Date: Tue, 15 Aug 2023 01:26:02 +0900
Subject: [PATCH] Enhance cursor start:/initial: doc

---
 lib/flor/pcore/cursor.rb | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/lib/flor/pcore/cursor.rb b/lib/flor/pcore/cursor.rb
index b02a75a6..4ee32cd2 100644
--- a/lib/flor/pcore/cursor.rb
+++ b/lib/flor/pcore/cursor.rb
@@ -62,6 +62,10 @@ class Flor::Pro::Cursor < Flor::Procedure
   #
   # ## cursor and start: / initial: attribute
   #
+  # Sometimes, it is necessary to enter a cursor not at its first child, but
+  # its second or third. Once such a cursor is entered and a `continue` is
+  # met it will "rewind" to the first child (not the "start" child).
+  #
   # ```
   # task 'create mandate'
   # cursor start: 'approve mandate'
@@ -71,6 +75,15 @@ class Flor::Pro::Cursor < Flor::Procedure
   # task 'activate mandate'
   # ```
   #
+  # The string passed to start:/initial: is looked up (down) in the cursor
+  # in the order: (example `cursor start: 'bravo'`)
+  #
+  # * tag (for example `push l 'b' tag: 'bravo'`)
+  # * string argument (for example `task 'toto' context: 'bravo'`)
+  # * string target (for example `task 'bravo'`)
+  # * name target (for example `bravo _`)
+  # * att target (for example `task 'toto' bravo: 'ok'`)
+  #
   # ## see also
   #
   # Break, continue, loop.