Tracker. Collect issues and ideas in tracker

Collect a broad series of possible improvements to Pandoc Ikiwiki
plugin management of meta block attributes. The issues are best
consumed via the collection page: *issues.mdwn*. Also main tracker
document added.

1 files changed, 101 insertions, 0 deletions

diff --git a/tracker/attribute-author.mdwn b/tracker/attribute-author.mdwn
new file mode 100644
index 0000000..9eb3290
--- /dev/null
+++ b/tracker/attribute-author.mdwn
@@ -0,0 +1,101 @@
+% Deal with author field
+
+In YAML meta data blocks, *author* can be provide provided in three
+structres. calls for some flexibility and compromises on provisioning
+for Ikiwiki page templates.
+
+## Author field in Pandoc
+
+Simplest version is *scalar* (*MetaInlines*). These are equivalent:
+
+    % title
+    % author
+    % date
+
+and
+
+    ---
+    title: title
+    author: author
+    date: date
+    ...
+
+Second is as *list* (*MetaList* of *MetaInline*). On the topic of that
+"YAML escaping rules must be followed", this is an example Pandoc
+documentation:
+
+    ---
+    title:  'This is the title: it contains a colon'
+    author:
+    - Author One
+    - Author Two
+    tags: [nothing, nothingness]
+    abstract: |
+      This is the abstract.
+
+      It consists of two paragraphs.
+    ...
+
+Third version is *list of hash* (*MetaList* of *MetaMap* with keys to
+*MetaInlines*). Further down we read that "[v]ariables can contain
+arbitrary YAML structures[.] ... The following combination, for
+example, would add an affiliation to the author if one is given:"
+
+     ---
+     title: The document title
+     author:
+     - name: Author One
+       affiliation: University of Somewhere
+     - name: Author Two
+       affiliation: University of Nowhere
+     ...
+
+"To use the structured authors in the example above, you would need a
+custom template:"
+
+     $for(author)$
+     $if(author.name)$
+     $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
+     $else$
+     $author$
+     $endif$
+     $endfor$
+
+## Our Pandoc Ikiwiki plugin as of today
+
+The *author* attribute affects four *pagestate* and *template* meta
+attributes: *author*, *num_autors*, *pandoc_author*, and
+*pandoc_primary_author*:
+
+ * *pandoc_author*: list of all author items as elements
+ * *num_authors*: length of that list
+ * *author*: scalar single string with authors concatenated
+ * *pandoc_primary_author*: Content of the first item in the list
+
+A YAML meta block field will overwrite fields provided as ikiwiki meta
+declarations:
+
+    \[[!meta author="Wallraff"]]
+
+This holds for first and secon cases of structure version above. Third
+version is not supported.
+
+Two Problems. First, the third version will cause *author* field to
+fail: *author* is not pupulated. Second, List case is not usable,
+because of how template loop structure works. (see above, "meta
+attribute list of hashes").
+
+## Suggestion to solution
+
+Suggested outcome is very similar as  Always populate according to this:
+
+ * *pandoc_author*: list of hashes with 'name' as default key
+ * *num_authors*: length of that list
+ * *author*: scalar single string with authors concatenated
+ * *pandoc_primary_author*: Content of the first item in the list
+
+The third *list of hash* case is obvious, since it follow close the
+suggested structure. Just the composition of *author* need some
+polishing. The second *list* case need transformation of list to *list
+of hash* with 'name' as key. The third *scalar* case also calls for a
+transformation to list of hash same way.