summaryrefslogtreecommitdiffstats
path: root/tracker/attribute-author.mdwn
blob: 9eb32900766ac9c7ddfd333b866c7b355c1f772c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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.