diff options
| -rw-r--r-- | issues.mdwn | 33 | ||||
| -rw-r--r-- | tracker.mdwn | 17 | ||||
| -rw-r--r-- | tracker/attribute-author.mdwn | 101 | ||||
| -rw-r--r-- | tracker/attribute-hashes.mdwn | 28 | ||||
| -rw-r--r-- | tracker/attribute-lists.mdwn | 17 | ||||
| -rw-r--r-- | tracker/attributes-blocks-scalars.mdwn | 15 | ||||
| -rw-r--r-- | tracker/documentation-meta-attr.mdwn | 57 | ||||
| -rw-r--r-- | tracker/meta-tags.mdwn | 4 | ||||
| -rw-r--r-- | tracker/parse-complex-structures.mdwn | 22 |
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 + ... + |