From: Gustav Eek Date: Mon, 6 Jan 2020 15:19:50 +0000 (+0100) Subject: Tracker. Add a bunch of inital todos to tracker X-Git-Url: https://git.g-eek.se/?a=commitdiff_plain;h=0f1c6c2087a5279ab5a3454a01a44aecaaa1b7c8;p=ikiwiki-pandoc.git Tracker. Add a bunch of inital todos to tracker --- diff --git a/tracker/attribute-author.md b/tracker/attribute-author.md new file mode 100644 index 0000000..952408d --- /dev/null +++ b/tracker/attribute-author.md @@ -0,0 +1,103 @@ +--- +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. diff --git a/tracker/attribute-hashes.md b/tracker/attribute-hashes.md new file mode 100644 index 0000000..3b0c094 --- /dev/null +++ b/tracker/attribute-hashes.md @@ -0,0 +1,30 @@ +--- +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: + +``` + + + Knowing that ther will only be one revolution one can be sloppy with + and + contents. + + +``` diff --git a/tracker/attribute-lists.md b/tracker/attribute-lists.md new file mode 100644 index 0000000..fe27f5a --- /dev/null +++ b/tracker/attribute-lists.md @@ -0,0 +1,19 @@ +--- +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', +); +``` diff --git a/tracker/attributes-blocks-scalars.md b/tracker/attributes-blocks-scalars.md new file mode 100644 index 0000000..843a1cf --- /dev/null +++ b/tracker/attributes-blocks-scalars.md @@ -0,0 +1,17 @@ +--- +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*. diff --git a/tracker/documentation-meta-attr.md b/tracker/documentation-meta-attr.md new file mode 100644 index 0000000..cba6f3a --- /dev/null +++ b/tracker/documentation-meta-attr.md @@ -0,0 +1,59 @@ +--- +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 +), 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: + + + + + + + + +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/done.md b/tracker/done.md new file mode 100644 index 0000000..1f7604f --- /dev/null +++ b/tracker/done.md @@ -0,0 +1,10 @@ +--- +title: Done, tracker summary +... + +[[!inline + sort="meta(title)" + pages="* and tagged(done) and !tracker/done and !tracker/index" + archive=yes +]] + diff --git a/tracker/index.md b/tracker/index.md new file mode 100644 index 0000000..703b8e1 --- /dev/null +++ b/tracker/index.md @@ -0,0 +1,12 @@ +--- +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 +]] + diff --git a/tracker/meta-tags.md b/tracker/meta-tags.md new file mode 100644 index 0000000..341038e --- /dev/null +++ b/tracker/meta-tags.md @@ -0,0 +1,45 @@ +--- +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. diff --git a/tracker/parse-complex-structures.md b/tracker/parse-complex-structures.md new file mode 100644 index 0000000..ee8ae87 --- /dev/null +++ b/tracker/parse-complex-structures.md @@ -0,0 +1,23 @@ +--- +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 + ... diff --git a/tracker/verify-inline-sort.md b/tracker/verify-inline-sort.md new file mode 100644 index 0000000..ac204ca --- /dev/null +++ b/tracker/verify-inline-sort.md @@ -0,0 +1,8 @@ +--- +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.