This closes #1144

LICENSE

@@ -250,6 +250,13 @@ This project includes the software: DataTables Table plug-in for jQuery
   Used under the following license: The BSD 3-Clause (New BSD) License (http://opensource.org/licenses/BSD-3-Clause)
   Copyright (c) Allan Jardine (2008-2012)
 
+This project includes the software: glossarizer
+  Available at: https://github.com/PebbleRoad/glossarizer
+  Developed by: Vinay M, PebbleRoad Pte Ltd (http://www.pebbleroad.com)
+  Version used: 1.5
+  Used under the following license: The MIT License (http://opensource.org/licenses/MIT)
+  Copyright (c) Vinay M, PebbleRoad Pte Ltd (2004-2016)
+
 This project includes the software: jQuery Form Plugin
   Available at: https://github.com/malsup/form
   Developed by: Mike Alsup (http://malsup.com/)

brooklyn-docs/_includes/base-head.html

@@ -7,11 +7,24 @@
 <link href="{% dependency_url bootstrap.css %}" rel="stylesheet">
 <link href="{{site.path.style}}/deps/octicons/octicons.css" rel="stylesheet">
 <link href="{{site.path.style}}/deps/bootstrap-theme.css" rel="stylesheet">
+<link href="{{site.path.style}}/deps/tooltip.css" rel="stylesheet">
 
 <link rel="stylesheet" href="{{ site.path.style }}/css/code.css" type="text/css" media="screen" />
 
 <link href="{{site.path.style}}/css/website.css" rel="stylesheet">
 
 <script src="{% dependency_url jquery.js %}"></script>
+<script src="{% dependency_url glossarizer.js %}"></script>
 <script src="{% dependency_url bootstrap.js %}"></script>
+<script src="{% dependency_url tooltip.js %}"></script>
 <script type="text/javascript" src="{{ site.path.style }}/deps/jquery.cookie.js"></script>
+<script>
+$(function(){
+  $('body').glossarizer({
+    sourceURL: '/guide/glossary.json?'+Math.random(),
+    caseSensitive : true,
+    lookupTagName : 'p, ul',
+    callback: function(){ new tooltip(); }
+  });
+});
+</script>

brooklyn-docs/guide/glossary.json

@@ -0,0 +1,22 @@
+[
+  {
+    "term": "location, !location:",
+    "description": "A server or resource to which Apache Brooklyn can deploy applications"
+  },
+  {
+    "term": "blueprint",
+    "description": "A descriptor or pattern which describes how Apache Brooklyn should deploy applications"
+  },
+  {
+    "term": "entity",
+    "description": "A software package or service Apache Brooklyn can interact with"
+  },
+  {
+    "term": "sensor, !<code>sensor",
+    "description": "A sensor is a property of an Apache Brooklyn entity, updated in real-time"
+  },
+  {
+    "term": "effector",
+    "description": "Effectors are tools Apache Brooklyn provides, that allow you to manipulate the live entities within an application"
+  }
+]

brooklyn-docs/guide/ops/security-guidelines.md

@@ -40,7 +40,7 @@ configuration" feature. This allows credentials to be retrieved from a store man
 rather than being stored within YAML blueprints or brooklyn.properties.
 
 A secure credential store is strongly recommended, such as use of 
-[HashiCorp's Vault](www.vaultproject.io) - see
+[HashiCorp's Vault](https://www.vaultproject.io) - see
 `org.apache.brooklyn.core.config.external.vault.VaultExternalConfigSupplier`.
 
 

brooklyn-docs/guide/start/blueprints.md

@@ -6,44 +6,84 @@ children:
 - { section: Launching from a Blueprint, title: Blueprint } 
 ---
 
-<div style="width: 100%; display: block; background-color: #CC9966; margin-bottom: 2px;  padding: 50px 30px 50px 80px;" >
-  <h3>NOTE</h3>
-  <div>
-  The structure of Brooklyn's repositories is changing at present (Jan 2016). Until this is complete 
-  please obtain the "br" command line tool from <a href="https://github.com/brooklyncentral/brooklyn-cli">Brooklyn Central</a>
-  </div>
-</div>
+Blueprints are descriptors or patterns which describe how Apache Brooklyn should deploy applications. Blueprints are written in [YAML](https://en.wikipedia.org/wiki/YAML){:target="_blank"} and all of the entities available are defined in the __[Brooklyn Catalog](../../website/learnmore/catalog/)__.
 
 ## Launching from a Blueprint
 
-We'll start by deploying an application with a simple YAML blueprint containing a Tomcat server.
+We'll start by deploying an application with a simple YAML blueprint containing an [Apache Tomcat](https://tomcat.apache.org/){:target="_blank"} server.
 
-Copy the blueprint below into a text file, "myapp.yaml", in your workspace, but *before* you create an application with 
-it, modify the YAML to specify the location where the application will be deployed.  (Note, to copy the file you can
-hover your mouse over the right side of the text box below to get a Javascript "copy" button.)
+Copy the blueprint below into a text file, "myapp.yaml", in your workspace (Note, to copy the file you can
+hover your mouse over the right side of the text box below to get a Javascript "copy" button).
 
 {% highlight yaml %}
 name: Tomcat
-location:
-  jclouds:aws-ec2:
-    identity: ABCDEFGHIJKLMNOPQRST
-    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
 services:
-- serviceType: brooklyn.entity.webapp.tomcat.TomcatServer
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+  name: tomcatServer
+location: <your-location-definition-goes-here>
+{% endhighlight %}
+
+
+## Locations
+
+Before you can create an application with this configuration, you need to modify the YAML to specify a location. Locations in Apache Brooklyn are server resources which Brooklyn can use to deploy applications. These locations may be servers or cloud providers which provide access to servers. 
+
+In order to configure the location in which Apache Brooklyn launches an application, replace the ```location:``` element with values for your chosen target environment. Here are some examples of the various location types:
+
+{::options parse_block_html="true" /}
+
+<ul class="nav nav-tabs">
+    <li class="active impl-1-tab"><a data-target="#impl-1, .impl-1-tab" data-toggle="tab" href="#">Vagrant</a></li>
+    <li class="impl-2-tab"><a data-target="#impl-2, .impl-2-tab" data-toggle="tab" href="#">Clouds</a></li>
+    <li class="impl-3-tab"><a data-target="#impl-3, .impl-3-tab" data-toggle="tab" href="#">BYON</a></li>
+</ul>
+
+<div class="tab-content">
+<div id="impl-1" class="tab-pane fade in active">
+
+The Vagrant configuration described in [Running Apache Brooklyn](./running.html), on the previous page is the recommended way of running this tutorial. This configuration comes with four blank vagrant configurations called byon1 to byon4.
+
+These can be launched by entering the following command into the terminal in the vagrant configuration directory.
+
+{% highlight bash %}
+ $ vagrant up byon1 byon2 byon3 byon4
+{% endhighlight %}
+
+The location in "myapp.yaml" can now be replaced with the following YAML to launch using these vagrant servers.
+
+{% highlight yaml %}
+location:
+  byon:
+    user: vagrant
+    password: vagrant
+    hosts:
+      - 10.10.10.101
+      - 10.10.10.102
+      - 10.10.10.103
+      - 10.10.10.104
 {% endhighlight %}
 
-Replace the ```location:``` element with values for your chosen target environment, for example to use SoftLayer rather 
-than AWS (updating with your own credentials): 
+</div>
+<div id="impl-2" class="tab-pane fade">
+
+Apache Brooklyn uses [Apcahe jclouds](http://jclouds.apache.org/){:target="_blank"} to support a range of cloud locations. More information on the range of providers and configurations is available [here](../ops/locations/#clouds){:target="_blank"}.
+
+As an example, here is a configuration for [Amazon Web Services (AWS)](http://www.aws.amazon.com){:target="_blank"}. Swap the identity and credential with your AWS account details, then replace the location in your "myapp.yaml" with this.
 
 {% highlight yaml %}
 location:
-  jclouds:softlayer:
+  jclouds:aws-ec2:
     identity: ABCDEFGHIJKLMNOPQRST
     credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
 {% endhighlight %}
 
-Or, if you already have machines provisioned, you can use the "bring your own nodes" (byon) approach. 
-Of course, replace the identity and address values below with your own values.
+</div>
+<div id="impl-3" class="tab-pane fade">
+
+The Bring Your Own Nodes (BYON) configuration allows Apache Brooklyn to make use of already available servers. These can be specified by a list of IP addresses with a user and password as shown below. More information including the full range of configuration options is available [here](../ops/locations/#byon){:target="_blank"}. 
+
+Replace the hosts, user and password in the example below with your own server details, then replace the location in your "myapp.yaml" with this.
+
 {% highlight yaml %}
 location:
   byon:
@@ -56,30 +96,36 @@ location:
     - 192.168.0.19
 {% endhighlight %}
 
-**Note**: See __[Locations](../ops/locations)__ in the Operations section of the User Guide for instructions on setting
-up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file 
-on disk rather than in the blueprint.
-(For the application above, if you are using a "Bring your own Nodes" location, you will need at least three nodes.)
+</div>
+</div>
+
+---
+
+**Note**: For instructions on setting up a variety of locations or storing credentials/locations in a file on disk rather than in the blueprint, see __[Locations](../ops/locations)__ in the Operations section of the User Guide.
+
+## Deploying the Application
 
-First you will have to log in to brooklyn:
+First, log in to brooklyn with the command line interface (CLI) tool by typing:
 {% highlight bash %}
 $ br login http://localhost:8081/
 {% endhighlight %}
 
-To secure the server you can add a username and password in Brooklyn's properties file, as described in the User Guide. 
-Then the login command will require the additional parameters of the userid and password.
+To secure the Apache Brooklyn instance, you can add a username and password to Brooklyn's properties file, as described in the User Guide [here](../ops/brooklyn_properties.html){:target="_blank"}. 
+If this is configured, the login command will require an additional parameter for the userid and will then prompt for a password.
 
 Now you can create the application with the command below:
 
 {% highlight bash %}
-$ br deploy myapp.yaml
+$ br deploy myapp.yaml 
+{% endhighlight %}
+<pre>
 Id:       hTPAF19s   
 Name:     Tomcat   
-Status:   In progress   
-{% endhighlight %}
+Status:   In progress  
+</pre>
 
 Depending on your choice of location it may take some time for the application to start, the next page describes how 
-you can monitor the progress of the application deployment and verify its successful deployment.
+you can monitor the progress of the application deployment and verify if it was successful.
 
 ## Next