Yeah

Author: mpourmpoulis

README.md

@@ -18,7 +18,12 @@ In particular, navigation through the code sometimes felt a little bit too mecha
 need to be taken to get there. What if you could instead simply describe (syntactically)  what you want to select? 
 
 PythonVoiceCodingPlugin tries to enable you to do just that!
-As implementing such functionality requires the analysis of source code,a task far more suitable to editors.
+To provide this functionality, it ships with bundles the implement a grammar, hopefully expressive enough for describing regions of interest, while running on the voice coding macro system side  and 
+cooperate with the core plugin, running on the editor side, arguably the more suitable of the two environments
+for analyzing source code and decoding the meaning of queries within the given context. 
+
+
+
 
 I want to be honest. This is not exactly the best code ever written. It is far from it:) And it is far from the full functionality i would want it to offer. Nonetheless, I still think that PythonVoiceCodingPlugin is a tool that :
 
@@ -42,6 +47,7 @@ I want to be honest. This is not exactly the best code ever written. It is far f
 * is partly customizable. If you find yourself using certain commands with some given parameters often and want a shorthand smaller command, you can always follow my commented banana example:)
 
 
+As I said, far from perfect but nonetheless an out-of-the-box solution which I hope to be helpful for beginners to get up to speed and a step towards the right direction. I hope you enjoy using it as much as I have enjoyed coding it:)
 
 ## Release and Version 
 
@@ -52,9 +58,9 @@ Currently in preparation of the initial 0.0.0 release , probably between 5-10/11
 
 ## Limitations
 
-There are of course certain limitations: 
+There are of course certain limitations which I would like to make clear from the start: 
 
-* Currently I do not fully support python > 3.3 (Still, you can work on code that contains some new features such as async and await keywords, f-strings). That's because Sublime uses python 3.3.6 and I rely on the standard library´s ast module to parse the code. An alternative could have been astroid but it itself uses typed_ast, which contains C code, something which I wanted to avoid. The plugin will most likely eventually change to a client server architecture and simply use an up to date ast module from python 3.7 or the new 3.8.
+* Currently I do not fully support python > 3.3 (Still, you can work on code that contains some new features such as async and await keywords, f-strings). That's because Sublime uses python 3.3.6 and I rely on the standard library´s ast module to parse the code. An alternative could have been astroid but it itself uses typed_ast, which contains C code, something which I wanted to avoid. The plugin will most likely eventually change to a client server architecture and simply use an up to date ast module from python 3.7 or the new 3.8. please note that this restriction only concerns the users of new syntactical features. There is no problem , for instance, if you use a new standard library function.
 
 ![](gif/l1.gif)
 
@@ -179,7 +185,7 @@ For specific versions be sure to check the requirements.txt
 
 ## Acknowledgements
 
-### Resources
+### Useful Learning Resources
 
 The following resources proved very helpfull for the success of the project. Many thanks to all the authors!
 
@@ -191,4 +197,21 @@ The following resources proved very helpfull for the success of the project. Man
 
 * [sublime 3 unofficial documentation]( http://docs.sublimetext.info/en/latest/index.html  )
 
-* the python [grammar]() specification
+* the python [grammar]() specification
+
+* of course [the sublime forum]()
+
+
+### Development tools
+
+Many thanks to all of the developers that have put their time and effort behind projects such as
+
+* Natspeak
+
+* Dragonfly
+
+* Caster
+
+
+needless to say, while coding PythonVoiceCodingPlugin I used PythonVoiceCodingPlugin :)
+

doc/README.md

@@ -34,7 +34,7 @@ Choice("adjective",{
 
 } )
 ```
-![](./gif/arg3.gif)
+![](./gif/big3.gif)
 
 and 
 
@@ -51,9 +51,11 @@ Choice("vertical_direction",{
 ```
 
 usually followed by an integer. Beware the difference between up and above! As a rule of thumb, above only takes "interesting" lines into consideration:)
-![](./gif/big4.gif)
+
+![](./gif/arg5.gif)
 
 * in certain cases you can combine these two approaches:)
+
 ![](./gif/big5.gif)
 
 Details vary but that is the. spirit! Ok , what else?
@@ -128,10 +130,12 @@ Choice("index_collectable",{
 	"(variable|variables)":"variable",
 	"( parameter | parameters)":"parameter",
 	"(module|modules)":"module",
-	"(import|imported) (value|item|object|element)":"import value",
+	"imported (value|object)":"import value",
 	"function ( name |names)":"function name",
 } 
 ```
+please note that these items are collected from the whole source code.
+
 ### Insert Item
 
 These "items" can then be inserted in the current cursor position by means of the 
@@ -143,3 +147,18 @@ command. Item_index specifies which item from the collection you want
 
 ![](./gif/d5.gif)
 
+### index collectible
+
+certain collectible items such as variables and parameters can be index collected by means of a query like
+
+```python
+"[smart] variable <collect_index>"
+```
+In such a case, items will only be collected from the current function  and in item will be inserted
+based on the index specified and their order of appearance
+
+![](./gif/d6.gif)
+
+
+
+

doc/SelectArgument.md

@@ -1,5 +1,7 @@
 # Argument Selection Command
 
+![](./gif/arg0.gif)
+
 This is a SelectionQuery that enables you to select an argument from a function call.
 It supports the following syntaxes: 
 
@@ -115,8 +117,17 @@ now let's see something different:
 
 in this example we use the command:
 
+```python
+"[smart] [<adjective>] <level> [<level_index>]  argument <argument_index>"
+```
 For the time being, the only available option for the level parameter is
 
+```python
+Choice("level",{
+		"inside":"inside",
+	}
+),
+```
 by means of the keyword inside , we can specify that we want an argument from a function call that is nested inside another function call! The level_index parameter
 
 Specifies the index of the argument of the outer function call our desired ROI lies in. In order to specify which outer function goal we are referring to we can optionally use an adjective :
@@ -132,6 +143,9 @@ This, looks very similar to the previous one. However, instead of using the adje
 
 As you can see, the syntax looks like:
 
+```python
+"[smart] <level> [<level_index>] <adjective> argument <argument_index>"
+```
 
 
 

doc/SelectBigROI.md

@@ -2,6 +2,9 @@
 
 These commands are responsible for selecting "big" regions of interest. By "big" we refer to things like "if condition" or "assignment right" in contrast to say the first entry of a dictionary.
 
+![](./gif/big0.gif)
+
+
 In particular, the currently offered "big roi´s" are :
 
 ```python
@@ -83,7 +86,7 @@ you should probably be already familiar with adjectives, so here is an example o
 
 ![](./gif/big3.gif)
 
-as with case one, only the current function searched.
+as with case one, only the current function searched. ( pay attention to my last example where alternatives are only offered from the nested function definition!)