From 5fc03cf63c0033230cba33a60a31d8de0908b0d1 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Tue, 11 Aug 2015 10:15:20 -0700
Subject: [PATCH] glossary: Provide a quick overview of important terms

And link them to the more detailed specification.

This borrows from appc, which calls the launched process tree "the
app" [1].  I don't see a point to abbreviating it, so I've gone with
"application".

Subsection titles for the entries will be obnoxiously spacious, but
the other alternatives seem worse:

a. An HTML definition list (<dl>) would have nice default styling, but
   it's annoying to write raw HTML.  And we would have needed
   something like:

     <dt name="bundle">Bundle</dt>
     <dd>

     A [directory structure](bundle.md) that is...

     </dd>

   to get Markdown-style links in the defintion itself.

b. A Markdown list (* ...) would have reasonable default styling, but
   there's no Markdown syntax for adding anchors to the entries.  And
   a glossary is much less useful if you can't link to a specific
   entry.

[1]: https://github.com/opencontainers/specs/pull/88#discussion_r36269387

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 README.md   |  1 +
 glossary.md | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 glossary.md

diff --git a/README.md b/README.md
index f85d5fff5..7b640ae01 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ Table of Contents
   - [Linux Specific Configuration](config-linux.md)
 - [Runtime and Lifecycle](runtime.md)
 - [Implementations](implementations.md)
+- [Glossary](glossary.md)
 
 ## Use Cases
 
diff --git a/glossary.md b/glossary.md
new file mode 100644
index 000000000..c69d72d90
--- /dev/null
+++ b/glossary.md
@@ -0,0 +1,22 @@
+# Glossary
+
+## Application
+
+A process tree launched inside a [container](#container).
+
+## Bundle
+
+A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating [containers](#container) and launching [applications](#application).
+
+## Configuration
+
+A [file](config.md) in a [bundle](#bundle) which defines the intended [container](#container) and [application](#application).
+
+## Container
+
+An environment setup for the [application](#application) (namespaces, resource limits, mounts, …).
+
+## Runtime
+
+An implementation of this specification.
+It reads a [configuration file](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), and launches an [application](#application) inside the container.