Merge pull request #43 from tkuebler/master

Documentation editing and addition of 'Using Chatscript on a Mac' doc.

Author: chatscriptnlp

WIKI/ChatScript-Json.md

@@ -525,3 +525,30 @@ Representing JSON in CS facts is more than just a bunch of subject-verb-object f
 The facts have typing bits on them that describe the structure and arrays have index values that must
 remain consistent. Therefore you should not create and alter JSON fact structures using ordinary CS
 fact routines like `^createfact` and `^delete`. Instead use the JSON routines provided.
+
+
+## Practical Examples
+
+The write jsonwrite and json tree print out different views of the same data..
+
+    u: (-testcase1) $$jsonObject = ^jsoncreate(object)
+        ˆjsonobjectinsert( $$jsonObject name “some name” )
+        ˆjsonobjectinsert( $$jsonObject phone “some number” )
+        ˆjsonwrite ( $$jsonObject ) \n
+        ^jsontree ( $$jsonObject )\n
+
+Note in this next example how to escpe a json string with ^''.  This makes creating json objects from static data very intuitive and clear.
+    
+    u: (-testcase2) $$tmp = ^jsonparse( ^'{name: "Todd Kuebler", phone: "555.1212"}' )
+        ^jsonwrite( $$tmp ) \n
+        ^jsontree( $$tmp ) \n
+        name: $$tmp.name, phone: $$tmp.phone
+ 
+ This example shows the . notation access of data inside an json object in chatscript.  This is probably the most intuitive way of interacting with the data. 
+ 
+    u: (-testcase3) $$tmp = ^jsoncreate(object)
+        $$tmp.name = "Todd Kuebler"
+        $$tmp.phone = "555-1212"
+        ^jsonwrite( $$tmp ) \n
+        ^jsontree( $$tmp ) \n
+        name: $$tmp.name, phone: $$tmp.phone 

WIKI/Installing-and-Updating-ChatScript.md

@@ -24,6 +24,12 @@ make file in SRC. And you have to install curl and optionally postgres. If you d
 or want them you can in your build file do defines of: DISCARDDATABASE and
 DISCARDJSON.
 
+Alternatively you can use the binary in `BINARIES/MacChatScript`, but it is at least one version behind unless you are grabbing chatscript directly from github.   
+
+There is also an Xcode project in the `NON-WINDOWS NON-C/Xcode` directory  that you can launch and build your own binary with.  This is probably the prefered method for advanced users.
+
+See the `Chatscript on a Mac` in `Overviews and Tutorials` directory of the docs for a more indepth discusion of compiling and using ChatScript on a mac.
+
 
 ## Installing Linux
 
@@ -57,18 +63,39 @@ whatever. That's not the ideal way however.
 
 The ideal way to do ChatScript is to have a folder that somehow contains your bot data
 AND contains CS as a subfolder. Like this:
-```
-MYFOLDER
-  BOTDATA
-  filesmybot.txt
-  ChatScript
-```
+
+    MYFOLDER/
+        startserver.sh
+        BOTDATA/
+            Smooth/
+                smoothcontrol.top
+            Fuzzy/
+                fuzzycontrol.top
+                flea.top
+            AllBots/
+                shopping.top
+        filesmybot.txt
+        ChatScript/
 
 In your `filesmybot.txt` you name the path to your `BOTDATA` files and folders
 appropriately. Then, to update ChatScript, you remove the ChatScript folder and drop in
 the new one. ChatScript automatically looks above itself to find your `filesxxx.txt` file if it
 can't find it within.
 
+Example filesmybot.txt for the directory structure above:
+
+    # multibot example
+    ../BOTDATA/Smooth/
+    ../BOTDATA/Fuzzy/
+    ../BOTDATA/AllBots/
+    # load in standard chatscript quibbles
+    RAWDATA/QUIBBLE/
+
+You then start the server in the 'MYFOLDER' directory with a script like this on Mac or Linux, windows is similar:
+
+    #!/bin/sh
+    cd ChatScript && BINARIES/MacChatScript livedata=../LIVEDATA english=LIVEDATA/ENGLISH system=LIVEDATA/SYSTEM local
+
 Similarly, if you have your own `LIVEDATA` files, you can give a reference to your copy
 of files in `MYDATA/LIVEDATA` so you don't have to worry that CS copies may have
 changed. You want to allow CS to use its own copy of `LIVEDATA/SYSTEM` and

