--- /dev/null
+---
+title: 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.
--- /dev/null
+---
+title: 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>
+```
--- /dev/null
+---
+title: 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',
+);
+```
--- /dev/null
+---
+title: 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*.
--- /dev/null
+---
+title: 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*.
--- /dev/null
+---
+title: Done, tracker summary
+...
+
+[[!inline
+ sort="meta(title)"
+ pages="* and tagged(done) and !tracker/done and !tracker/index"
+ archive=yes
+]]
+
--- /dev/null
+---
+title: Tracker summary, open issues
+...
+
+These are open issues. See [[done]].
+
+[[!inline
+ sort="meta(title)"
+ pages="tracker/* and !tagged(done) and !tracker/done and !tracker/index"
+ archive=yes
+]]
+
--- /dev/null
+---
+title: 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.
+
+## Info
+
+Tags and labels are used to for many things, such as filtering for
+inline. The [tag directive][drtv:tag] is standard usage. Maintenance
+is through [tag plugin][pln:tag].
+
+[drtv:tag]: https://ikiwiki.info/ikiwiki/directive/tag/
+[pln:tag]: https://ikiwiki.info/ikiwiki/plugins/tag/
+
+## Progression notes
+
+Questions, which is execution order? If parsing with *htmlize* happens
+before, that should be a good start.
+
+Possible places for source code: */IkiWiki/Plugin/tag.pm*. After
+copying to local dir, and adding some debug code, this is snippet of
+output:
+
+
+```
+D: tag:import: Run.
+D: pandoc:import: Run.
+D: tag:getopt: Run.
+D: tag:checkconfig: Run.
+D: tag:preprocess_tag: Run for test, test and 0.
+D: tag:preprocess_tag: Run for test, test and 0.
+D: IkiWiki.pm:htmlize: Run for test, HASH(0x563f41723878),
+D: pandoc:htmlize: Run for test
+D: pandoc:htmlize: Pandoc command: pandoc -f markdown -t json --email-obfuscation=none
+D: pandoc:htmlize: Pandoc command: pandoc -f json -thtml5 --email-obfuscation=none--filter=pandoc-citeproc
+D: pandoc:htmlize: Return.
+D: pandoc:pageactions: Run for test
+D: tag:pagetemplate: Run for test, test, page.
+D: pandoc:pagetemplate: Run for test and page
+```
+
+Thus it seems tag plugin gets all the execution before Pandoc plugin,
+for pulling all tag related info. This will be a hard one to break.
--- /dev/null
+---
+title: 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
+ ...
--- /dev/null
+---
+title: Verify sort title meta tag for page inlining
+titlesort: 01
+...
+
+Verify that the Pandoc YAML meta data is parsed and populated before
+the Ikiwiki *inline* directive is processed. That is that the
+*titlesort* field should be available.
projects / ikiwiki-pandoc.git / commitdiff