####################################
cvsRevision = "$Revision: 1.5 $" ##
####################################


THIRD RELEASE: Versavant revision 1.31, 17 July 2005
--------------


This is the third release of the versavant.py implementation of the
"Versavant Disclosure Discipline" for disclosing Topic Map
Applications (TMAs).  It is released under a "release early, release
often" policy.  Please expect bugs and rough edges, and please report
them to me.


WHAT'S NEW IN THIS RELEASE
--------------------------

* Added 3 more "Subject Map Pattern" assertion models, to the existing
  BigAssert model.  All four consider assertions to be reciprocal, and
  all have distinct named roles.  All assume that the role players are
  reified.  All have conferral rules that read the other three and add
  their perspectives to the subjects (i.e., add properties and proxies
  as necessary).  To the extent possible, all their subjects' proxies
  merge.  All are demonstrated in versavant/PARK/parkdemo.py.

  - BigAssert (the implementation and helpful diagrams are in
    versavant/Lib/BIGASSERT) reifies everything in sight: the
    relationship itself (the reified as an "A-proxy"), the type of the
    relationship ("T-proxy"), the roles of the relationship
    ("R-proxies"), and the castings ("C-proxies") (the "role player
    *seen as* playing the role).
    
  - TRA_assert (the implementation and helpful diagrams are in
    versavant/Lib/TRA_assert) is like BigAssert but it doesn't reify
    castings.

  - A_assert (the implementation and helpful diagrams are in
    versavant/Lib/A_assert) is like TRA_assert but it doesn't
    reify the roles or the relationship type.  It only reifies
    the relationship itself.  There are role names, but no
    proxies for the roles.

  - U_assert (the implementation and helpful diagrams are in
    versavant/Lib/A_assert) doesn't reify anything.  Instead, there
    are 6 non-SIP properties added to each role player.  These let you
    look up the other role players in terms of the roles being played
    by the roleplayer whose proxy you're standing at, or by the roles
    that the other role players play, or by the proxyIds of the other
    role players. 

* Bug fixes.

* Added some protective code to prevent implementers from doing some
  silly things which I recently did myself.


CHANGES COMING
--------------

Big ISO/IEC JTC1/SC34/WG3 meeting coming up in Montreal, just before
the Extreme Markup Languages conference.  The T+ model is being
integrated with the Topic Maps Reference Model.


INSTALLATION AND RUNNING THE DEMOS
----------------------------------

To see the software work, first install Python 2.4 (if you don't
already have it), which can be downloaded from
http://www.python.org/2.4.1/.  

Presumably, you have already unzipped the release, or you wouldn't
be reading this file.

