summaryrefslogtreecommitdiffstats
path: root/tracker/attribute-author.mdwn
diff options
context:
space:
mode:
authorGustav Eek <gustav.eek@fripost.org>2019-12-14 23:30:16 +0100
committerGustav Eek <gustav.eek@fripost.org>2020-01-06 16:25:18 +0100
commit926db30b62cae327398e9971605051680710b21a (patch)
tree34d698504f50a4cc8d70e7d1c2d7d230aedf1e85 /tracker/attribute-author.mdwn
parent9b611caf3208ea05988f4d0bdeacac9eb0c0e59d (diff)
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.
Diffstat (limited to 'tracker/attribute-author.mdwn')
-rw-r--r--tracker/attribute-author.mdwn101
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.