WIKI/OVERVIEWS-AND-TUTORIALS/ChatScript-on-a-Mac.md

@@ -0,0 +1,76 @@
+#Chatscript on a Mac
+
+> © Bruce Wilcox, [email protected] brilligunderstanding.com
+
+> Revision 1 - 7/16/2017 - [email protected]
+
+
+## Installing
+
+Life is not as easy for Mac users since Bruce doesn't have a mac - therefore a build of the mac binary is not part of every release.
+
+However ChatScript builds and runs just fine on any version of OSX ( now called MacOs ) and there are many of us using ChatScript on macs with no problem.  The unix underpinnings of MacOS make it a great development environment and ChatScript generally works the same way as under Linux.
+
+### Method 1 - build from command line
+
+After unzipping into a folder
+(typically called ChatScript), you need to compile the src in SRC. The alternate
+technology is to beg in the ChatScript forum on ChatBots.org for a mac user to send you
+their executable copy of the latest build.
+To compile means using XCODE and making an appropriate make file for it based on the
+make file in SRC. And you have to install curl and optionally postgres. If you don't have
+or want them you can in your build file do defines of: DISCARDDATABASE and
+DISCARDJSON.
+
+The example/default command line compile is located in NON-WINDOWS NON-C/MAC/MacCompile.sh.  Read the readme in that directory for more instructions.
+
+### Method 2 - use outdated binary in the BINARIES folder
+Alternatively you can use the binary in BINARIES/MacChatScript, but it is at least one version behind unless you are grabbing chatscript directly from github.   
+ 
+### Method 3 - use the included Xcode project to build
+There is also an Xcode project in the 'NON-WINDOWS NON-C/Xcode' directory  that you can launch and build your own binary with.  This is probably the prefered method for advanced users.
+
+## Prerequisites for compiling via Xcode
+
+####(included) curl library
+This is actually part of the default mac ecosystem and is already included in the Xcode project under 'TARGETS/MacChatScript/Build Phases/Link Binary with Libaries' ( navigation path in xcode editor )
+
+#### (optional) mongodb libraries
+These can be aquired via brew ( http://brew.sh ) The command is:
+
+    brew install mongodb mongo-c-driver
+#### (optional) postgress libraries
+These can also be aquired via brew.  The command is:
+
+    brew install postgresql
+
+## brew errata
+
+Follow the instructions at http://brew.sh to install and use brew.
+
+In general you can find the packages talked about in the is document with:
+
+    brew search mongo
+    brew search postgres
+
+You need the mongodb, mongo-c-driver and postgresql modules.
+
+***Important:*** The version of MacOS/OSX you are running determines what version of brew you run and what packages are available.  The packages for your particular macos version might be different than above.
+
+## Configuring Xcode for Mongo and/or Postgres
+
+More details coming Soon - essentially it involves installing the libraries then adding them to the list of libs that get included.  The setting is under build phases.
+
+## Running
+
+Running Chatscript is as simple as executing the binary you have from the instructions above.  Follow the same instructions as the main manual similar to Linux.  It boils down to:
+
+* Launch the `Terminal` application. It's found in /Applications/Utilities.  note: ⌘[space] launches spotlight, just type terminal in the window that pops up to find it and click on it to launch it.
+* In `Terminal` `cd` to the directory that contains chatscript. example: `cd src/Chatscript`
+* Run your binary using the linux instructions, ie
+
+    BINARIES/MacChatScript local
+
+## Getting Mac specific Help
+
+The best place for getting help is probably http://chatbots.org in the Chatscript forum. There are a number of friendly and helpful users there that answer mac specific question.   The github project is primarily for people contributing to chatscript code, documentation or reporting bugs.