"Fossies" - the Fresh Open Source Software Archive

Member "absence-v2.1/README.txt" (15 Dec 2013, 13500 Bytes) of package /linux/www/web-absence-2.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2 This is the readme which accompanies my web-absence CGI application.
    3 --------------------------------------------------------------------
    4 
    5 The current version is 2.0.4
    6 
    7 The project home is located at:
    8 
    9 	http://www.unix-wissen.de/absence/
   10 
   11 
   12 DESCRIPTION
   13 ===========
   14 
   15 absence is a CGI-based tool for keeping track of people on a daily
   16 basis.  In principle it can be used to keep track of anything. For
   17 example it could be used to manage computer systems, or cars.
   18 
   19 The user interface revolves around a monthly display in the form of
   20 a matrix.  Days are represented by columns, and people (or objects)
   21 by rows.  This monthly unit I call a "month-image".  So-called "absences"
   22 are entered by clicking on the starting-day of the absence, and then
   23 entering the ending day, along with a short description.  If you
   24 select client-side image maps (as opposed to server-side), hovering
   25 over a particular absence will cause your browser to display the
   26 full text in the "short description" field as a so-called "tool-tip".
   27 
   28 Absence can now mark the current month and current day.  The current
   29 month is marked in a variety of ways: different (configurable) colors
   30 are used for the normal background, weekend background, calendar-week
   31 color, grid lines, and for the month-name and year text.  Additionally,
   32 a 2-pixel-wide frame is drawn around the whole month-image, also
   33 using a configurable color.  The colors are specified in
   34 AbsenceConfig.pm, or in your instance config file.  If you use the
   35 default colors supplied with absence, the current month normal
   36 background will be lighter, the weekend background lighter, the
   37 calendar-week lighter, and the grid lines darker.  The month and year
   38 text will be blue, and the frame will be white.
   39 
   40 How the current day is displayed is configurable: "fill" or "box".
   41 If "fill" is chosen, the column corresponding to the current day,
   42 will be colored using a configurable color.  If "box" is chosen,
   43 a frame 2 pixels wide will be drawn just inside the column using
   44 the same configurable color.
   45 
   46 There are different kinds of absence-types which are freely
   47 definable by the administrator.  Also arbitrary colors can be
   48 assigned to the various absence-types.
   49 
   50 An existing "absence" can be edited simply by clicking on it.
   51 
   52 Multiple separate "groups" are supported.
   53 
   54 As of version 1.7, absence supports access control.  Users are
   55 authenticated using a CGI form or via the standard http
   56 mechanism.  read, write, and admin permissions can be assigned
   57 on a group basis, and write permission can be assigned on a
   58 per-person basis.  Please see "README-AUTH.txt" for more information
   59 about authentication and authorization.
   60 
   61 Cookies are used to hold information about what was last
   62 displayed (and therefore what will be displayed the next time).
   63 
   64 JavaScript must be enabled for administrators, but is not
   65 absolutely necessary for users.
   66 
   67 Multiple-Reservation Mode
   68 =========================
   69 As of version 2.0 absence can be configured to support multiple
   70 reservations for the same person on the same day.  The various reservations
   71 that coincide with one another (i.e., have overlapping dates) must be display
   72 above or below one another.  A new characteristic, priority, determines how
   73 reservations are arranged graphically.  Priorities are whole numbers and
   74 go from 10 to 1, and from -1 to -10.  10 indicates that a reservation of
   75 that type should be placed as close to the top of the person-row as possible.
   76 It can only lose to another reservation of priority 10.  A priority of 9
   77 will be placed as close to the top as possible, but only after all priority
   78 10 reservations have been placed. The same method is used for the positive
   79 priorities.  The same method is used in reverse for negative priorities, i.e.,
   80 -10 means place as close to bottom as possible. -9 means place as close to
   81 bottom as possible, except for -10 priority reservations, et cetera.
   82 
   83 The above applies to all non-block type reservations, i.e., full, half, or
   84 quarter height.  Block reservations are always displayed using the current
   85 full height of the person-row, and can overlap, or underlap non-block
   86 reservations.  Positive priorities overlap, and negative underlap.  Thus,
   87 a block reservation of prio 10 would cover everything else, except another
   88 block reservation or prio 10.  A block reservation of -10 could be covered
   89 by everything else: non-block reservations and block reservations with all
   90 priorities except -10.
   91 
   92 Reservation types have another new characteristic: transparency, which
   93 allows the administrator to configure how transparent the displayed
   94 reservations are, that is, to what extent they allow what's underneath
   95 to show through.
   96 
   97 Block reservations could be used, for example, for holiday.
   98 
   99 
  100 Skipping non-workdays
  101 =====================
  102 As of v2.0 it is possible to configure reservations such that
  103 a reservation is interrupted by non-workdays, i.e., weekends and holidays.
  104 
  105 
  106 using Absence on Windoze
  107 ========================
  108 you're on your own.
  109 
  110 
  111 Character Sets
  112 ==============
  113 Absence stores its data as UNICODE.  This might sound promising, but
  114 there's a hitch: the GD fonts I use can only display ISO-8859-1 (Latin1).
  115 So if you want anything but the Latin1, you're pretty much out of luck.
  116 Sorry about that.  If you have a need for other character sets, let me
  117 know.  I won't promise that I'll support them, but if enough are interested,
  118 I'll have a look.
  119 
  120 Holiday descriptions that are imported are assumed either to be stored as
  121 UTF-8 or Latin1.  The same is true if you are migrating old (v1.8) Absence
  122 data.
  123 
  124 
  125 Prerequisites
  126 =============
  127 
  128 	- the PostgreSQL database, at least V8.X.X
  129 
  130 	- the perl DBI and DBD-PostgreSQL modules
  131 
  132 	- the GD library, at least V2.X
  133 		(see http://www.boutell.com/gd/)
  134 		prerequisites for libgd are:
  135 		- libpng (linked dynamically)
  136 		- libz
  137 		- libjpeg
  138 
  139 	- the Perl GD module, V2.X
  140 		(see http://www.cpan.org/modules/by-module/GD/)
  141 
  142 	- the Perl CGI module
  143 		(see http://www.cpan.org/modules/by-module/CGI/)
  144 
  145 	- the Perl CGI::Session module
  146 
  147 	- the Perl Digest::MD5 module.
  148 		(see http://www.cpan.org/modules/by-module/Digest/)
  149 
  150 	I'm currently using gd-2.0.36 and GD-2.41.
  151 
  152 LICENSE
  153 =======
  154 
  155     Absence is free software: you can redistribute it and/or modify
  156     it under the terms of the GNU General Public License as published by
  157     the Free Software Foundation, either version 3 of the License, or
  158     (at your option) any later version.
  159 
  160     Absence is distributed in the hope that it will be useful,
  161     but WITHOUT ANY WARRANTY; without even the implied warranty of
  162     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  163     GNU General Public License for more details.
  164 
  165     You should have received a copy of the GNU General Public License
  166     along with Absence.  If not, see <http://www.gnu.org/licenses/>.
  167 
  168 CHANGES
  169 =======
  170 
  171 2.1:
  172 
  173 - if "holiday_scheme" is set to "advanced", added country and region fields
  174   to the "Add Person" and "Modify Person" management forms. If the parameters
  175   "header_holiday_country" and "header_holiday_region" are set in
  176   AbsenceConfig.pm, they are used as the default values.
  177 
  178 - added ability to change username (when authentication is enabled)
  179 
  180 - changed logout mechanism to use javascript. This works for Firefox and IE,
  181   but not for Opera. Safari, Chrome et al not tested.
  182 
  183 - fixed a bug: after authenticating the string "Not Authenticated" was
  184   displayed in the upper ("control") frame.
  185 
  186 - added username to the "Logout" buttom, so user can see as whom he's
  187   authenticated
  188 
  189 2.0.4:
  190 
  191 - fixed a few minor bugs:
  192 	- content frame did not get reloaded after deleting an absence
  193 	- 'skip-non-workdays' attribute in absence types not being honored
  194 
  195 - added copyright and licensing information to relevant files
  196 
  197 2.0.3:
  198 
  199 - added ability to passed absence.pl a GET request to retrieve a page of
  200   month-images for a particular group, optionally starting at a
  201   particular month and for a specified number of months.  The GET
  202   parameters are "group_id", "start_month", "start_year", and "num_months".
  203 
  204 2.0.2:
  205 
  206 - added functionality to absence.pl to accept a HTTP GET request to
  207   display selected months for a particular group.
  208 
  209 2.0.1:
  210 
  211 - fixed bug when MULTI-RES mode enabled that caused reservation
  212   conflicts not to be discovered.
  213 
  214 2.0:
  215 
  216 tons of stuff:
  217 
  218 - no more flatfile databases.  Everything except some config params
  219   goes in a real database.
  220 
  221 - added functionality to allow multiple reservations (absences) on
  222   a particular day for a particular person.  Which reservation types
  223   are allowed to coincide with other types is configurable, as is the
  224   maximum height of a person-row.  Person-rows can be fixed or variable
  225   height, and if variable is configured, minimum and maximums can be
  226   specified.
  227 
  228 - reservation types now have a "height" characteristic.  They can be
  229   full, half, or quarter height, or "block" height. "full" height
  230   corresponds to the old reservation type; the text absence
  231   description is displayed on such reservations.  The "half" and
  232   "quarter" heights are one-half and one-quarter as high as "full", and
  233   cannot accept any text.  "full", "half" and "quarter" height reservations
  234   cannot overlap one another.  "block" height reservations are always the
  235   current entire height of the person-row, and overlap, or underlap
  236   (depending on priority) the full/half/quarter height reservations.
  237 
  238 - reservation types can be assigned prorities, which influence whether
  239   the corresponding reservations are displayed at the top, or the bottom
  240   of a person-row.
  241 
  242 - reservation types are now administered from the "manage" page.
  243 
  244 - several old bugs have been fixed, for example one involving incorrect
  245   display of the current month/day.
  246 
  247 - since holidays are now stored in the database, there is a holiday-management
  248   script.  People and Holidays can be associated with a particular country
  249   or region, thus allowing the per-person display of holidays, which
  250   might be useful if absence is used to manage virtual groups based about
  251   the world.
  252 
  253 - legacy (v1.8.x) flatfiles can be imported into the database during
  254   installation.
  255 
  256 - multiple instances are not currently supported.  If you want support, let
  257   me know.
  258 
  259 - reservation-types can be configured to skip non-workdays.
  260 
  261 1.8.1:
  262 
  263 - fixed bug which caused current month/day to be incorrectly displayed
  264 
  265 1.8:
  266 
  267 - if "absence-types.db" is edited, the legend image will automatically
  268   be regenerated.
  269 
  270 - options added to mark current month or day
  271 
  272 - fixed bug that caused wrong month-images to be displayed after
  273   modifying an absence if "Next"/"Previous" buttons were used
  274 
  275 - made all colors used configurable in AbsenceConfig.pm
  276 
  277 - added option to alternate background color in the people-rows
  278 
  279 - bank holidays can be indicated with a small or large mark.
  280 
  281 1.7.2:
  282 
  283 - fixed bug that caused incorrect group to be displayed when
  284   modifying a person when group_policy is set to "single".
  285 
  286 1.7.1:
  287 
  288 - fixed silly syntax error
  289 
  290 1.7:
  291 
  292 - authentication and authorization added.
  293   see README-AUTH.txt for details.  This may not sound like much,
  294   but it is.
  295 
  296 - lots of small improvements
  297 
  298 1.6.2:
  299 
  300 - repaired small bug which snuck in along with
  301   multi-group-membership.  The group-number was getting
  302   botched in "month_mod_times.db" which caused month-images
  303   to always be generated new, even if the cached versions
  304   were unchanged.
  305 
  306 - fixed month-modification-time database.  It was not working at
  307   all, causing month-images to always be re-created.
  308 
  309 1.6.1:
  310 
  311  mainly cosmetic stuff:
  312 
  313 - fixed the handling of conflicts when two users are
  314   modifying/deleting the same entity. (reservation/group/person).
  315   The scripts would exit with die(), causing a server error
  316   (but not necessarily a data-inconsistency).  Now such
  317   situations are recognized and an appropriate error-message
  318   is displayed.
  319 
  320 - sorted groups and people alphabetically in management page.
  321 
  322 - added more information about reservation conflicts
  323 
  324 - other stuff
  325 
  326 1.6:
  327 
  328 - users can be members of multiple groups (if so configured)
  329 
  330 - various bug fixes and minor improvements:
  331 	logging improved
  332 	added JavaScript to auto-submit when group is chosen
  333 	logging improved
  334 	db-file handling a bit safer
  335 	bank-holiday label configurable
  336 	when CW-bar is only one day long, CW-number is not printed
  337 	cookie-handling improved (simplified)
  338 	other stuff I can't remember
  339 
  340 1.5:
  341 
  342 - added support for multiple "instances" of absence which all use the
  343   same Perl scripts and modules.  This will not work on windoze/IIS.
  344   See windoze notes.
  345 
  346 - added a comprehensive installation script, "install.pl"
  347 
  348 - documented all modules and scripts.
  349 
  350 1.4c:
  351 
  352 - added windoze info to Readme.txt.
  353 - added "binmode()" statements to "AbsenceImage.pm" for stoopid windoze.
  354 - added comments to "AbsenceConfig.pm" for windoze users.
  355 
  356 1.4b:
  357 
  358 - the wrong "index.html" file was included in the 1.4 and 1.4a kit.
  359 
  360 1.4a:
  361 
  362 - a configuration option was added for the cookie domain, which had been
  363   hard-coded into 'absence.pl' :(.
  364 
  365 - An error message is now printed if a user who has disallowed cookies
  366    tries to use the "Next" or "Previous" buttons.
  367 
  368 1.4:
  369 
  370 - the broken URLS produced in v1.3 have been fixed.  v1.3 only worked if
  371   the browser did *not* fix the broken URLS.  Specifically, targets of the
  372   month-images were in the form:
  373 
  374 	"/path/absence-click.pl?G-M/YYYY"
  375 
  376   The browser then appended "?<x-coord>,<y-coord>" to the end.
  377 
  378 - either client-side or server-side image maps can be used.  The client-side
  379   map option is new.
  380 
  381 - cookie administration was cleaned up an iota.