ossp-pkg/as/as-gui/as-events.pod
##
## OSSP asgui - Accounting system graphical user interface
## Copyright (c) 2002-2004 The OSSP Project (http://www.ossp.org/)
## Copyright (c) 2002-2004 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2002-2004 Michael Schloh von Bennewitz <michael@schloh.com>
## Copyright (c) 2002-2004 Cable & Wireless Telecommunications Services GmbH
##
## This file is part of OSSP asgui, an accounting system graphical user
## interface which can be found at http://www.ossp.org/pkg/tool/asgui/.
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
## as-events.pod: Plain old documentation file
##
=pod
=head1 NAME
B<as-events> - accounting system events document format
=head1 DESCRIPTION
The B<as-gui> application takes input from the user and may store its data to
a file on the local filesystem. Among other functions, a user can enter time,
amounts, remarks, and other values. This data tuple is termed an I<event>, and
may either be transmitted to a B<AS> server or stored to a local file. Should
it be stored to a local file, the file name is arbitrary and is shown in the
title bar of B<as-gui>. Typically, the file is called F<events.as>. In most
cases the postfix B<.as> is appended to the file name, although this behaviour
can be turned on or off through the user preferences.
=head1 FILE FORMAT
The B<as-events> file contains ASCII text. The first line consists of an
identifier to associate the file type and version. Following text may contain
white space, comments, and data tuples.
=head1 GRAMMAR
B<events.as> ::= B<eventsid> B<tuplelist>
B<eventsid> ::= "%!AS-EVENTS-" [0-9] '.' [0-9]
B<tuplelist> ::= B<tuplelist> | B<tuple> | B<comment> | EMPTY
B<tuple> ::= B<user> B<uuid> B<crc> B<revision> B<date> B<begin> B<end> B<amount> B<account> B<remark>
B<comment> ::= ($#.*)
(* user field *)
B<user> ::= [a-zA-Z][a-zA-Z0-9]+
(* uuid field *)
B<uuid> ::= B<hexoctet> '-' B<hexquartet> '-' B<hexquartet> '-' B<hexquartet> '-' B<hextwelvetet>
(* crc field *)
B<crc> ::= B<hexoctet>
B<hextwelvetet> ::= B<hexoctet> | B<hexquartet>
B<hexoctet> ::= B<hexquartet> | B<hexquartet>
B<hexquartet> ::= B<hexdigit> | B<hexdigit> | B<hexdigit> | B<hexdigit>
B<hexdigit> ::= B<a-zA-Z0-9>
(* revision field *)
B<revision> ::= [0-9]
(* date field *)
B<date> ::= [0-9][0-9][0-9][0-9] '-' [01][0-9] '-' [0123][0-9]
(* time fields *)
B<begin> ::= B<timeval>
B<end> ::= B<endval>
B<amount> ::= B<timeval>
B<timeval> ::= B<hourval> ':' B<minuteval>
B<endval> ::= B<hourinc> ':' B<minuteval>
B<hourval> ::= [01][0-9]
B<hourinc> ::= B<hourval> | 2[0-4]
B<minval> ::= [0-5][0-9]
(* account field *)
B<account> ::= B<account> | B<accpart>
B<accpart> ::= B<accsep> B<acctext>
B<accsep> ::= '/'
B<acctext> ::= [a-zA-Z0-9_-]*
(* remark field *)
B<remark> ::= '"' .* '"'
=head1 EXAMPLE
A typical B<as-events> file might look like this:
%!AS-EVENTS-0.6
harvey 0ccf1d42-743b-43df-9b5d-202451b3c26f e8f212b6 0 2002-09-30 00:00 00:00 02:00 /it/development/meeting/weekly "Code review"
harvey 9c497382-ae88-4a1a-91b5-202451b3c26f c8637e9a 0 2002-09-30 00:00 00:00 00:30 /it/common/office/communication "Conference call"
harvey e230eae7-367f-4c35-bee1-202451b3c26f 02cb1abb 0 2002-09-30 00:00 00:00 00:30 /sales/travel/customer "Simontech visit"
=head1 SEE ALSO
as-gui(1),
as-gui.conf(5),
as-accounts(5),
=cut
