doc

Author: easycoder

resources/codex/md/background.md

@@ -1,13 +1,13 @@
 # Background information #
 This is the ~ec~ **Codex**, a comprehensive free resource aimed at two groups of people:
 
-**Beginners** can learn to code using English-like scripts, with no prior experience needed, no need to set up hosting or to download any software. Codex includes a comprehensive tutorial with many working examples.
+**Beginners** can learn to code using English-like scripts, with no prior experience needed, no need to set up hosting or to download any software. **Codex** includes a comprehensive tutorial with many working examples.
 
-**Experts** can leverage the ~ec~ technology to achieve better productivity. When the Codex is installed on a server it allows direct access by the owner of the site to all the site code, which can be developed and maintained on any PC or even a smartphone.
+**Experts** can leverage the ~ec~ technology to achieve better productivity. When the **Codex** is installed on a server it allows direct access by the owner of the site to all the site code, which can be developed and maintained on any PC or even a smartphone.
 
-~ec~ was originally developed as a WordPress plugin, to offer non-programmers a relatively painless way to customize aspects of their pages and add simple interactivity based on DOM manipulation. As it developed it became clear that it was capable of far more than mere tweaks and was soon employed as the engine behind several complete websites. Further development resulted in the Codex, a complete IDE for website coding and a tutorial for programmers, both novice and expert.
+~ec~ was originally developed as a WordPress plugin, to offer non-programmers a relatively painless way to customize aspects of their pages and add simple interactivity based on DOM manipulation. As it developed it became clear that it was capable of far more than mere tweaks and was soon employed as the engine behind several complete websites. Further development resulted in the **Codex**, a complete IDE for website coding and a tutorial for programmers, both novice and expert.
 
-~ec~ is written in vanilla JavaScript with no dependencies except those called for by optional plugins. The total package size is about 250kB so it forms a fairly minor addition to a web page. However, it implements a complete scripting language able to perform all the major functions required by any website, and its plugin architecture allows extra functionality to be added by anyone in a seamless manner.
+~ec~ is written in vanilla JavaScript with no dependencies except those called for by optional plugins. The total package size - with all features used - is about 250kB so it forms a fairly minor addition to a web page. However, it implements a complete scripting language able to perform all the major functions required by any website, and its plugin architecture allows extra functionality to be added by anyone in a seamless manner.
 
 Sites built with ~ec~ need no JavaScript in their site logic, and because scripts are easy to understand it takes only a short time for a new programmer to become familiar with the language. This is great for productivity. For the same reason, maintenance of the site is made far easier than is otherwise commonly the case. Both these factors result in a drastic lowering of the overall TCO of the site.
 

resources/codex/md/install.md

@@ -1,7 +1,7 @@
 # Installing the EasyCoder Codex #
-The ~ec~ **Codex** is a complete integrated development system for coding websites. It can be run locally in your own computer or installed on your server; the only prerequisite is a recent copy of PHP.
+The ~ec~ **Codex** is a complete integrated development system for coding websites. It can be run locally in your own computer or installed on your server; the only prerequisite is a recent copy of PHP or Python 3, depending on which you want to use to run a local webserver.
 
-## Installation on a regular PC ##
+## Installation on a regular PC using PHP ##
 First download the Codex archive into an empty folder.
 
 Unzip the archive.
@@ -14,14 +14,17 @@ You should get confirmation that the PHP server started.
 
 Now go to your browser and type ~code:localhost:8000~ into the address bar. Hit ~code:Enter~. The Codex should start up.
 
+## Installation on a regular PC using Python 3 ##
+In this case, use the ~rest.py~ script to run a local webserver on any port you choose.
+
 ## Installation on a server ##
 Download the Codex archive into the root of your website.
 
 Unzip the archive.
 
 Type the URL of your server into your browser address bar and hit ~code:Enter~. The Codex should start up.
 
