Reworked documentation

.ok

@@ -1,10 +1,14 @@
 make help #prints targets
 # Build for a release
 export EMBED_PASHUA=1; make clean zip; unset EMBED_PASHUA; make zip
-# Settings
+# Settings (telling make to embed the Pashua app inside the script library)
 export EMBED_PASHUA=0
 export EMBED_PASHUA=1
 unset EMBED_PASHUA
 # Log file
 open ~/Library/Logs/Catsdeep/ASPashua.log # Open in console
 less +G ~/Library/Logs/Catsdeep/ASPashua.log  # Show last part with less
+# Control logging of the library
+defaults write com.catsdeep.ASPashua do_log -bool TRUE
+defaults read com.catsdeep.ASPashua
+defaults delete com.catsdeep.ASPashua

README.md

@@ -3,45 +3,32 @@ ASPashua
 
 This AppleScript Library tries to make it convenient to use [Pashua][] with AppleScript for enhanced dialogs.
 
+Getting started
+---------------
 
-Prerequisites
--------------
+Download the [latest release][latest-release], and install it in one of the _Script Libraries_ folders (more more instructions in the download). 
 
-**NOTICE**: you need to have [osagitfilter][] installed, before cloning this repository locally.
+In the download you will also find examples of how to use the script library.
 
-You need to have [Pashua][] installed on your system, since this library is a wrapper for that application.
+When you are done playing with those, you can see the [Pashua documentation][pashua-config] on what you can do with these forms.
 
+There are two distributions: in the biggest archive, the Pashua application is embedded within the script library, so you don't need to distribute it.
 
-Using
------
 
-To use this AppleScript Library, run `make install` from the command line. After this, you can open and run the included examples.
+Developing
+----------
 
-To create your own code, first you need to create a [form configuration][pashua-config], either as text-string or in a seperate file. Then you can display the form with `display pashua dialog` which returns a `record` with the entered values.
+Pre-requisites for working with this repository:
 
+* you need to have [osagitfilter][] installed, before cloning this repository.
+* you need to have [Pashua][] installed on your system, since this library is a wrapper for that application.
+* it's handy to have [ok-bash][] installed, so you can easy use the included `.ok`-file.
 
-Settings
---------
+Type `make` to see the help-screen. And type `ok` (or `cat .ok`) for some additional commands.
 
-To enable the logging, run the following on the command line:
-
-	defaults write com.catsdeep.ASPashua do_log -bool TRUE
-
-To instruct `make install` to embed `Pashua.app` into the built target, execute:
-
-	defaults write com.catsdeep.ASPashua embed -bool TRUE
-
-This will log the input and output of the _Pashua.app_-call to the log file `~/Library/Logs/Catsdeep/ASPashua.log`. The file can be easily inspected with macOS' _Console.app_.
-
-Inspect settings:
-
-	defaults read com.catsdeep.ASPashua
-
-Revert settings to default:
-
-	defaults delete com.catsdeep.ASPashua
-
 
 [osagitfilter]: https://github.com/doekman/osagitfilter
 [Pashua]: https://www.bluem.net/en/projects/pashua/
 [pashua-config]: https://www.bluem.net/pashua-docs-latest.html
+[ok-bash]: https://github.com/secretGeek/ok-bash
+[latest-release]: https://github.com/doekman/ASPashua/releases/latest

Release-notes.md

@@ -17,7 +17,7 @@ To do this:
 	- if it doesn't exist, you can created it with command+shift+N (or from the menu: Archive > New folder...)
 * As a final step, move `ASPashua.scptd` to this folder
 
-Now you can run the supplied samples.
+Now you can run the supplied examples.
 
 
 Version 0.3

examples/0.read-me.md

@@ -0,0 +1,14 @@
+ASPashua examples
+=================
+
+In this folder you will find examples how to use the ASPashua scripting library.
+
+`dpd` denotes an example with the handler `display pashua dialog`.
+
+1. Demonstrates the usage of `display pashua dialog` with the form definition in an external file
+2. Demonstrates the usage of `display pashua dialog` with the form definition as an inline string
+3. Same, but more elaborate
+4. Demontrates how to set a custom location for `Pashua.app`
+5. Shows how to do form validation and use dynamic values with a form definition in an external file
+6. Same, but with the form definition as an inline string
+7. Demonstrates how to dynamic populate the options of an popup control