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.

9 files changed, 294 insertions, 0 deletions

diff --git a/issues.mdwn b/issues.mdwn
new file mode 100644
index 0000000..bedfee5
--- /dev/null
+++ b/issues.mdwn
@@ -0,0 +1,33 @@
+% Issues of the Pandoc plugin
+
+Things how they should work
+
+[[!toc]]
+
+# Support of complex meta structures
+
+[[!inline pages="tracker/parse-complex-structures.mdwn"]]
+
+# Documentation of meta attribute list of hashes
+
+[[!inline pages="tracker/documentation-meta-attr"]]
+
+# Deal with author field
+
+[[!inline pages="tracker/attribute-author"]]
+
+# Deal with meta *list* attributes
+
+[[!inline pages="tracker/attribute-lists"]]
+
+# Deal with meta attributes *hash*
+
+[[!inline pages="tracker/attribute-hashes"]]
+
+# Handle block as scalar
+
+[[!inline pages="tracker/attributes-blocks-scalars"]]
+
+# Make tags available
+
+[[!inline pages="tracker/meta-tags"]]
diff --git a/tracker.mdwn b/tracker.mdwn
new file mode 100644
index 0000000..bfbf1cc
--- /dev/null
+++ b/tracker.mdwn
@@ -0,0 +1,17 @@
+% Tracker summary
+
+# Remaining
+
+[[!inline
+  sort="meta(title)"
+  pages="tracker/* and !tagged(done) and !tracker/done"
+  archive=yes
+]]
+
+# Done
+
+[[!inline
+  sort="meta(title)"
+  pages="tracker/* and tagged(done) and !tracker/done"
+  archive=yes
+]]
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.
diff --git a/tracker/attribute-hashes.mdwn b/tracker/attribute-hashes.mdwn
new file mode 100644
index 0000000..fa6286d
--- /dev/null
+++ b/tracker/attribute-hashes.mdwn
@@ -0,0 +1,28 @@
+% Deal with meta attributes *hash*
+
+The structure of *hash* (*MetaMap* with keys pointing at
+*MetaInlines*) has similar issues as other YAMLE meta data block
+cases. Example:
+
+```
+---
+experiment:
+ key_first: Värde
+ key_second: värde
+...
+```
+
+Solution is as always to transform to list of hash, that is wrap into
+a list. Access then comes via loop template construct. The loop will
+always undergo one iteration. Implicitly it will create a
+scope. Example:
+
+```
+<TMPL_IF EXPERIMENT>
+  <TMPL_LOOP EXPERIMENT>
+     Knowing that ther will only be one revolution one can be sloppy with
+     <TMPL_VAR KEY_FIRST> and
+     <TMPL_VAR KEY_SECOND> contents.
+  </TMPL_LOOP>
+</TMPL_IF>
+```
diff --git a/tracker/attribute-lists.mdwn b/tracker/attribute-lists.mdwn
new file mode 100644
index 0000000..b95118d
--- /dev/null
+++ b/tracker/attribute-lists.mdwn
@@ -0,0 +1,17 @@
+% Deal with meta *list* attributes
+
+For reasons presented meta lists are not working in page templates
+(see above, "meta attribute list of hashes").
+
+Suggestion is to always transform them to list of hashes with a
+default key (e.g. 'name'). That would be in accordance to "Deal with
+author field" above.
+
+Configuration would be:
+
+```
+my %list_meta_keys = (
+    author => 'name',
+    bibliography => 'path',
+);
+```
diff --git a/tracker/attributes-blocks-scalars.mdwn b/tracker/attributes-blocks-scalars.mdwn
new file mode 100644
index 0000000..a36c0ce
--- /dev/null
+++ b/tracker/attributes-blocks-scalars.mdwn
@@ -0,0 +1,15 @@
+% Handle block as scalar
+
+This one should be simple. Make available blocs (*MetaBlock* with one
+*Plain*) as scalar. Example
+
+```
+---
+abstract: |
+  tillagd i dokument arg-for-fripost
+
+  med flera stycken
+...
+```
+
+This should be handled in *unwrap_c*.
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*.
diff --git a/tracker/meta-tags.mdwn b/tracker/meta-tags.mdwn
new file mode 100644
index 0000000..e5be776
--- /dev/null
+++ b/tracker/meta-tags.mdwn
@@ -0,0 +1,4 @@
+% Make tags available
+
+This is the difficultmost. Collect YAML meta block *tag* and *tags*
+fields (as scalars or lists) and amend to the mainline tag work.
diff --git a/tracker/parse-complex-structures.mdwn b/tracker/parse-complex-structures.mdwn
new file mode 100644
index 0000000..0dfac34
--- /dev/null
+++ b/tracker/parse-complex-structures.mdwn
@@ -0,0 +1,22 @@
+% Support of complex meta structures
+
+In Plugin, add support in *unwrap_c* for support of the structure:
+*MetaList* with 2 x *MetaMap* with keys pointing to *MetaInlines*:
+
+    ---
+    references:
+     - id: refone
+       title: Ref-MetaInlines-in-MetaList
+     - id: reftwo
+       title: Ref-MetaInlines-in-MetaList
+    ...
+
+Actually it sounds complex but this fix should also be needed for the
+simpler example of *MetaMap* with keys pointing at *MetaInlines*:
+
+    ---
+    experiment:
+     key_first: Värde
+     key_second: värde
+    ...
+