

         README FOR MANUALLY INSTALLING AND SETTING UP TAGSTORE


This file is part of tagstore, an alternative way of storing and
retrieving files and folders.

Copyright (c) 2010-2014  Karl Voit, Christoph Friedl, Wolfgang Wintersteller


This is a short description of how to manually install, configure, and
start the tagstore software.

You don't need the manual *installation* in case you use the Windows
installer.

You don't need the manual *configuration* steps in case you are happy
with the default settings: English language, one tag-line, free
vocabulary.


* High-level Overview of the Setup-process

The setup process consists of following steps (described in detail
below):

1. check prerequisites (Python)
   - in order to be able to run tagstore
2. edit the general tagstore configuration
   - in case you want to modify the default setting
3. creating your first store via tagstore Manager
   - in order to get your first store that will hold your files
4. start the tagstore daemon
   - which recognizes new files in stores


* Setup-process in Detail

** STEP 1: prerequisites

a) open a commandline shell (cmd.exe or Terminal or similar)

b) test if Python is available on your system path:

: python --version

(expected output, where 2.5 or higher is fine)
Python 2.5.0

In case there is an output like this:

: python: command not found

please check your system PATH variable and your python installation.


** STEP 2: Manually Editing the General tagstore Config File

General configuration of tagstore can be done by manually editing the
tagstore.cfg file which is located in the folder:

: /path_to_tagstore_installation/tsresources/conf/store.cfg

*** max_tags

Set the number of tags allowed to be used for tagging a single item.
Up to six tags can be computed within a reasonable time on typical
systems which depends on your hardware: SDD is much faster than
hard-disks, Linux is much faster than Windows.

*WARNING*: Using higher numbers of max_tags can lead to incredible
high computation time for each tagging process.

*** num_popular_tags

Sets the number of recent/popular describing tags which should be
shown as decision help.

** STEP 3: create a new store


a) Run the tagstore-manager file:

   : python /path_to_tagstore_installation/tagstore-manager.py
   OR
   : /path_to_tagstore_installation/tagstore-manager.py	(make sure the executable flag is set for this file)
   Then, the tagstore manager window should appear.

b) Create a new store:

  1. select the tab "Store Management"
  2. click the button "New Tagstore" and select a directory where you
     want to create your new tagstore.
  3. please make sure this directory is empty, so there can be no
     troubles with already existing files there. you can create a new
     directory directly at the selection dialog if you want to.
  4. the selected directory should now appear in the list below the "New
     Tagstore" button.

c) Check if the creation of the tagstore was successful:

   Go to the previously selected directory (the new store). Check if there are following sub-directories:
    storage
    navigation
    categorization
    expired_items

d) Close the tagstore manager by clicking the "Save" button in the bottom right corner. 


** STEP 4: Start the tagstore daemon (= the thing which is running in background)

NOTE: From now on, the daemon (tagstore.py) needs to run in background
all the time in order to recognize new files in the stores!

Just run the tagstore.py file in the same way you ran the
tagstore-manager file above:

   : python /path_to_tagstore_installation/tagstore.py
   OR
   : /path_to_tagstore_installation/tagstore.py	(make sure the executable flag is set for this file)

In order to run the daemon on system start, you will need to set-up
something that tagstore.py gets started as well. On GNU/Linux systems,
you might find starttagstore.sh handy. Please change the path to
tagstore ("/home/karl/bin/tagstore") according to your set-up.


* OPTIONAL: More Starting Parameters

In the same folder where this README file (you are reading now) is
located, there is a file called tagstore.py.  Run "python tagstore.py -h" for
displaying optional starting parameters.


* OPTIONAL: GNU/Linux: Create a Start Menu Entry for tagstore Manager

In case you want to start the tagstore manager from your desktop
environment, you might place "tagstore_manager.desktop" in, e.g.,
"~/.local/share/applications/". 

Please modify the tagstore path "/home/karl/bin/tagstore" (twice!)
according to your set-up before!

You also have to modify the tagstore path in the file
"starttagstoremanager.sh" as well.


* OPTIONAL: Manually Editing the Store Config File

Additional configuration for each store can be done by manually editing
the store.cfg file. 

*Please note*: this is only necessary, if you want to differ
configuration between different stores!

Store-specific configuration files are located in folders like:
: /path_to/a_specific_store/.tagstore/store.cfg

Each line in the configuration file represents a configuration
parameter. Only the following parameters might be of interest for you
to be changed manually:

** show_category_line

There are 4 different settings:

0 ... show just the describing tagline 
1 ... show the describing tagline AND a categorizing tagline - freely selectable categorizing tags 
2 ... show the describing tagline AND a categorizing tagline - only restricted vocabulary is allowed
3 ... show just the categorizing tagline - only restricted vocabulary is allowed

** category_mandatory

true ... if there is a categorizing tagline available there MUST be at least one tag provided
false ... the categorizing tagline can be left empty


* Known bugs

- tagstore can not be installed and run from C:\program files
  - Reason: tagstore needs writing permission to its config files
    which are located in the install directory
  - should be fixed by now when using the Windows installer

- tagstore can not be installed in a folder which starts with an
  underline (_)