Wherever you unzipped this file, there is now a "versavant" directory.
You need to make the path to that directory part of your PYTHONPATH
environment variable's value.  In Windows XP, you can create this
environment variable as follows:

  (1) Get to the "Control Panel" - it's probably on your Start menu.

  (2) If you see "Pick a Category", click "Switch to Classic View"

  (3) Click on "System".  This causes a "System Properties" pane to appear.

  (4) Click the "Advanced" tab.

  (5) Near the bottom of the pane, click on "Environment Variables".
      This causes an "Environment Variables" pane to appear.

  (6) click "New".  This opens a "New System Variable" pane or a
      "New User Variable" pane, depending on which "New" you clicked.
      From Python's perspective, it doesn't matter which one you chose.

  (7) On the "New System Variable" pane, at "Variable name:", enter
      "PYTHONPATH" (but don't use quotes).

  (8) On the same pane, at "Variable value:" enter the path to your
      versavant directory, wherever you unzipped it.  For example:
      "C:\versavant\" (don't use quotes)

  (9) click OK on the "New System Variable" pane.

 (10) click OK on the "Environment Variables" pane.

 (11) click OK on the "System Properties" pane.

 (12) close the Control Panel pane.

Then go to the versavant directory in which this README file appears,
and run demo.py.  Windows XP users may find it's easiest to do this
in a "Command" window, as follows:

  prompt> cd versavant
  prompt> python demo.py

Or, to run the bare-bones demo:

  prompt> cd versavant/PLD
  prompt> python pld.py

Or, to run the multiple assertion-models demo

  prompt> cd versavant/PARK
  prompt> python parkdemo.py


Read the demo programs and their associated opt.py ("opt" is an
acronym for "original population task") files to see what's going on.
Versavant.py provides an API.  Each demo program exercises some of
that API, and contains lots of informative commentary.

I have tested the software only under Linux, Windows XP, and Windows
98/ME.  If you attempt to run it on other platforms, I would like to
know what happens.


WHAT'S IT ALL ABOUT?
--------------------

The Versavant software is a tool for topic mapping that takes the view
that the ISO draft "Topic Maps Data Model (TMDM)" notion of what a
topic map is (Topics, Associations, Occurrences, the "TAO of topic
maps") is only one of an unbounded number and variety of possible
"Topic Map Applications (TMAs)".  The idea is that every TMA should be
able to work alongside every other TMA, and that it should be easy and
convenient for different TMAs to take advantage of information
expressed in the terms of other TMAs, in order to approach the goal of
having a single "place" for each subject, where everything known about
that subject is directly accessible.

The idea is also that each TMA needs to be free to have its own
notions of how to talk about various subjects, just as human
vocabularies and syntaxes, both formal and informal, always do.  To
speak is often necessarily to invent a manner of speaking; I believe
that's why natural languages mutate constantly, and why new formal
languages are invented every day.  Given almost any subject, there are
many contexts within which that subject can be identified, and many
different ways of identifying it and referring to it.


WHAT ABOUT TMDM?
----------------

The bad news is that the draft ISO Topic Maps Data Model (TMDM) is not
yet implemented as a TMA in Versavant-land.  I'm hoping that there
will be implementations soon.  "Release early, release often".

The good news is that, with this Versavant software, it's surprisingly
easy to implement a TMA.  Moreover, to implement a Versavant TMA is to
make a rigorous formal disclosure of it that anyone else can use in
the context of any topic map.  Indeed, this Versavant implementaiton
embeds all the TMAs that govern a topic map in the interchangeable XML
form of that topic map, when it is exported as an XML document.  If
you receive a Versavant topic map, you are in a very good position to
exploit that topic map, to merge it with others, and even to maintain
it without damaging its logical integrity or internal consistency.
Versavant's XML topic maps are an interesting variety of "smart
content".  They are radically self-describing.


"VERSAVANT DISCLOSURE DISCIPLINE"
---------------------------------

In the draft ISO 13250-5 "Topic Maps Reference Model"
(http://www.isotopicmaps.org/TMRM/TMRM-latest.html), a topic map is a
set of "subject proxies".

  (The more-general term "subject proxy" was adopted in order to avoid
  having to use the overloaded term "topic", which in XTM is an XML
  element type, and in TMDM is an Infoset information item.  In the
  Topic Maps Reference Model, both kinds of "topic" are seen as ways
  of interchanging and/or implementing subject proxies.)

Each subject proxy is a proxy for a single subject of conversation.
Each subject proxy is a set of one or more properties.  At least one
of the properties must be a "subject identity property (SIP)".  The
SIP(s) is/are used to determine whether two proxies have the same
subject, and should therefore be merged, so that the achievement of
the goal of all topic mapping -- the goal of "one proxy per subject"
-- is facilitated.  The nature of that matching process, and of the
merging process, and of the processes that support any querying
features, are all unconstrained by Versavant.

The Versavant Disclosure Discipline is not yet documented, except by
the versavant.py source code, and by the example TMAs loaded and used
in demo.py.  These demo TMAs can be found in the directories DemoTMA1,
DemoTMA2, and DemoTMA3.  Let me explain very briefly that, under the
Versavant Disclosure Discipline, TMA disclosures consist of

  (1) a set of functions for each property class, each of which is an
      instance of a Versavant Disclosure Discipline-defined function
      class, and

  (2) a set of functions that implement "conferral rules", if any,
      which collectively constitute the inference logic of the TMA.
      Basically, each conferral rule is triggered by something in the
      topic map that the TMA designer believed to imply either
      additional subjects, or additional properties of existing
      subjects, or both.  The operation of the conferral rule makes
      these additional subject proxies and properties explicit.  Like
      all other proxies, "conferred" proxies consist of properties, at
      least one of which is an SIP, etc.  Conferred properties can
      trigger conferral rules.

Each TMA is disclosed primarily by a "TMA configuration file".
Examples are the files called "tmaconf.xml" in each of the three
example TMA directories.  These files establish the names of all the
properties and conferral rules, and associate functions with each one.

Versavant provides comprehensive auditability of all of its merging,
conferral, and "original population task" processes.  When using the
Versavant Topic Map Inspection Tool (by calling the inspect()
function, as you will see in demo.py), to see how any property value
came into existence, go to the display page for the subject proxy in
which the property appears, and click on the upward-pointing gray
triangle that appears after the property class name.

CLOSING REMARKS
---------------

I'm hoping that it will turn out to be helpful to have interoperable
disclosures of how people can address the subjects that other people
are talking about, in the same terms that they are talking about them,
without everyone first having to agree on what those terms will be,
and without first requiring everyone to accept the limitations of any
pre-existing subject-addressing conventions.

After all, only a subset of the set of all possible subjects are
information objects, and I believe it's a mistake to pretend that all
subjects are information objects.  The purpose of versavant.py is to
demonstrate that there is a better way.  Instead of putting the
objects in control of the subjects, the Versavant approach gives
subjects the power of life and death over the objects that represent
them.


PLEA FOR HELP
-------------

I need help with this in all departments, technical, organizational,
promotional, etc.  I have a list of things that need doing, and
opportunities abound.  I also wouldn't mind being paid to participate
in the further development and scale-up of the approach, on any or all
platform(s).  There must be people who are ready to support the
enhancement of the exploitability of unconstrained human indexing
efforts in larger, more diverse, more comprehensive indexes, both
public and private.


HEARTFELT ACKNOWLEDGEMENTS
--------------------------

The intellectual contributions and encouragement of the co-editor of
the Topic Maps Reference Model, Patrick Durusau, are very gratefully
acknowledged.  I would also like to thank many others for their
staunch support and significant intellectual contributions (you know
who you are).  Special thanks, in both categories, are due to Jan
Algermissen and Sam Hunting; the four of us did the early heavy
lifting on the Reference Model.  Special thanks are due to Victoria
T. Newcomb and Peter Newcomb, who, among other things, invented the
"Whataburger Model" of Topic Maps.  Very special acknowledgements are
due to Michel Biezunski, without whose early sacrifices, steadfast
commitment, pioneering implementations, and practical applications,
there would be no Topic Maps phenomenon, and no Topic Maps standard,
either.  Finally, I would like to acknowledge the efforts of the whole
Topic Maps Community, including those who have labored long and hard
over XTM and TMDM, in Topicmaps.org, in the ISO context (and in the
contexts of various national standards bodies), in government, in
commercial enterprises, in academia, and in other open-source
projects.  We have certainly struggled with each other, and it has not
been easy or painless, but I think we are all winners, and it is an
honor to serve beside you in this important work.


Steve Newcomb
Co-editor, ISO 13250:2002 Topic Maps
Co-editor, draft ISO 13250-5 Topic Maps Reference Model

Implementer, owner, and open-source licensor of versavant.py (this software) (www.versavant.org)
Consultant, Coolheads Consulting (www.coolheads.com)
