1 files changed, 91 insertions, 0 deletions
diff --git a/paper/lua-filters/scholarly-metadata/README.md b/paper/lua-filters/scholarly-metadata/README.md
new file mode 100644
index 0000000..7fb1d2a
--- /dev/null
+++ b/paper/lua-filters/scholarly-metadata/README.md
@@ -0,0 +1,91 @@
+# scholarly-metadata
+
+The filter turns metadata entries for authors and their
+affiliations into a canonical form. This allows users to
+conveniently declare document authors and their affiliations,
+while making it possible to rely on default object metadata
+structures when using the data in other filters or when accessing
+the data from custom templates.
+
+
+## Canonical format for authors and affiliations
+
+Authors and affiliations entries are treated as *named objects*.
+All named objects will have an ID and a name, i.e. they are
+metadata objects with *at least* those two keys:
+
+    - id: namedObjectExample
+      name: Example for a named object.
+
+The filter converts the *author* and *institute* metadata fields
+into lists of named objects.
+
+E.g., the following YAML data
+
+    author:
+      - Jane Doe:
+          email: 'jane.doe@example.edu'
+      - John Q. Doe
+
+
+will be transformed into
+
+    author:
+    - email: 'jane.doe\@example.edu'
+      id: Jane Doe
+      name: Jane Doe
+    - id: 'John Q. Doe'
+      name: 'John Q. Doe'
+      
+Internally, `id` will be a simple string, while `name` is of type
+`MetaInlines`.
+      
+
+## Referencing affiliations
+
+Author affiliations are a common feature of scholarly
+publications. It is possible to add institutes to each author
+object. Three methods of doing this are supported.
+
+1.  **Referencing institutes by list index**: affiliations can be
+    listed in the *institute* metadata field and then referenced
+    by using the numerical index:
+    
+        institute:
+          - Acme Corporation
+          - Federation of Planets
+        author:
+          - Jane Doe:
+              institute: [1, 2]
+          - John Q. Doe:
+              institute: [2]
+        
+    This is also the canonical representation used to keep track
+    of author affiliations.
+
+2.  **Referencing institutes by ID**: using numerical indices is
+    error prone and difficult to maintain when adding or removing
+    authors or affilications. It is hence possible to use IDs
+    instead:
+
+        institute:
+          - acme: Acme Corporation
+          - federation: Federation of Planets
+        author:
+          - Jane Doe:
+              institute: [acme, federation]
+          - John Q. Doe:
+              institute: [federation]
+
+3.  **Adding institute as an attribute**: sometimes it might be
+    more convenient to give an affiliation directly in the
+    author's YAML object. Those objects can still be referenced
+    by ID from authors listed below such entry.
+    
+        author:
+          - Jane Doe:
+              institute:
+               - Acme Cooproration
+               - federation: Federation of Planets
+          - John Q. Doe:
+              institute: [federation]