1 files changed, 57 insertions, 0 deletions
diff --git a/tracker/documentation-meta-attr.mdwn b/tracker/documentation-meta-attr.mdwn
new file mode 100644
index 0000000..fbec9c2
--- /dev/null
+++ b/tracker/documentation-meta-attr.mdwn
@@ -0,0 +1,57 @@
+% Documentation of meta attribute list of hashes
+
+The commit "Feat. Plugin. Provide sets of meta keys for inclusion"
+provide documentation included literally here.
+
+Add further lists of meta keys to include (*hash_meta_keys*
+and *list_hash_meta_keys*), add them to the *list_meta* map in
+subroutine *htmlize* and provide them to *pagestate* *meta*.
+
+This makes available, e.g. the *reference* attribute in page
+templates.
+
+The commit require some explanation.
+
+Until now, meta attributes were available as
+
+ * Bolean meta (*bool_meta*)
+ * Scalar meta (*scalar_meta*)
+ * List meta (*list_meta*)
+
+All meta attributes in documents are provided as page template
+variables with a 'pandoc_'-prefix. On top of that, attributes listed
+in *scalar_meta_keys* are made available as regular template
+variables, without prefix.
+
+Lists are problematic. Pure lists are pushed with 'pandoc_' prefix,
+but they can not be used. The alternative would be via loops (see
+<https://metacpan.org/pod/HTML::Template#TMPL_LOOP>), but inside loops
+one need to call for a variable and the pushed attribute does not
+provide one.
+
+This commit properly makes available the *reference* attribute, which
+is of type list of associated list. This construct actually fully
+natural fulfil the limitations of lists. Template loops generate the
+items, whose values are available with keys as variable names:
+
+    ---
+    references:
+     - id: refone
+       title: Ref-MetaInlines-in-MetaList
+     - id: reftwo
+       title: Ref-MetaInlines-in-MetaList
+    ...
+
+Which is called like this:
+
+    <TMPL_IF REFERENCES>
+      <TMPL_LOOP REFERENCES>
+         <TMPL_VAR ID>
+         <TMPL_VAR TITLE>
+      </TMPL_LOOP>
+    </TMPL_IF>
+
+How is hacky. The items in *hash_meta_keys* and *list_hash_meta_keys*
+are added to *list_meta_keys* and undergo the list processing. The
+list processing contradictory adopted better for *list_hash_meta_keys*
+than for *list_meta_keys*.