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