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
|
= Developing imip-agent =
To start developing the imip-agent software further, first obtain the code
by following the advice on the [[../Downloads|downloads page]]. Obtaining
the code directly from the repository is advisable since any changes you
make can then be tracked and managed.
<<TableOfContents(2,3)>>
== Distribution Contents ==
The software distribution contains the following directories:
{{{#!table
'''Directory''' || '''Description'''
==
`conf`
|| Example configuration files (see the
.. [[../GettingStarted|getting started guide]] for details)
==
`docs`
|| Documentation, including these wiki pages
==
`htdocs`
|| Resources for the [[../CalendarManager|management interface]]
==
`imiptools`
|| A Python package providing mail handling and support for calendar
.. object processing
==
`imipweb`
|| A Python package providing Web-related functionality for the
.. [[../CalendarManager|management interface]]
==
`messages`
|| Localised messages for the [[../AgentPrograms|agent programs]] and
.. [[../CalendarManager|management interface]]
==
`tests`
|| A suite of tests used to verify the behaviour of the software
.. (see the [[../Testing|testing guide]])
==
`tools`
|| Tools for [[../Administration|administration]] (see also the
.. [[../GettingStarted|getting started guide]])
}}}
At the top level of the distribution, the following files are found:
{{{#!table
'''File''' || '''Description'''
==
`imip_person.py`
||<rowspan="3"> The main program files for the
.. [[../AgentPrograms|agent programs]]
==
`imip_person_outgoing.py`
==
`imip_resource.py`
==
`imip_manager.py`
|| The [[../CalendarManager|management interface]] main program file
==
`markup.py`
|| A Python library providing HTML generation support
==
`README.txt`
|| Some basic documentation
==
`vCalendar.py`
||<rowspan="3"> Handling of vCalendar and related data formats
==
`vContent.py`
==
`vRecurrence.py`
}}}
== Architectural Components ==
The principal components of the software architecture are described below.
=== vContent ===
The v-prefixed libraries are concerned with the basic interpretation of
calendar-related data. For the most part, these libraries should already
behave in a predictable and reliable fashion and should not need much
further development. There are perhaps some deficiencies in the
`vRecurrence` module that are described on the
[[../CalendaringSupport|calendaring standards page]].
It is not inconceivable that a `vCard` module be introduced in the future
to handle vCard data, thus enhancing the data about people within
imip-agent, perhaps also supporting mechanisms to obtain free/busy and
other information about scheduling participants.
=== imiptools ===
The bulk of the work done in imip-agent happens within `imiptools`. When
used from [[../AgentPrograms|agent programs]] launched by the mail system,
the different modules support the "handler" functionality that involves
obtaining information from calendar data, performing the necessary action
related to a scheduling method, and generating responses or notifications.
More details are given about these activities in the guide to
[[../IncomingMessages|incoming message handling]].
When used from the [[../CalendarManager|management interface]], the
modules support the Web-based functionality as a more general calendar
system client, typically handling a single calendar object at any given
time.
The `imiptools.stores` package provides the basis for calendar data
persistence. From the very start, the nature of data organisation for
calendar users was centred on the storage of each user's free/busy records,
since the priority was to generate such records from messages exchanged
over e-mail, and the use of plain text files was chosen as the simplest
and most transparent approach. Beyond this, the need to retain calendar
objects arose, and thus a [[../FilesystemUsage|filesystem-based approach]]
was cultivated to manage such data.
In the future, other persistence mechanisms could be supported. However,
aside from performance concerns around access to free/busy schedules,
there may be no urgent need to adopt relational database technologies,
particularly as each user's data should remain isolated from that of
other users, and thus the volumes of data should remain relatively small
if managed well enough.
=== imipweb ===
Most of the `imipweb` package is concerned with the display of calendar
information as Web pages and the handling of submitted data over the Web
as users interact with those Web pages. The `imip_manager.py` file is
deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it
acts as a simple "switch" that shows the appropriate kind of Web page (or
"view") depending on the requested URL, delegating to one of the modules
within the `imipweb` package to do so:
|| '''Module''' || '''View''' ||
|| `imipweb.calendar` || Calendar ||
|| `imipweb.event` || Individual events ||
|| `imipweb.profile` || User profile ||
A general `imipweb.resource` module supports the different views with
common functionality. Useful abstractions for period and date information
are provided in the `imipweb.data` module. The CGI interfacing is defined
in the `imipweb.env` module.
One of the most awkward aspects of providing a Web interface to events is
the need to provide a comprehensive enough representation of period data
as expressed in calendar objects that can be held in a form defined in a
Web page, interpreted by the program, written back to the form, all
without losing information.
== Localisation ==
The traditional [[https://www.gnu.org/s/gettext|gettext]] mechanisms for
translating labels, messages and other user-readable strings are employed
in the imip-agent code. Some tools have been provided to maintain this
localisation.
To extract "messages" from the code, run the `tools/i18n_messages.sh`
script:
{{{
tools/i18n_messages.sh
}}}
This produces a file called `imip-agent.pot` in the current directory,
and it also attempts to merge any new messages into the existing message
translations found in the `messages` directory. Such translation files
have the following form:
{{{
messages/xx_XX.imip-agent.po
}}}
Here, `xx` is usually an [[WikiPedia:ISO_639-1|ISO 639-1]] language code,
whereas `XX` is usually an [[WikiPedia:ISO_3166-1|ISO 3166-1]] country code.
Translators should inspect and edit their files in the `messages`
directory and then use the `tools/i18n_format.sh` script to generate the
translations that the software will use:
{{{
tools/i18n_format.sh
}}}
This installs the "compiled" translations into the `locale` directory in
a location of the following form:
{{{
locale/xx_XX/LC_MESSAGES/imip-agent.mo
}}}
The `tools/install.sh` script will copy the `locale` directory into the
installation location unless the `--no-locale-dir` option is given. This is
provided to allow any centrally-installed translations to take precedence
over any locally-available translations.
|
