FIRST RELEASE
-------------


This is the first 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.


INSTALLATION AND RUNNING THE DEMO
---------------------------------

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/.  Then go to the directory in which this
README file appears, and run demo.py.  (Windows XP users may find it's
best to do this in a "Command" window:

  prompt> python demo.py

)


Read demo.py to see what's going on in the demo.  Versavant.py
provides an API.  The demo.py 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?  WHAT ABOUT THE TMRM "ASSERTION MODEL"?
--------------------------------------------------------

The bad news is that the draft ISO Topic Maps Data Model (TMDM) is not
yet implemented as a TMA in Versavant-land.  And neither is the
"assertion model" proposed in earlier drafts of the Topic Maps
Reference Model (TMRM).  These are still early days for the Versavant
approach.  I'm hoping that there will be implementations soon for both
of them.  "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)
