# HG changeset patch # User Paul Boddie # Date 1446591373 -3600 # Node ID 00cdc167314c60986725df36f29e25bebfe1df55 # Parent 4dc13177072d77fbddb337905053d314e5c2a6cd Expanded the documentation around usage, administration, the management interface and preferences. diff -r 4dc13177072d -r 00cdc167314c docs/tools/profile_prefs.sh --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/tools/profile_prefs.sh Tue Nov 03 23:56:13 2015 +0100 @@ -0,0 +1,17 @@ +#!/bin/sh + +DIRNAME=`dirname $0` + +BASEDIR="$DIRNAME/../.." +PROFILE="$BASEDIR/imipweb/profile.py" + +# Match the prefs_table and swap the columns for a table. + +echo "|| '''Label''' || '''Setting''' ||" + + grep '^ \+("' "$PROFILE" \ +| sed 's/^ \+("\(.*\)".*, \+"\(.*\)"),$/|| \2 || [[..\/Preferences#\1|\1]] ||/' + +# Convert from... to... +# ("setting" , "label"), +# || label || [[../Preferences#setting|setting]] || diff -r 4dc13177072d -r 00cdc167314c docs/wiki/Administration --- a/docs/wiki/Administration Tue Nov 03 23:55:11 2015 +0100 +++ b/docs/wiki/Administration Tue Nov 03 23:56:13 2015 +0100 @@ -77,6 +77,14 @@ an administrator might initialise the common names of users by scripting changes to the `CN` file for each user, obtaining such names from some kind of database. +The permissions on any created files must be consistent with those defined when +configuring the [[../SystemUsers|system users]] for imip-agent. To reset file +permissions, use the appropriate tool script: + +{{{ +tools/fix.sh +}}} + == Excluding Users Entirely == Since the [[../AgentPrograms|agent programs]] are installed as part of the mail diff -r 4dc13177072d -r 00cdc167314c docs/wiki/CalendarManager --- a/docs/wiki/CalendarManager Tue Nov 03 23:55:11 2015 +0100 +++ b/docs/wiki/CalendarManager Tue Nov 03 23:56:13 2015 +0100 @@ -7,7 +7,7 @@ and to create events to be shared with others. The management interface is deployed according to the -[[../WebServerIntegration|Web server integration guide]], and if enabled will be +[[../WebServerIntegration|Web server integration guide]] and, if enabled, will be advertised in messages sent by imip-agent to users receiving calendar-related messages, with links being provided like this (subject to the configuration): @@ -17,3 +17,91 @@ Upon following such a link, users should be asked to log in. They should then be presented with the details of an event received via e-mail. + +== The Calendar View == + +The root resource of the management interface shows a simple calendar view for +the logged-in user. The following elements are displayed: + + * The name of the user, linking to a profile page + + * Any requests/invitations that require attention, linking to those items in the + calendar + + * The period being shown, along with controls to navigate forwards and backwards + in the calendar, and controls to show and hide empty days and busy periods + + * Participants for scheduling: details of other users whose schedules are shown + alongside the user's own schedule + + * The calendar itself, featuring events, and possibly featuring a column + containing requests and invitations + +Adding scheduling participants, specifying their e-mail address, results in a new +schedule column being added for each new participant in the calendar. When creating +an event, all scheduling participants are automatically added as attendees. + +The calendar is divided into days, and these are divided into periods depending on +the nature of any events that feature in the calendar. Days for which no events are +recorded are hidden by default; such days can be shown if desired. + +Whole days can be chosen by selecting day headings in the calendar. Similarly, +individual periods can be chosen either by selecting period headings along the side +of the calendar or by selecting cells in the calendar. Upon selecting periods, +controls will appear for the creation of a new event, and if all periods are +deselected, such controls will disappear. + +Events appear in the calendar as filled regions, and their labels correspond to the +summary information defined for each event. These labels link to the event details +unless a request has updated the event: in which case, the request label will link +to the updated event details. + +Requests/invitations appear alongside events in a separate column in the calendar, +and their label links to the details of the request (and thus updated event). Such +items disappear from the calendar once processed by the user. + +== The User Profile == + +Each user's profile details are presented in a table mostly corresponding to the +system's [[../Preferences|preferences]], with the most significant settings given +first. Many users will probably only want to change their participation in the +calendar system, their name, language or time zone, at least if the defaults +chosen for deployment are reasonable. + +The settings names correspond to the preferences as follows: + +## This is generated by the docs/tools/profile_prefs.sh script... + +|| '''Label''' || '''Setting''' || +|| Participate in the calendar system || [[../Preferences#participating|participating]] || +|| Your common name || [[../Preferences#CN|CN]] || +|| Language || [[../Preferences#LANG|LANG]] || +|| Time zone/regime || [[../Preferences#TZID|TZID]] || +|| How to present incoming calendar messages || [[../Preferences#incoming|incoming]] || +|| Share free/busy information || [[../Preferences#freebusy_sharing|freebusy_sharing]] || +|| Bundle free/busy details with messages || [[../Preferences#freebusy_bundling|freebusy_bundling]] || +|| Publish free/busy details via the Web || [[../Preferences#freebusy_publishing|freebusy_publishing]] || +|| Deliver details of received free/busy messages || [[../Preferences#freebusy_messages|freebusy_messages]] || +|| How to respond to messages adding events || [[../Preferences#add_method_response|add_method_response]] || +|| How to handle event refresh requests || [[../Preferences#event_refreshing|event_refreshing]] || +|| Recognise whom as a new organiser of an event? || [[../Preferences#organiser_replacement|organiser_replacement]] || + +== The Event View == + +The event view consists of the following elements: + + * Basic event details: summary, start and end dates/times, and the organiser + + * A list of attendees with controls to add and remove attendees, depending on + the role of the user + + * Some controls to change or process the event + +In addition, some other elements may appear in the event view: + + * Periods during which the event recurs + + * Counter-proposals sent by attendees to the organiser of an event, appearing + if the user has the organiser role, with controls to process these items + + * Periods that conflict with the event's own periods diff -r 4dc13177072d -r 00cdc167314c docs/wiki/Configuration --- a/docs/wiki/Configuration Tue Nov 03 23:55:11 2015 +0100 +++ b/docs/wiki/Configuration Tue Nov 03 23:56:13 2015 +0100 @@ -9,6 +9,11 @@ These files are by default installed into the `/etc/imip-agent` directory and they can be changed in that location once the system is installed. +{{{#!wiki tip +=== Text Encoding === +The textual encoding employed by the preferences files is UTF-8. +}}} + == System-Level and Tool Configuration == Given a choice of [[../SystemUsers|system users and groups]], the diff -r 4dc13177072d -r 00cdc167314c docs/wiki/FrontPage --- a/docs/wiki/FrontPage Tue Nov 03 23:55:11 2015 +0100 +++ b/docs/wiki/FrontPage Tue Nov 03 23:56:13 2015 +0100 @@ -2,7 +2,8 @@ {{{#!table [[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] || -[[#Deployment|Deployment]] || [[#Notes|Design/Implementation Notes]] || +[[#Deployment|Deployment]] || [[#Usage|Usage]] || +[[#Notes|Design/Implementation Notes]] || [[/CalendaringSupport|Support for Standards]] }}} @@ -144,6 +145,11 @@ * [[/CalendarManager|Calendar Management Interface]] * [[/FreeBusyPublishing|Free/Busy Publishing]] +<> +== Using the Software == + + * [[/Usage|Using imip-agent]] + <> == Design and Implementation Notes == diff -r 4dc13177072d -r 00cdc167314c docs/wiki/Usage --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Usage Tue Nov 03 23:56:13 2015 +0100 @@ -0,0 +1,22 @@ += Using imip-agent = + +As an e-mail user, imip-agent may already be working in the background on your +behalf as you send and receive messages, depending on how the software has been +[[../Configuration|configured]]. + +If you are already using a mail program with calendar support, imip-agent can +provide additional support for scheduling by +[[../FreeBusyPublishing|publishing free/busy information]] for other calendar +users. You can then configure your [[../MailClients|mail/calendar program]] to +download this information. + +If your mail program does not support calendar information or you are not +completely happy with it, imip-agent provides a simple Web-based calendar +[[../CalendarManager|management interface]] showing your schedule. Information +on this facility should be provided in messages sent by the calendar system +when events arrive. Otherwise, you can choose to visit the management +interface directly. + +The management interface provides a profile page through which you can change +your [[../Preferences|preferences]] for the software. Here, you can change +your level of participation in the calendar system and adjust its behaviour. diff -r 4dc13177072d -r 00cdc167314c imipweb/profile.py --- a/imipweb/profile.py Tue Nov 03 23:55:11 2015 +0100 +++ b/imipweb/profile.py Tue Nov 03 23:56:13 2015 +0100 @@ -26,6 +26,9 @@ "A request handler for the user profile page." # See: imiptools.config, imiptools.profile + # NOTE: This could be defined in another format and generated or computed + # NOTE: for this class and for the documentation. + # See: docs/tools/profile_prefs.sh pref_labels = [ ("participating" , "Participate in the calendar system"),