-If you need help, join our Slack channel by clicking here.
+If you need help, join our [Slack channel](https://join.slack.com/t/easycoder-software/shared_invite/enQtNTU5ODEwOTQ5NTU0LWQ1NWVkOTUxOGQ3NzJmNDI1ZGRlOTdmMjc1NDAxMGIwMTFjODg1ZDJhODEzMzUzODc2MDNlZWU4NmYyZWRlOWI).
 
 ## Script strategies ##
 There are two main strategies for using ~ec~ scripts, as follows:
@@ -62,6 +65,8 @@ becomes
 
 ~pre:attach Button to `ec-button`~
 
+where ~code:ec-button~ is the id of an element that already exists in your HTML.
+
 The most common use of this strategy is probably where an existing page is being retrofitted with ~ec~ script.
 
 ### Script from your server ###
@@ -85,7 +90,7 @@ Here's what the simplest form of this page looks like:
 <pre id="easycoder-script">
 
 variable Script
-rest get Script from &#96;/resources/scripts/myscript&#96;
+rest get Script from &#96;/resources/ecs/myscript.ecs&#96;
 run Script
 stop
 
@@ -95,8 +100,8 @@ stop
 
 </html>~
 
-Here the script (~code:myscript~) is located in the ~code:{site root}/resources/scripts~ directory. When you write scripts in Codex, put them in this directory, allowing you to directly maintain your site code from any computer (including a smartphone).
+Here the script (~code:myscript.ecs~) is located in the ~code:{site root}/resources/ecs~ directory. When you write scripts in Codex, put them in this directory, allowing you to directly maintain your site code from any computer (including a smartphone). The downloaded package includes a file called ~scripted.html~, which is a script editor with which you can edit files in the ~ecs~ directory. You will have to set up an encrypted password in ~code:properties.txt~; it's probably best to contact us for details of this unless you feel like diving into the ~code:rest.php~ REST server.
 
 If you can deal with the CORS issues you can use a complete URL to retrieve your script from a remote site, as in
 
-~pre:rest get Script from &#96;https://mysite.com/myscripts/home&#96;~
+~pre:rest get Script from &#96;https://mysite.com/myscripts/home.ecs&#96;~

resources/codex/md/step16.md

@@ -1,5 +1,4 @@
 # Using Google Maps #
-
 One of the strengths of ~ec~ is the way it can be extended using plugins. These are JavaScript code modules that provide extra language features to users of the system. EasyCoder comes with a number of these, available on demand, so I'll demonstrate how to use one of the more interesting ones.
 
 Google Maps are one of the most spectacular features to be found on any website. They provide a vast range of features and require very little effort to include on the page. That said, it takes some effort to learn how to do it, and we've taken away that effort by building our own ~ec~ plugin to handle maps for you. Currently it's a little basic but we hope to add more features as time goes by. Click here to load the map script:
@@ -10,7 +9,7 @@ The script builds a page using the full space available, then divides it into a
 
 In the variable list you'll see ~code:gmap Map~. This is part of the new functionality available with the plugin loaded, as are the commands later that make reference to the ~code:Map~.
 
-The map itself requires a div to place it in, then you can create the map using a very small set of commands. The first thing to add to the map is an 'API key' provided by Google to authorize the use of a map on this website. You can get your own API key by registering as a Google developer and requesting your key on the appropriate page. (Unfortunately it's beyond the scope of these notes to describe how to do it.) This particular key is one that restricts usage to pages on a limited range of websites, of which this is one. (The ~code:reverse~ part is to prevent GitHub detecting that an API key has been given, causing it to issue security warnings.)
+The map itself requires a div to place it in, then you can create the map using a very small set of commands. The first thing to add to the map is an 'API key' provided by Google to authorize the use of a map on this website. You can get your own API key by registering as a Google developer and requesting your key on the appropriate page. (Unfortunately it's beyond the scope of these notes to describe how to do it.) This particular key is one that restricts usage to pages on a limited range of websites, of which this is one. (The ~code:reverse~ part is to prevent GitHub issung regular security warnings that an API key has been written to the public repository that serves this website.)
 
 There are only 3 items of information needed to set up a map; ~code:latitude~, ~code:longitude~ and ~code:zoom~. Experiment with each of these to discover how they work; try to get a map displaying your own home.
 

resources/codex/md/step8.md

@@ -11,7 +11,7 @@ The rectangle is set to occupy 9% of the container's width and to have a border
 
 Don't be put off by the apparent complexity of CSS. It's well worth spending some time reading up on it, but in the end you just have to try things out. The great thing about using the ~ec~ editor is you can experiment until you succeed in making it work.
 
-So far, we have a gray rectangle in a larger box. The next command is ~code:wait 2 seconds~, which does just that. You can use wait to pause a script for any number of millis (milliseconds), ticks (100ths of a second), seconds or minutes.
+So far, we have a gray rectangle in a larger box. The next command is ~code:wait 2 seconds~, which does just that. You can use ~code:wait~ to pause a script for any number of ~code:millis~ (milliseconds), ~code:ticks~ (100ths of a second), ~code:seconds~ or ~code:minutes~. In all cases the final ~code:s~ is optional.
 
 Now for the animation itself. We use a variable ~code:Angle~ to count from 0 to 360. This is the number of degrees in a circle. If you're not mathematically inclined, try to visualize a clock with a second hand going around it. It's a rather odd second hand that stretches right across the clock from one edge to the other. If you were to look at the clock edge-on you wouldn't see the rotary movement; the second hand would just appear to get longer and shorter as it journeys around the dial. The mathematical sine function tells us the apparent length of the second hand at any point in its progression around the dial. In our example the diameter of the clock is 200 pixels (so the radius is 100 pixels) and the apparent length, seen end-on, varies from 0 to 200 pixels. (Exactly the same principle applies to the length of the day as the seasons change. So you see, maths can be useful.)
 

resources/codex/md/tools.md

@@ -8,11 +8,11 @@ The mechanism for requesting a plugin is very simple. Suppose you want to includ
 
 ~pre:load plugin `gmap`~
 
-In this example the plugin is a standard ~ec~ one but you can also load third-party plugins from any URL (if you deal with CORS issues).
+In this example the plugin is a standard ~ec~ one but you can also load third-party plugins from any URL if you deal with CORS issues.
 
 Once the plugin is loaded it is available to any script that needs it (but not the one that loaded it). Here, any script that includes map commands can be loaded and compiled, as in
 
-~pre:rest get Script from `/resources/scripts/myscript`
+~pre:rest get Script from `/resources/ecs/myscript.ecs`
 run Script~
 
 (This is the simplest form, that assumes you don't need to communicate with the script once it's running.)