-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.tex
385 lines (306 loc) · 13.3 KB
/
index.tex
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
\input texrc
\title club3
\centerline{\url{https://github.com/ds26gte/club3}}
\centerline{\urlh{http://ds26gte.github.io}{Dorai Sitaram}}
\medskip
\noindent
club3 is a Common Lisp program that schedule a series of meetings of the
Toastmaster™
type fairly.
\beginsection Installation
Get club3 from GitHub:
\begintt
git clone https://github.com/ds26gte/club3
\endtt
This produces
a directory `club3`,
which contains a shell script called `club3`. Put a copy of or soft link to
`club3` in your `PATH`.
The subdirectory `lisp` contains several Lisp files, the main file
being `club3.lisp`. If you move `club3.lisp` to a different
location, you must ensure that all the other `.lisp` files in the
`lisp` subdirectory move with it, as code in `club3.lisp` assumes
that they are in the same directory as itself.
The script `club3` sets and uses an environment variable `CLUB3DIR` to
identify the directory containing `club3.lisp`. Change it to suit you.
The script `club3` also sets and uses an environment variable `LISP` to identify
your Common Lisp system. Change to suit you.
Optional: You may compile `club3.lisp` (using the Common Lisp function
`compile-file`). Only `club3.lisp` need be explicitly compiled — it will
take care of compiling the other `.lisp` files.
\beginsection Usage
In a directory that contains all the data relevant to your club, call
`club3` with the argument `schedules` or `profiles`.
The data in the current directory serves as input to both calls, and
influences the result. This input data consists of an init file
`club3rc.lisp` and a subdirectory `past-schedules` which contains the
scheduling history of the club. For an example, see
the directory `examples/articulators` in the distribution.
\beginsection Generating schedules
\begintt
% club3 schedules
\endtt
generates schedules. (I.e., type `club3 schedules` at your Unix
prompt `%`.)
(For convenience, the argument `schedules` can be dropped:
calling `club3` is equivalent to calling `club3 schedules`.)
The schedules consist of a `.txt` file for each date
in the calendar (see below), and an HTML file `new-schedules.html`
that lists the schedules as an easy-to-read and -print table.
For a saved example, see
{\tt examples/articulators/current-schedules.html} in the club3 distro.
The generated `.txt` files can be inserted into `past-schedules` (see
below) to influence the course of future schedules (created by future
calls to `club3 schedules`). Before putting a `.txt` file into
`past-schedules`, it is a good idea to edit this file by hand to ensure
that it accurately records the members who actually performed the roles
(since club members typically negotiate substitutions up to the very
last minute because of unforeseen circumstances).
\beginsection Generating profiles
\begintt
% club3 profiles
\endtt
generates member profiles in a subdirectory called `profiles`, browsable
via an `index.html` file.
Example: `examples/articulators/profiles/index.html` in the distro.
\beginsection Initialization
The init file `club3rc.lisp` is essential. At the very least, it must
use the operators `members`, `lineups`, and `calendar` to respectively list
the members in the club; the type of meeting lineups used; and the
calendar dates for which schedules are desired.
Other operators such as `availability`, `expertise`, `eagerness`,
`role-difficulty`, and `number-of-trials` are optional: However it is useful
to invoke some or all of them so that the generated schedules are both
equitable and feasible.
The operators `full-names`, `role-names`, and `club-name` help make the output
schedules more readable.
Example: `examples/articulators/club3rc.lisp` in the distro.
\beginsection Members
The operator `members` lists the members in the club, a symbol for each
member. E.g.,
\begintt
(members andrew brad charlie dan eileen fran george hilary ian judy
kim lori marcia nelson oliver prasad rick stephanie theresa
ulrich vanessa willy xavier yul zoe)
\endtt
\beginsection Lineups
The operator `lineups` introduces the various prescribed lineups for the
club’s meetings. Each lineup is a list whose first element is a keyword
describing the type of meeting, and whose second element is a list of
roles.
\begintt
(lineups (:default
(tm word joke poet speaker speaker speaker
ge eval eval eval topics)))
\endtt
Roles can repeat: the above lineup allows for three `speaker`s and three
`eval`s.
The first lineup is considered the default lineup (even if it wasn’t
explicitly named `:default`). `lineups` can take more arguments if different
lineups are possible (for different meetings).
\begintt
(lineups (:default ...)
(:topics-tuesday
(tm word joke poet speaker speaker ge eval eval topics)))
\endtt
This specifies a meeting of type `:topics-tuesday`, which differs from the
`:default` meeting in that its lineup has only two `speaker`s and two `eval`s.
(The purpose of this meeting is plausibly to allow more time for `topics`
than is possible in a `:default` meeting.)
A type of meeting called `:superset` may be optionally added. This
specifies the list of roles that will be specified in the HTML table
generated by `club3 schedules` for a sequence of meetings, which may be
of different type. The idea is to list all the roles possible in all
the meetings, and have the column for each meeting fill only the row
that is relevant to it.
\beginsection Calendar
The operator `calendar` contains a series of dates for which meetings need
to be scheduled. Each date is given as a dotted integer YYYY.MM.DD; thus,
2009.02.24 is 2009 Feb 24.
\begintt
(calendar 2009.03.03
2009.03.10)
\endtt
If the type of meeting to be held on a particular date differs from the
`:default` type of meeting, then the date is enclosed as the first element
in a list whose second element is the type of meeting. E.g.,
\begintt
(calendar 2009.03.03
(2009.03.10 :contest)
2009.03.17
2009.03.24
(2009.03.31 :skills-night)
(2009.04.07 :topics-tuesday))
\endtt
The type of meeting is typically one of the keywords introduced by the
`lineups` operator (see above). However, it can be anything. If it isn’t one
of the keywords introduced by `lineups`, then no schedule is presumed
for that date. (This is useful to mark certain dates for special
activities that do not require scheduling, or have been scheduled by
other means.)
\beginsection Availability
The `availability` operator contains exceptional information about the
temporal availability of the members. By default, members are assumed
to be always available. To override this for any member, that member’s
symbol is associated with an expression denoting
when that member is available.
Availability expressions are given in prefix notation using operators
such as `after`, `always`, `before`, `between`, `from`,
`on`, and `until` whose arguments
are dates or the results of other operations.
`and`, `not`, and `or` are also allowed, but can only operate on the results of
other operations (i.e., not directly on dates). [Use `on` if you find
yourself wanting to use `and`/`not`/`or` directly on dates. E.g.,
`(not (on 2009.03.17))`.]
Dates are either in YYYY.MM.DD format or the keyword
`:further-notice` (= $\infty$).
Examples:
\begintt
(availabilty (kim (not (between 2009.03.10 2009.03.21))))
\endtt
states that `kim` will not be available from March 3 to 21, 2009
(inclusive).
\begintt
(availability (kim ...)
(theresa (not (until :further-notice))))
\endtt
says that `theresa` will not be available until further notice.
\begintt
(availability (kim ...)
(theresa ...)
(kumaran (and (not (on 2009.02.24 2009.04.28
2009.05.26 2009.06.30))
(not (between 2009.03.10
2009.03.31)))))
\endtt
states that `kumaran` will not be available on Feb 24, April 28, May 26, and
June 30 of 2009; and also between March 10 and 31 of 2009.
\beginsection Role-difficulty
Using the `role-difficulty` operator, you can identify specific roles to
be either `:easy`, `:intermediate`, or `:hard`. By default, all roles are
considered to be `:easy`. Example entries:
\begintt
(role-difficulty (speaker :intermediate)
(eval :hard))
\endtt
\beginsection Expertise
By default, every member is considered to be capable of doing all and
only the `:easy` roles To modify this, use the `expertise` operator. Each
argument is a list whose first element is the member name and whose
subsequent elements are the additional roles they can tackle beyond the
`:easy` roles. E.g.,
\begintt
(expertise (rick topics eval))
\endtt
If you entered `:intermediate` or `:hard` instead of a role name, all roles
that are intermediate or hard, respectively, are intended.
\begintt
(expertise (rick ...)
(connie :intermediate))
\endtt
The keyword `:all` stands for {\em all} roles. Thus to encode the fact that
`bash` can do anything:
\begintt
(expertise (rick ...)
(connie ...)
(bash :all))
\endtt
You may also enter a list such as `(- speaker topics)` instead of a role.
This requests that the `speaker` and `topics` roles be removed from that
member’s expertise.
\begintt
(expertise (rick ...)
(connie ...)
(bash ...)
(judyk (- speaker topics)))
\endtt
\beginsection Eagerness
By default, all members are supposed to exhibit the same moderate level
of eagerness to be scheduled. However, using the `eagerness` operator,
you can add an eagerness level to a member. Each argument consists of
the member name followed by a number between 0 and 3 inclusive: 0 for
inactive; 1 for taking it slow; 2 for normal (the default); and 3 for
fast track. E.g.,
\begintt
(eagerness (joseph 3)
(judyk 1)
(theresa 0))
\endtt
states that `theresa` is inactive, `judyk` wants to take it slow, and `joseph`
wants the fast track.
\beginsection Number-of-trials
`club3` uses a system that ascribes demerits to each member for a role on
any day (based on history, availability, etc). Since a lineup is filled
in a certain order, earlier roles may beat out later roles in getting
their best-suited members, leading to overall higher demerits. `club3`
tries to counter this by picking among eligible members using an
geometrically decaying distribution among them, so a member with higher
demerits could still snag a role. `club3` then generates more, different
lineups, to see if another lineup with fewer overall demerits
materializes.
By default, `club3` generates 400 trial lineups for each meeting date, and
picks the best among them. `club3` output will also indicate the ordinal
`n` of the eventually picked lineup, so you get an idea if the number of
trials is reasonable. (If `n` is too close to 400, and the best lineup
was updated many times, perhaps more trials are needed.)
To change the number of trials, use the `number-of-trials` operator, e.g.,
\begintt
(number-of-trials 200)
\endtt
\beginsection Full-names
The symbol used for each member is typically capitalized when printing
out schedules or profiles; thus, `charlie` becomes “Charlie” and `marcia`
becomes “Marcia”. However, in certain cases, naive capitalization may
be inaccurate or unsightly. For instance, if there are several members
with the same (first) name, the `members` operator may have used an
initial to disambiguate, e.g., `judyk` and `judyp` for two different Judys.
To properly capitalize them in the output schedule (so the Judys don’t
judge you), use the `full-names` operator:
\begintt
(full-names (judyk "Judy K")
(judyp "Judy P"))
\endtt
You may add more complicated names:
\begintt
(full-names (judyk ...)
(judyp ...)
(kelvin "William Thomson, First Baron Kelvin"))
\endtt
For routine scheduling, however, a first name, sometimes enhanced with a
disambiguating initial, is usually
enough.
\beginsection Role-names
`lineups` uses abbreviated symbols for each role. When printing out the
schedule as an HTML file, the roles are capitalized, and if there are
multiple instances of a role in a meeting, each role instance gets a number suffix
(e.g., “Speaker \#2”). If you want the printed name for a role to be
different than the mere capitalization of the role symbol, you may use
the `role-names` operator, e.g.,
\begintt
(role-names (tm "Toastmaster")
(eval "Evaluator"))
\endtt
\beginsection Club-name
The name of the club is set using the operator `club-name`. This name is
used to title the schedules.
\begintt
(club-name "The Articulators")
\endtt
\beginsection History
The subdirectory `past-schedules` contains the schedules (the `.txt` files)
generated for previous calendars — i.e., by previous calls to `club3 schedules`. While optional, `past-schedules` is useful to maintain, as
it provides the historical information necessary to ensure that no
member is over- or underscheduled.
\beginsection System requirements
`club3` runs on any Common Lisp in a Unix-like environment, e.g.,
\urlh{http://common-lisp.net/project/armedbear}{ABCL},
\urlh{http://clisp.sf.net}{CLISP},
\urlh{http://ccl.clozure.com}{Clozure CL},
\urlh{http://cmucl.org}{CMUCL},
\urlh{https://github.com/jcbeaudoin/MKCL}{MKCL},
\urlh{http://ecls.sf.net}{ECL}, and
\urlh{http://sbcl.sf.net}{SBCL}.
(On Windows, you can get a Unix
environment via \urlh{http://cygwin.com}{Cygwin}, which also
provides CLISP.)
\bye