Matrix Public Net - Getting Started
===================================

After installing the binary program files you have to adjust the
preferences. You first need an identity on the Matrixpn to store your
published news. Then you also have to specify your friends and people
you trust in.


Using The Default Configuration
-------------------------------

The MPN components need several config/data-files in a specific
directory. On GNU/Linux systems they are located in '~/.matrix/'.

To get started I recommend to copy the preferences that come with the
source/binaries. Don't do this as root since you have to copy the files
to your user home directory.

When installing from the tar-ball or CVS, copy the 'startprefs'
folder: 'cp -r startprefs ~/.matrix'.

The Debian package installs these files in
'/usr/share/doc/matrixpn/examples/startprefs/'. So you need to do a:
'cp -r /usr/share/doc/matrixpn/examples/startprefs ~/.matrix'.


Configuring With Your Webbrowser
--------------------------------

When you have the required Webbrowser and Urlhandler installed (as 
the installation instructions say) you can open the
~/.matrix/prefs.xml file with the browser. Then follow the
instructions to create an identity and select friends. With this
interface you can also select more topics and languages you want to
use.


Configuring By Hand
-------------------

Most options can (by now) only be changed by changing the config-files
directly with a text-editor. So if you want a sophisticated
configuration or you don't have the required webbrowser the following
notes may help. 

With any webbrowser, go to the mpn-server http://matrix.wearlab.de
directly or to the project page at http://matrixpn.auriga.wearlab.de
for a list of servers.

When you do the registration or view any other information that you
can enter into the configuration of mpn you get xml-code snippets
displayed. These are for your prefs.xml file. Copy the snippets into
the root-node, before the last line: </matrix-private-prefs>.


Launching The Net
-----------------

Now your MPN node should be ready to be started. Therefore execute the
'fetchnews' program. If you want to see what it is doing, type:
'fetchnews -v'. Fetchnews will query your friends for new messages and
fetch them automatically. It then applies all rules specified in the
preferences and recommends the new messages to people that trust in
you.

To hear the audio messages, you have to enable the 'Matrix News
Plugin' in the effectplugins-section of your XMMS. Messages are only
played, when you are listening to anything, not when XMMS is stopped
or paused.

If you want to publish a message, use the 'greporter' program. It is
quite self-explanatory (I hope). Hit the record-button once to record
and then again to stop recording (only once again). It takes some time
for the button to pop out, but that is all right. The program encodes
the message in ogg-vorbis during that time. 


Testing
-------

To test your setup, it is a good idea to add yourself as a friend, so
you can hear your own messages. It takes several minutes for the
messages to travel through the net. 

The default-setup plays only important-marked messages as soon as they
arrive, so publish your tests with priority=important with the
greporter.


Troubleshooting / How It Works
------------------------------

If the XMMS-Plugin does not play the messages you expect, there are
several places where you can look for the message to figure out, where
it is stuck:

1. The greporter sends the message as a mime-encoded mail to the
   mpn-server. Use 'mailq' to see if the message got out of your
   computer or is stuck in the mail queue. Also edit the
   matrix-private-prefs/identity/remote/server_email entry in
   prefs.xml to have the message sent to your own email-address and
   see if it arrives. Your mailserver needs to be working correctly.

2. When the message arrives at the mpn-server and is processed
   correctly, the server adds an entry to a webpage. View this page
   with your browser, to see if the entry is there. Use the URL from
   the matrix-private-prefs/identity/person/home entry in the
   prefs.xml. Consider viewing the source of the page, because it
   is xml and not html.

3. Fetchnews should fetch this entry by itself (if you are your own
   friend). Run it as 'fetchnews -v' or even 'fetchnews -v -v' to make
   it verbose. When it got the message, you should find it in your
   news.xml-file. 

4. The Plugin looks for new entries in the news.xml-file, downloads
   the ogg-files and plays them, according to the instructions in the
   newsblocks (in prefs.xml). After playing the message is marked as
   xmms-played in the news.xml file and will not be played again.


MPN Default Config/Data-Files Overview 
--------------------------------------

There are plenty of config-files to adjust the behaviour of your
mpn-node:

prefs.xml:
	
	This is the central file to configure your MPN. Several other
	files are referenced from this one:

	prefs2html.xsl:

		This stylesheet is automatically used for viewing the
		prefs.xml file in a webbrowser.

	morse_matrix.ogg,
	morse_s.ogg,
	morse_end.ogg:

		These audio-files are played as intro, separator and
		ending of an instant MPN message.

	heiter_start.ogg,
	heiter_s.ogg,
	heiter_end.ogg:
	
		These audio-files are used for the newsblocks that are
		played every 30 minutes, by default. So you have
		different jingles for different kinds of messages.

	global.xsl:

		This stylesheet transforms every incoming
		news-message. If the weight of the incoming message is
		less than 0.2 it is discarded, otherwise it copies the
		message and adds a generic pong-tag. 

	f_Wx0.8.xsl:

		This stylesheet is applied to all incoming messages
		from friends, by default. It multiplies the weight of
		the message by 0.8. This way a message gets more and
		more unimportant or unbelievable as it passes from
		person to person. 

	f_Wx0.2_dontrec.xsl:

		The default stylesheet for messages from bots. It
		multiplies the bot-messages by 0.2 and prevents the
		message from being recommended to the persons that
		trust in you.

        instant.xsl:

		This stylesheet is used to decide which message is
		played at once (as soon as it is there). All other
		messages will be delayed for the
		every-30-minutes-newsblock. Messages with
		priority=important (3) go into the instant-newsblock,
		no matter what the weight is.


Received messages will also be stored together with the preferences:

news.xml:

	Contains all the message headers that are currently on your
	node. Incoming messages are added and expired messages are
	deleted automatically by the system. These stored headers are
	processed by the various .xsl config files to make the network
	very flexible.

	news2html.xml:

		You can view the news.xml file in your
		internet-browser via this stylesheet.

	content:

		This directory contains the latest played audio
		messages. The headers in the news.xml file reference
		these files. They are also automatically deleted when
		they expire.


Other files:

published.xml:
	
	To have an overview of what you have published yourself, all
	these headers are saved in this file.

	published2html.xml:

		You can view the published.xml file in your
		internet-browser via this stylesheet.

news.xml.lock,
prefs.xml.lock:

	These files indicate that one mpn-program uses the
	news.xml/prefs.xml file. No other program touches the
	corresponding file for the time one of this files exists. If
	something goes wrong (program crash) it could remain and you
	have to delete them manually.

