From 18734986bc9e3ab47f63753e16dd791b18db6754 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 1/2] glossary: Provide a quick overview of important terms

And link them to the more detailed specification.

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.

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

diff --git a/README.md b/README.md
index 5cf3e3400..e838b0188 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,7 @@ Table of Contents
 - [Runtime and Lifecycle](runtime.md)
   - [Linux Specific Runtime](runtime-linux.md)
 - [Implementations](implementations.md)
+- [Glossary](glossary.md)
 
 In the specifications in the above table of contents, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
 
diff --git a/glossary.md b/glossary.md
new file mode 100644
index 000000000..8eaee1402
--- /dev/null
+++ b/glossary.md
@@ -0,0 +1,19 @@
+# Glossary
+
+## Bundle
+
+A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating a [container](#container) and launching a process within it.
+
+## Configuration
+
+The [`config.json`](config.md) and [`runtime.json`](runtime-config.md) files in a [bundle](#bundle) which define the intended [container](#container) and container process.
+
+## Container
+
+An environment for executing processes with configurable isolation and resource limitations.
+For example, namespaces, resource limits, and mounts are all part of the container environment.
+
+## Runtime
+
+An implementation of this specification.
+It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md).

From 0f9ec22bd45e11bd3bfc5fd523a8c893312ec532 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Fri, 25 Sep 2015 15:09:03 -0700
Subject: [PATCH 2/2] glossary: Specify UTF-8 for all our JSON
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I wish there was a cleaner reference for what UTF-8 was.  But [1]
seems too glib, and I can't find a more targetted link than just
dropping folks into a Unicode chapter (which is what [1] does):

  The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011)

With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95.

I'd rather put this normative requirement in the configuration-spec
files, but maintainer consensus was to put it in the glossary [2,3].

[1]: https://en.wikipedia.org/wiki/UTF-8
[2]: https://github.com/opencontainers/specs/pull/146#issuecomment-138970417
[3]: https://github.com/opencontainers/specs/pull/146#issuecomment-143348788

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 glossary.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/glossary.md b/glossary.md
index 8eaee1402..00075621c 100644
--- a/glossary.md
+++ b/glossary.md
@@ -13,7 +13,14 @@ The [`config.json`](config.md) and [`runtime.json`](runtime-config.md) files in
 An environment for executing processes with configurable isolation and resource limitations.
 For example, namespaces, resource limits, and mounts are all part of the container environment.
 
+## JSON
+
+All configuration [JSON][] MUST be encoded in [UTF-8][].
+
 ## Runtime
 
 An implementation of this specification.
 It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md).
+
+[JSON]: http://json.org/
+[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf