Revising tool setup

en-US/Setting_Up_Tools.md

@@ -7,93 +7,122 @@ category: Setting Up Tools
 title: Setting Up Tools
 ---
 
-To allow for easier installing, using and updating of the various software tools which form part of the toolchain, we use a Virtual Machine (VM). This VM is based on [Ubuntu](https://www.ubuntu.com/). 
+Our projects use a consistent set of free tools for building and modifying fonts. To build our fonts you will need to use the same toolchain and workflow we use.
+To allow for easier installation, use, and management of the various software tools which form part of the toolchain, we use a Virtual Machine (VM). This VM is currently based on [Ubuntu] 16.04 LTS (Xenial). *There is ongoing work happening on a newer version based on Ubuntu 18.04 LTS (Bionic) and python3 but it's not fully ready yet. Stay tuned. It is also possible to separately install required packages directly on a linux-based OS, but that is not covered in this guide.*
 
-### Installing Virtualbox and Vagrant ###
+The process of setting up the toolchain involves:
 
-We need to install Virtualbox from [https://www.virtualbox.org/wiki/Downloads](https://www.virtualbox.org/wiki/Downloads)
-- Download the installer for the preferred host OS. (Please stay with version series 5.2 at this stage).
-- Run the installer (we might have to reboot).
-- Also install the corresponding Extension Pack.
+- Installing Virtualbox and Vagrant
+- Setting up a font projects folder
+- Configuring Vagrant
+- Running Vagrant for the first time - to download and install required tools
 
-We use Vagrant to automatically drive Virtualbox and make handling of our VM much simpler, less manual and error-prone.
+Please bear in mind that __the toolchain is fairly large (over 500 software components for both base OS and toolchain: a total of about 2 Gb)__, so it will require a __comfortable unmetered network connection__ to download both the base image and the various components on top of that. Even on recent hardware and with a decent network connection it's likely to take __more than 20 minutes__ to download and install everything. But it sure beats having to install everything manually.
 
-We need to install Vagrant from [https://www.vagrantup.com/downloads.html](https://www.vagrantup.com/downloads.html)
-- Download the 64 bits installer for the preferred host OS. 
-- Run the installer (we might have to reboot).
+## Step 1: Install Virtualbox and Vagrant
 
-### Understanding what Smith is and what it does ###
+Virtualbox enables us to spin up a new, separate, linux-based environment in a guest VM without any risk to the host computer or the files we are working on. To install Virtualbox:
 
-[Smith](https://github.com/silnrsi/smith) is a Python-based framework for building, testing and maintaining WSI (Writing Systems Implementation) components such as fonts. It is based on waf. Smith orchestrates and integrates various tools and utilities to make a standards-based open font design and production workflow easier to manage.
+- Download the [Virtualbox installer] for the preferred host OS. __Please stay with version series 5.2 for now__.
+- Run the installer. You may also need to reboot.
+- Install the corresponding Extension Pack.
 
-Building a font involves numerous steps and various programs, which, if done by hand, would be prohibitively slow. Even working out what those steps are can take a lot of work. Smith uses a dedicated file at the root of the project (the file is python-based) to allow the user to describe how to build the font. By chaining the different build steps intelligently, smith reduces build times to seconds rather than minutes or hours, and makes build, test, fix, repeat cycles very manageable. By making these processes repeatable, including for a number of fonts at the same time, projects can be shared with others simply, or - better yet - they can be included in a CI (Continuous Integration) system. This allows for fonts (and their various source formats) to truly be libre/open source software and developed with open and collaborative methodologies.
+We use Vagrant to automatically drive Virtualbox and make handling of our VM much simpler, less manual and less error-prone. To install Vagrant:
 
-Smith is _Copyright (c) 2011-2018 SIL International (www.sil.org)_   
-and is released under _the BSD license_.
+- Download the [64-bit Vagrant installer] for the preferred host OS. 
+- Run the installer. You may also need to reboot.
 
-Smith is developed and maintained by [SIL International's WSTech team](https://software.sil.org/wstech/).
+## Step 2: Set up a font projects folder
 
-The toolchain components (smith itself and the various components) are all open and do not place any undue restricted licensing requirements on the user or developer. We can run it on any system via a VM, and we can run it on a Continuous Integration (CI) as well if desired. We can copy the whole VM to other computers or share it with colleagues and friends without restrictions. 
+We recommend that you set up a dedicated font projects folder (such as *Documents/work/fonts/*). This makes it easy to use a single VM configuration for multiple projects. __Further steps and examples in this guide will assume that you have set up this folder.__
 
-#### Downloading the current smith vagrant profile ####
+## Step 3: Configure Vagrant
 
-Download the current Vagrant profile from the smith github repository. The profile is just two files:
--  [Vagrantfile](https://github.com/silnrsi/smith/raw/master/vm-install/Vagrantfile)
--  [provision.sh](https://github.com/silnrsi/smith/raw/master/vm-install/provision.sh)
+Our particular Vagrant VM configuration is defined by two files available from our Smith project github repository. Download these two files and put them into your font projects folder (*Documents/work/fonts/*). The easiest way to do that is to right click on the following links, and choose "Save Link As..." or "Download Linked File As...":
 
-Download these two files and put them into the same parent folder of the font project folder: __Documents/work/fonts/__. (We do it this way so we can use the same VM for multiple font projects in subfolders). 
+-  [Vagrantfile] (be sure to save the file as "Vagrantfile" not "Vagrantfile.txt")
+-  [provision.sh]
 
-Then check out the out Andika Mtihani git repository by typing:
+## Step 4: Run Vagrant
 
-> cd __~/Documents/work/fonts/__
->
-> git clone https://github.com/silnrsi/font-andika-mtihani 
+The first time you run Vagrant it will automatically:
 
-This will checkout a local working copy of the git repository in __~/Documents/work/fonts/font-andika-mtihani/__. (We can also use a GUI client for git to do that if needed).
+- Download all the required software components
+- Install them in a fresh VM
+- Set up shared folders to provide access to everything in your font projects folder
+- Enable you to control the VM through a local ssh connection
 
-#### Spinning up the profile and testing that it runs ####
+To run Vagrant use the terminal to navigate to your font projects folder (*/Documents/work/fonts/*) and type:
 
-Open this parent folder __Documents/work/fonts/__ in the terminal and type:
+> `vagrant up`
 
-> vagrant up 
+*Note that this first-time run will take a while - typically 20 minutes or more - while it "provisions" (configures) the VM. Time to grab a cup of tea or coffee...*
 
-This will start spinning up the whole toolchain. 
-Now is probably at good time to go grab a cup of tea or coffee...
+While it's installing everything you'll notice hundreds of lines of commands and messages. There may even be warnings among the messages. As long as the final message isn't a brignt red warning, and you see the message "smith is now ready to use" you're probably fine.
 
-Vagrant has a few subcommands which are pretty self-explanatory and useful to remember:
-- __vagrant up__ spins up the profile by reading the configuration in Vagrantfile, then provisions the VM by running the provision.sh script
-- __vagrant provision__ can be typed separately once the VM is running to have it go through the installation steps and to get updates for example. 
-- __vagrant ssh__ allows us to log into the VM so that we can run the various commands (see next section). 
-- __vagrant halt__ stops the VM
-- __vagrant destroy__ deletes the VM but not any of the work files shared on the host computer 
+After the provisioning is complete, briefly test the VM by connecting with it through ssh:
 
-The vagrant profile will automatically set up shared folders, so the VM will see the files under the __Documents/work/fonts/__ folder on the host computer. We can adjust this in the Vagrantfile to our liking (and then type __vagrant reload__) but by default it shares the folder where it was launched from, in our case __Documents/work/fonts/__ on the host computer with __/smith/__ inside the VM. 
+> `vagrant ssh`
 
-(Vagrant stores certain files in a __.vagrant/__ subfolder on the host computer. _Remember that if we rename or move that subfolder or the whole parent folder in the course of working on the project, vagrant won't be able to find the path to the VM again and we may have to spin up a new VM._ The actual Virtual Machine configuration and disk images are stored in __~/.Virtualbox/__.)
+The command prompt should change. Then navigate to your font projects folder, which in the VM is mapped to */smith*:
 
-Watch the command-line output as it automatically downloads, sets up the base VM (also called a box in Vagrant jargon) then runs the provision.sh script which contains instructions on what to install and from where. We can open the provision.sh script in our preferred text editor to see what it does. 
+> `cd /smith`
 
-Once the whole vagrant up process has finished (and we see the message "smith is now ready to use"), we can type __vagrant ssh__ to log into the VM. 
+Then leave the VM:
 
-### Keeping the VM updated ###
+> `exit`
 
-Over the course of working with the VM, there will be updates to various components of the toolchain. These updates are not applied automatically. We can choose to apply them by typing inside the VM: 
-> sudo apt-get update -y -q
->
-> sudo apt-get upgrade -y -q -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" -o Dpkg::Options::="--force-overwrite" -u -V --with-new-pkgs
+Shut down the VM:
 
-or by telling Vagrant to reprovision (re-run the provision.sh script which also has the two commands above) by typing in the terminal on the host computer:
-> vagrant provision
+> `vagrant halt`
 
+If at any point in this something doesn't work, then the Vagrant provision may have failed at some point. In that case, be sure to `exit` the VM then run the following to try the provisioning step again:
 
-### Video preview of the steps ###
+> `vagrant provision`
 
-(The video skips some of the longer parts of the installation process).
+### Video walkthrough
 
-Watch it full screen for more legibility. 
+Here is a video that shows some of the installation process but skips some of the longer steps. Watch it full screen for more legibility. 
 
 <video src="../assets/videos/setting-up-tools.webm" width="90%" height="90%" controls preload></video>
 
+## Using the VM
+
+After the VM is configured and working, the normal process of using it is to:
+
+- Navigate to your font projects in the terminal
+- `vagrant up`
+- `vagrant ssh`
+- Wait until the prompt changes
+- `cd /smith`
+- (do whatever you're wanting to do - see next section on [Building Font Projects])
+- When done, `exit`
+- Wait until the prompt changes back
+- `vagrant halt`
+
+## Maintaining the VM and tools
+
+Normally the VM only needs to be updated if there is a particular feature or bug fix in a newer version of the tools that you want to use. Running `vagrant provision` will automatically get the latest versions of everything already installed. *However be aware that newer versions may potentially cause problems, so tread carefully!*
 
+If you want to configure a new VM, or get the latest set of tools (for example, if we've added new tools needed for some project), then you'll need to go back to Step 3 above. BTW - `vagrant destroy` will delete the VM but not any of the work files shared on the host computer.
 
+## Technical notes on Vagrant
+
+The vagrant profile will automatically set up shared folders, so the VM will see the files inside the folder from which you've run Vagrant (typically your font projects folder - *Documents/work/fonts/*. You can adjust this by editing the Vagrantfile to your liking.
+
+Vagrant stores certain files in a __.vagrant/__ subfolder on the host computer. _Remember that if we rename or move that subfolder or the whole parent folder in the course of working on the project, vagrant won't be able to find the path to the VM again and we may have to spin up a new VM._ The actual Virtual Machine configuration and disk images are stored in __~/.Virtualbox/__.
+
+Watch the command-line output as it automatically downloads, sets up the base VM (also called a box in Vagrant jargon) then runs the provision.sh script which contains instructions on what to install and from where. You can open the provision.sh script in your preferred text editor to see what it does. 
+
+It is also possible to update the VM components separate from running `vagrant provision`. From the command prompt inside the VM run:
+
+> sudo apt-get update -y -q
+>
+> sudo apt-get upgrade -y -q -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confold" -o Dpkg::Options::="--force-overwrite" -u -V --with-new-pkgs
 
+[Ubuntu]: https://www.ubuntu.com/
+[Virtualbox installer]: https://www.virtualbox.org/wiki/Downloads
+[64-bit Vagrant installer]:  https://www.vagrantup.com/downloads.html
+[Vagrantfile]: https://github.com/silnrsi/smith/raw/master/vm-install/Vagrantfile
+[provision.sh]: https://github.com/silnrsi/smith/raw/master/vm-install/provision.sh
+[Building Font Projects]: Building_Font_Projects.md