                                   SYNOPSIS

Here I want to give you an idea of the layout of VASM and the relationships,
characteristics, and roles of its components. This document is accompanied by
a Graphviz dot source and PNG diagram which you should consult as you read.
For the sake of clarity, some relations have been omitted in the diagram.

                                 ARCHITECTURE

There are four distinct tiers in VASM:

Data Types
----------

Function: composition and abstraction of Perl's basic data types
Style: object-oriented

There is actually only one here (for now), VASM::Tree. It represents
hierarchal data in the form of hashes for a number of other components.

Foundation Classes
------------------

Function: representation of application-specific data types independent of UI
Style: object-oriented

Right now, we have:

VASM::Message - i18n message catalogs in Unicode
VASM::Error - subclass of VASM::Message for reporting errors
VASM::Action - file type and URI association preferences 
VASM::Menu - abstract definition of window manager menu
VASM::Menu::Translators - superclass of VASM::Menu used to write out menu
definitions for window managers

VASM::Message and VASM::Menu both inherit from VASM::Tree, whereas
VASM::Action's inner workings (a blessed arrayref) are so simple as to obviate
the need for any data type class. Foundation classes may include methods that
accept file handles, most likely referring to XML files, as arguments, but may
NOT know anything about the location of the files (c.f. 'Resource Modules'
below)

We want to use duck-typing liberally here, or at least get close. Do you want
to invent a new paradigm again and again? Of course not. For instance, all
foundation modules support Parse and Write methods, which each accept a single
IO::Handle for reading and writing XML files, respectively.

Resource Modules
----------------

Function: management of file system resources using the XDG Basedir standard
Style: procedural (no encapsulation of data is involved)

VASM::Resource is the core module, and, as I said, adheres to the XDG Basedir
standard. Configuration and data files will be found in the 'vasm' subdir of
both the global and user-specific XDG configuration directories; the resources
themselves are held in deeper hierarchies below this toplevel directory. The
file /usr/share/vasm/Common/Message/Message.xml, for instance, would refer to
the default message catalog, in the messages directory of a directory
allocated for resources shared in common amongst a number of facilities.
VASM::Resource also includes some generic primitives for creating personal
resource files.

VASM::Resource provides only basic functionality, which is differentiated by
sub-modules particular to a given type of resource, such as
VASM::Resource::Message. For all practical purposes, one could say that they
'inherit' from VASM::Resource. They are charged with the duties of dealing
with all file operations relevant to their resource type: specifically,
locating resource files and instantiating objects from them, as well as
handling of the file system in serializing objects. Again, the objects
themselves are responsible for writing to an IO::Handle, but VASM::Resource
sub-modules dig up the file itself, and are responsible for opening and
closing the filehandles.

Applications
------------

Role: UI bridge between lower tiers and users
Style: Procedural (again, no encapsulation really needed, and limited size of
code for a given app obviates concerns about scalability)

I gave up on the idea that I could somehow abstract the differences between
cdialog and Gtk2. They are two completely different UI models, and the result
would be a cluster. That being said, in cases where it is appropriate to write
an application for cdialog and Gtk2, the dialog version needs to be
sufficiently functional (i.e., not half-assed), although the Gtk2 version may
have extended functionality. For things like services configuration, it is of
special importance that the cdialog version work well. There are a few
important UI guidelines specific to either environment. In cdialog
applications, it must be possible to exit the program at any menu entry,
regardless of depth. Furthermore, all Gtk2 apps will be driven with the
GtkDialog widget. It's expedient to work with and its limitations are not
relevant here. Also, we still like the 'one window at a time' model from the
old VASM.

Finally, all VASM applications must be self-documenting. That is, when you
open them in cdialog or Gtk2 mode, the interface itself will present
complete instructions on the use of the application. In cdialog apps, this
means supplying the text for menus up top. In Gtk2, the convention I decided
on was to have a brief description of the application just above the dialog
buttons (at the bottom of the 'action area', in the Gtk2 parlance), which
expands into full documentation, using the Gtk2::Expander widget.

Overall, the applications need to work as expected, and be reasonably
maintainable. You can take more liberties with style here: cut and paste is
more acceptable, and you can get away with slightly less orthogonal code than
usual. Obviously, you can't hand in a gross hack, but I'm not expecting you to
stare at your code for an hour and think: "What would Alan C. Kay do?"

                                  STANDARDS

1) We use XML for storage of data intrinsically useful to VASM. XML::Parser
and XML::Writer make this very easy
2) VASM::Message catalogs must be written in Unicode UTF-8
3) VASM::Resource adheres to the XDG BaseDir standard

I decided to part with the Desktop Entry standard and gettext for a bunch of
reasons. It would be a PITA to explain it all. Some of them became invalid
over the development of the project, others still stand. Knowing that we have
an open codebase and certainly adhere to a few basic standards, let's not
split hairs about that issue.
