From 704a8828d200ff4bdfb650e376e2c0b91caee624 Mon Sep 17 00:00:00 2001
From: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
Date: Sun, 17 Jan 2016 00:54:37 -0400
Subject: [PATCH] Backport metadata chapter and add section about sorted
 lookups. Closes GitLab issue#234.

---
 docs/topics/index.rst    |  1 +
 docs/topics/metadata.rst | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 docs/topics/metadata.rst

diff --git a/docs/topics/index.rst b/docs/topics/index.rst
index 8ec133f1e9..70e81554fd 100644
--- a/docs/topics/index.rst
+++ b/docs/topics/index.rst
@@ -9,6 +9,7 @@ Introductions to all the key parts of Mayan EDMS you'll need to know:
    file_storage
    permissions
    transformations
+   metadata.rst   
    versioning
    signatures
    indexes
diff --git a/docs/topics/metadata.rst b/docs/topics/metadata.rst
new file mode 100644
index 0000000000..ce62870c42
--- /dev/null
+++ b/docs/topics/metadata.rst
@@ -0,0 +1,34 @@
+========
+Metadata
+========
+
+Metadata is the name of the attribute of a document. The concept of metadata is
+divided in two: **metadata types** (size, color, distance) and **metadata values** for
+those types. Metadata types are defined in the setup menu and associated with
+document types. Then when a document is uploaded, a value for that metadata
+can be entered. There are two kinds of metadata type to document type relations:
+optional and required. When a metadata type is optional for a document type,
+it can be left blank for a document being uploaded and the upload will still
+be successful. On the other hand required metadata type must be given a value
+or it will not be possible to upload the document at hand.
+
+Examples of metadata type: Invoice number, color, employee id.
+
+The data entry of metadata types can be set to allow any value to be provided
+(the default) or a list of possible values can be entered in the ``Lookup``
+configuration option and users will be presented with a drop down list of options
+instead of the default text entry box.
+
+We the ``Lookup`` option is used, it is convenient for the end user to select
+from a sorted list. In order to automatically sort the metadata list,
+use the python function sorted().
+
+For example, a metadata list of first names may look like this in the Lookup
+field of the metadata edit screen::
+
+    ["Markus", "Lyndia", "Bunny", "Glynis", "Juli", "Marie," "Elliot", "Kimberely", "Catherina", "Tobie"]
+
+To insure the user always sees a sorted metadata field when adding metadata
+ to a document, write the list like this::
+
+     sorted(["Markus", "Lyndia", "Bunny", "Glynis", "Juli", "Marie," "Elliot", "Kimberely", "Catherina", "Tobie"]).