smooth edges after breaking the monolithic document

Mostly fixing the heading levels, but some transition text was edited.

Author: 0xaf1f

00-installation/README.md

@@ -1,4 +1,4 @@
-### Install
+# Installing Singularity
 Here we will install the latest tagged release from [GitHub](https://github.com/singularityware/singularity). If you prefer to install a different version or to install Singularity in a different location, see these [Singularity docs](http://singularity.lbl.gov/docs-installation).
 
 We're going to compile Singularity from source code.  First we'll need to make sure we have some development tools installed so that we can do that.  On Ubuntu, run these commands to make sure you have all the necessary packages installed.
@@ -49,7 +49,11 @@ $ . etc/bash_completion.d/singularity
 $ sudo cp etc/bash_completion.d/singularity /etc/bash_completion.d/
 ```
 
-If everything went according to plan, you now have a working installation of Singularity.  You can test your installation like so:
+If everything went according to plan, you now have a working installation of Singularity.
+Simply typing `singularity` will give you a summary of all the commands you can use.
+Typing `singularity help <command>` will give you more detailed information about running an individual command.
+
+You can test your installation like so:
 
 ```
 $ singularity run docker://godlovedc/lolcow
@@ -75,4 +79,5 @@ Creating container runtime...
 
 Your cow will likely say something different (and be more colorful), but as long as you see a cow your installation is working properly.  
 
-This command downloads and runs a container from [Docker Hub](https://hub.docker.com/r/godlovedc/lolcow/).  During the next hour we will learn how to build a similar container from scratch.  
+This command downloads, converts, and runs a container from [Docker Hub](https://hub.docker.com/r/godlovedc/lolcow/).
+In the next exercise, we will learn how to build a similar container from scratch.

01-building/README.md

@@ -1,11 +1,6 @@
-## Hour 2 (Building and Running Containers)
-
-In the second hour we will build the preceding container from scratch. 
-
-Simply typing `singularity` will give you an summary of all the commands you can use. Typing `singularity help <command>` will give you more detailed information about running an individual command.
-
-### Building a basic container
+# Building a basic container
 
+In this exercise, we will build a container from scratch similar to the one we used to test the installation.
 To build a singularity container, you must use the `build` command.  The `build` command installs an OS, sets up your container's environment and installs the apps you need.  To use the `build` command, we need a **recipe file** (also called a definition file). A Singularity recipe file is a set of instructions telling Singularity what software to install in the container.
 
 The Singularity source code contains several example definition files in the `/examples` subdirectory.  Let's copy the ubuntu example to our home directory and inspect it.
@@ -57,7 +52,7 @@ But if you want to shell into a container and tinker with it (like we will do he
 
 When your build finishes, you will have a basic Ubuntu container saved in a local directory called `lolcow`.
 
-### Using `shell` to explore and modify containers
+# Using `shell` to explore and modify containers
 
 Now let's enter our new container and look around.  
 

02-io/README.md

@@ -1,4 +1,4 @@
-### Blurring the line between the container and the host system.
+# Blurring the line between the container and the host system
 
 Singularity does not try to isolate your container completely from the host system.  This allows you to do some interesting things.
 

03-runscript/README.md

@@ -1,8 +1,7 @@
-## Hour 3 (advanced Singularity usage)
+# The Runscript: Making containerized apps behave more like normal apps
 
-### The Runscript: Making containerized apps behave more like normal apps
-
-In the third hour we are going to consider an extended example describing a containerized application that takes a file as input, analyzes the data in the file, and produces another file as output.  This is obviously a very common situation.  
+We are now going to consider an extended example describing a containerized application that takes a file as input, analyzes the data in the file, and produces another file as output.
+This is obviously a very common situation.
 
 Let's imagine that we want to use the cowsay program in our `lolcow.simg` to "analyze data".  We should give our container an input file, it should reformat it (in the form of a cow speaking), and it should dump the output into another file.  
 

04-bind-mounts/README.md

@@ -1,4 +1,4 @@
-### Bind mounting host system directories into a container
+# Bind mounting host system directories into a container
 
 It's possible to create and modify files on the host system from within the container. In fact, that's exactly what we did in the previous example when we created output files in our home directory.  
 

05-the-hubs/README.md

@@ -1,4 +1,4 @@
-### Singularity Hub and Docker Hub
+# Singularity Hub and Docker Hub
 
 We've spent a lot of time on building and using your own containers so that you understand how Singularity works. But there's an easier way! [Docker Hub](https://hub.docker.com/)
 hosts over 100,000 pre-built, ready-to-use containers.  And singularity makes it easy to use them.

06-misc/README.md

@@ -1,22 +1,22 @@
-## Miscellaneous Topics
+# Miscellaneous Topics
 
-### X11 and OpenGL
+## X11 and OpenGL
 
 You can use Singularity containers to display graphics through common protocols. To do this, you need to install the proper graphics stack within the Singularity container.  For instance if you want to display X11 graphics you must install `xorg` within your container.  In an Ubuntu container the command would look like this.  
 
 ```
 $ apt-get install xorg
 ```
 
-### GPU computing
+## GPU computing
 
 In Singularity v2.3+ the experimental `--nv` option will look for NVIDIA libraries on the host system and automatically bind mount them to the container so that GPUs work seamlessly. 
 
-### Using the network on the host system
+## Using the network on the host system
 
 Network ports on the host system are accessible from within the container and work seamlessly.  For example, you could install ipython within a container, start a jupyter notebook instance, and then connect to that instance using a browser running outside of the container on the host system or from another host.  
 
-### a note on SUID programs and daemons
+## a note on SUID programs and daemons
 
 Some programs need root privileges to run.  These often include services or daemons that start via the `init.d` or `system.d` systems and run in the background.  For instance, `sshd` the ssh daemon that listens on port 22 and allows another user to connect to your computer requires root privileges.  You will not be able to run it in a container unless you start the container as root.
 

README.md

@@ -11,9 +11,7 @@ This is an introductory workshop on Singularity. It was originally taught by Dav
 - [Singularity Hub](https://singularity-hub.org/)
 - [Docker Hub](https://hub.docker.com/)
 
-## Hour 1 (Introduction and Installation)
-
-### What IS a software container anyway? (And what's it good for?)
+## What IS a software container anyway? (And what's it good for?)
 
 A container allows you to stick an application and all of its dependencies into a single package.  This makes your application portable, shareable, and reproducible.
 
@@ -28,7 +26,7 @@ Here are some examples of things you can do with containers:
 - Install and run an application that requires a complicated stack of dependencies with a few keystrokes.
 - Create a pipeline or complex workflow where each individual program is meant to run on a different operating system.
 
-### How do containers differ from virtual machines (VMs)
+## How do containers differ from virtual machines (VMs)
 
 Containers and VMs are both types of virtualization.  But it's important to understand the differences between the two and know when to use each.
 
@@ -46,7 +44,7 @@ Because of their differences, VMs and containers serve different purposes and sh
 - VMs are good for long running interactive sessions where you may want to use several different applications.  (Checking email on Outlook and using Microsoft Word and Excel).
 - Containers are better suited to running one or two applications non-interactively in their own custom environments.
 
-### Docker
+## Docker
 
 [Docker](https://www.docker.com/) is currently the most widely used container software.  It has several strengths and weaknesses that make it a good choice for some projects but not for others.
 
@@ -77,7 +75,7 @@ See https://docs.docker.com/engine/security/security/#docker-daemon-attack-surfa
 
 Docker shines for DevOPs teams providing cloud-hosted micro-services to users.
 
-### Singularity 
+## Singularity
 
 [Singularity](http://singularity.lbl.gov/) is a relatively new container software originally developed by Greg Kurtzer while at Lawrence Berkley National labs.  It was developed with security, scientific software, and HPC systems in mind.