##
##  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