Straw

= Contents =

    * Introduction
    * Minimum Requirements
    * Installation
    * Notes on Installation
    * Notes on Translation
    * Notes on Configuring your Web Browser
    * Database Corruption: How to recover data
    * Database Conversion Problems ( for version 0.21.x and below ONLY )
    * Environment variables
    * Help?



=== Introduction ===

Straw is a desktop news aggregator for the GNOME environment. Its aim is to
be a faster, easier and more accessible way to read news and blogs than the
traditional browser.



=== Minimum Requirements ===

1. Python 2.4
2. Python ADNS - This is optional, but you get better results if you have it
    installed. If you don't, Straw's user interface freezes on every name
    lookup (the results are cached though, so it shouldn't be too bad.)
3. Berkeley DB and their python bindings (pybsddb)
4. PyGTK 2.8+ (incl. extras which contains the gtkhtml2 module)
6. GConf

=== Installation ===

1. Make sure you have the required packages to run Straw

[myshell@test.com]$ cd straw
[myshell@test.com:~/straw]$ python setup.py install_modules_check

2. Build the necessary files to run Straw

[myshell@test.com:~/straw]$ python setup.py build

3. Install

[myshell@test.com:~/straw]$ python setup.py install

... Or if you want to install straw in /usr/local..

[myshell@test.com:~/straw]$ python setup.py install --prefix=/usr/local



=== Notes on Installation ===

Straw installs files into three locations: 

1. The straw executable into a directory that should be in your $PATH, like
   '/usr/bin/' or '/usr/local/bin'.

2. A library directory to a location that should be in python's search path,
    like '/usr/lib/python2.2/site-packages' or '/usr/local/lib/python2.3/site-packages'.

3. And a data directory into a location that should be an architecture-neutral
    directory like it '/usr/share/' or '/usr/local/share'

If the library directory[2] isn't in your search path, or if you for some
reason installed it elsewhere, you should point the STRAW_LIB
environment variable at the directory under which the straw library
directory was created. 



=== Notes on Translation ===

(1) Updating the POT file

[myshell@test.com:~/straw]$ python setup.py translate --pot


(2) Merging LANGCODE.po with straw.pot

[myshell@test.com:~/straw]$ python setup.py translate --dist LANGCODE


(3) Merging translation with desktop file

[myshell@test.com:~/straw]$ python setup.py build_desktop

'python setup.py --help-commands' for more info.


=== Database Corruption: How to recover data ===

When you see following error ...

"Recovery Error: See README for details on how to recover data."

... run ...

[myshell@test.com:~/straw]$ db_recover -h $HOME/.straw -c -v
[myshell@test.com:~/straw]$ db_checkpoint -1 -v

... after which you can now restart straw and everything should be fine. 

If it still errors, read the last paragraph of the next section (... conversion problems)


=== Database conversion problems ( for version 0.21.x and below ONLY ) ===

The database format changed between Straw versions 0.21 and
0.22. Straw will automatically convert your database, but people have
experienced problems which we have been unable to trace.

If the conversion fails, you will be shown a dialog reporting the
problem. The exception will be saved to a file, the dialog will tell
you the name. You should see what's the problem; if it contains an
error telling you to run recover, you should try running db_recover on
the $HOME/.straw directory, like this:

$ db_recover -h $HOME/.straw -c -v
$ db_checkpoint -1 -v

However, this does not always help. If all else fails, you should
rescue your $HOME/.straw/config file and put it in a new, empty
$HOME/.straw directory. You will lose all the articles and images, but
your subscriptions will be safe.

We apologize for the inconvenience.

=== Environment variables ===

While most of Straw's configuration is stored in gconf and its own
configuration file, there are also some more developer-oriented
environment variables that modify Straw's behaviour.

STRAW_RELOAD_CSS: If defined, reload CSS every time an article is
                  displayed.

STRAW_THREAD_DNS: If defined, use a separate thread with the normal
                  name resolving instead of ADNS for name look
                  ups. Avoids the ADNS dependency and the various
                  problems with the library (spurious lookup failures,
                  resolv.conf parsing problems) but causes a frozen UI
                  in some installations.

STRAW_NO_ETAGS:   Don't use ETags. Causes extra network traffic, but 
                  occasionally useful for debugging.

STRAW_IN_SOURCE_DIR: Tell Straw it's running in the source directory,
                     so it knows where to look for dependencies.

=== Help? ===

1. Visit http://live.gnome.org/Straw for mailing lists and reporting defects.
2. We have a channel in irc.freenode.net called #straw.
3. For more installation commands, run:

[myshell@test.com:~/straw]$ python setup.py --help-commands


- Straw Maintainers
