1\environment publicationsstyle
2
3\startcomponent publicationslua
4
5\startchapter[title=The \LUA\ view]
6
7The following is reserved for \LUA\ programmers.
8
9Because we manage data at the \LUA\ end it is tempting to access it there for
10other purposes. This is fine as long as you keep in mind that aspects of the
11implementation may change over time, although this is unlikely once the modules
12become stable.
13
14The entries are collected in datasets and each set has a unique name. In this
15document we have the set named \type {example}. A dataset table has several
16fields, and probably the one of most interest is the \type {luadata} field. Each
17entry in this table describes a publication. Take, for example \type
18{publications.datasets.example.luadata["article"]}:
19
20\startluacode
21 context.tocontext(publications.datasets.example.luadata["article"])
22\stopluacode
23
24There is a companion entry in the parallel \type {details} table,\\
25\type {publications.datasets.example.details["article"]}:
26
27\startluacode
28 context.tocontext(publications.datasets.example.details["article"])
29\stopluacode
30
31tracking further information derived from the publication entry and its use.
32
33You can loop over the entries using regular \LUA\ code combined with \MKIV\
34helpers:
35
36\startbuffer
37local dataset = publications.datasets.example
38
39context.starttabulate { "lll" }
40context.NC() context("tag")
41context.NC() context("short")
42context.NC() context("title")
43context.NC() context.NR()
44context.HL()
45for tag, entry in table.sortedhash(dataset.luadata) do
46 local detail = dataset.details[tag] or { }
47 context.NC() context.type(tag)
48 context.NC() context(detail.shorthash)
49 context.NC() context(entry.title)
50 context.NC() context.NR()
51end
52context.stoptabulate()
53\stopbuffer
54
55\typeLUAbuffer
56
57This results in:
58
59\ctxluabuffer
60
61Notice that the years in this example dataset given as \type {YYYY} are
62interpreted as if they were \index {9999}\type {9999}.
63
64You can manipulate a dataset after loading. Of course this assumes that you know
65what kind of content you have and what you need for rendering. As example we load
66a small dataset.
67
68\startbuffer
69\definebtxdataset[drumming]
70\usebtxdataset[drumming][mkivpublications.lua]
71\stopbuffer
72
73\cindex{definebtxdataset}
74\cindex{usebtxdataset}
75
76\typeTEXbuffer
77
78\getbuffer
79
80Because were going to do some \LUA, we could have loaded this dataset using:
81
82\startTEX
83\startluacode
84publications.load("drumming","mkiv-publications.lua","lua")
85\stopluacode
86\stopTEX
87
88The dataset has three entries:
89\startfootnote
90Gavin Harrison is in my (Hans) opinion one of the most creative, diverse and
91interesting drummers of our time. Its also fascinating to watch him play and a
92welcome distraction from writing code and manuals.
93\stopfootnote
94
95\typeLUAfile{mkivpublications.lua}
96
97As you can see, we can have a subtitle. As an exercise, we will combine the
98title and subtitle into one:
99
100\startbuffer
101\startluacode
102local luadata = publications.datasets.drumming.luadata
103
104for tag, entry in next, luadata do
105 if entry.subtitle then
106 if entry.title then
107 entry.title = entry.title .. ", " .. entry.subtitle
108 else
109 entry.title = entry.subtitle
110 end
111 entry.subtitle = nil
112 logs.report("btx",
113 "combining title and subtitle of entry tagged %a into %a",
114 tag,entry.title)
115 end
116end
117\stopluacode
118\stopbuffer
119
120\typeTEXbuffer \getbuffer
121
122As a hash comes in a different order each run (something that demands a lot of
123care in multipass workflows that save data in between), so it is probably
124better to use this instead:
125
126\startTEX
127\startluacode
128local ordered = publications.datasets.drumming.ordered
129
130for i=1,#ordered do
131 local entry = ordered[i]
132 if entry.subtitle then
133 if entry.title then
134 entry.title = entry.title .. ", " .. entry.subtitle
135 else
136 entry.title = entry.subtitle
137 end
138 entry.subtitle = nil
139 logs.report("btx",
140 "combining title and subtitle of entry tagged %a into %a",
141 entry.tag,entry.title)
142 end
143end
144\stopluacode
145\stopTEX
146
147This loops processes in the order of definition. Alternately, one can sort by
148\Index{tag}:
149
150\startTEX
151\startluacode
152local luadata = publications.datasets.drumming.luadata
153
154for tag, entry in table.sortedhash(luadata) do
155 if entry.subtitle then
156 if entry.title then
157 entry.title = entry.title .. ", " .. entry.subtitle
158 else
159 entry.title = entry.subtitle
160 end
161 entry.subtitle = nil
162 logs.report("btx",
163 "combining title and subtitle of entry tagged %a into %a",
164 entry.tag,entry.title)
165 end
166end
167\stopluacode
168\stopTEX
169
170The original data is stored in a \LUA\ table, hashed by tag. Starting with \LUA\ 5.2
171each run of \LUA\ gets a different ordering of such a hash. In older versions, when you
172looped over a hash, the order was undefined, but the same as long as you used the same
173binary. This had the advantage that successive runs, something we often have in document
174processing gave consistent results. In todays \LUA\ we need to do much more sorting of
175hashes before we loop, especially when we save multipass data. It is for this reason
176that the \XML\ tree is sorted by hash key by default. That way lookups (especially
177the first of a set) give consistent outcomes.
178
179We can now simply typeset the entries with:
180
181\cindex{definebtxrendering}
182\cindex{placebtxrendering}
183
184\startbuffer
185\definebtxrendering[drumming][group=examples,dataset=drumming]
186\placebtxrendering[drumming][method=dataset]
187\stopbuffer
188
189\typeTEXbuffer \getbuffer
190
191Because we just want to show the entries, and have no citations that force them
192to be shown, we have to set the \type {method} to \type {dataset}.
193
194Of course, none of these manipulations in \LUA\ are really necessary, as the
195rendering could be setup as:
196
197\cindex {btxfetch}
198\cindex {btxdoif}
199\cindex {btxcomma}
200\cindex {starttexdefinition}
201\cindex {stoptexdefinition}
202
203\startTEX
204\starttexdefinition btx:default:title
205 \btxfetch{author}
206 \btxdoif{subtitle} {
207 \btxcomma
208 \btxfetch{subtitle}
209 }
210\stoptexdefinition
211\stopTEX
212
213which is indeed the case in many of the styles (the \type {default} style uses
214\Cindex {btxcolon}). \startfootnote The specifications could be modified to use a
215parameter \type {inbetween={, }} for titles:subtitles that the user can easily
216setup as needed. But as such style questions are, in general, well defined in the
217specifications, this was not deemed necessary. \stopfootnote
218
219It is always a question of how much should be done in \LUA\ and how much should
220be done in \TEX. In the end, it is often a question of taste.
221
222\stopchapter
223
224\stopcomponent
225 |