README

   1 Straw
   2
   3 = Contents =
   4
   5     * Introduction
   6     * Minimum Requirements
   7     * Installation
   8     * Notes on Installation
   9     * Notes on Translation
  10     * Notes on Configuring your Web Browser
  11     * Database Corruption: How to recover data
  12     * Database Conversion Problems ( for version 0.21.x and below ONLY )
  13     * Environment variables
  14     * Help?
  15
  16
  17
  18 === Introduction ===
  19
  20 Straw is a desktop news aggregator for the GNOME environment. Its aim is to
  21 be a faster, easier and more accessible way to read news and blogs than the
  22 traditional browser.
  23
  24
  25
  26 === Minimum Requirements ===
  27
  28 1. Python 2.4
  29 2. Python ADNS - This is optional, but you get better results if you have it
  30     installed. If you don't, Straw's user interface freezes on every name
  31     lookup (the results are cached though, so it shouldn't be too bad.)
  32 3. Berkeley DB and their python bindings (pybsddb)
  33 4. PyGTK 2.8+ (incl. extras which contains the gtkhtml2 module)
  34 6. GConf
  35
  36 === Installation ===
  37
  38 1. Make sure you have the required packages to run Straw
  39
  40 [myshell@test.com]$ cd straw
  41 [myshell@test.com:~/straw]$ python setup.py install_modules_check
  42
  43 2. Build the necessary files to run Straw
  44
  45 [myshell@test.com:~/straw]$ python setup.py build
  46
  47 3. Install
  48
  49 [myshell@test.com:~/straw]$ python setup.py install
  50
  51 ... Or if you want to install straw in /usr/local..
  52
  53 [myshell@test.com:~/straw]$ python setup.py install --prefix=/usr/local
  54
  55
  56
  57 === Notes on Installation ===
  58
  59 Straw installs files into three locations:
  60
  61 1. The straw executable into a directory that should be in your $PATH, like
  62    '/usr/bin/' or '/usr/local/bin'.
  63
  64 2. A library directory to a location that should be in python's search path,
  65     like '/usr/lib/python2.2/site-packages' or '/usr/local/lib/python2.3/site-packages'.
  66
  67 3. And a data directory into a location that should be an architecture-neutral
  68     directory like it '/usr/share/' or '/usr/local/share'
  69
  70 If the library directory[2] isn't in your search path, or if you for some
  71 reason installed it elsewhere, you should point the STRAW_LIB
  72 environment variable at the directory under which the straw library
  73 directory was created.
  74
  75
  76
  77 === Notes on Translation ===
  78
  79 (1) Updating the POT file
  80
  81 [myshell@test.com:~/straw]$ python setup.py translate --pot
  82
  83
  84 (2) Merging LANGCODE.po with straw.pot
  85
  86 [myshell@test.com:~/straw]$ python setup.py translate --dist LANGCODE
  87
  88
  89 (3) Merging translation with desktop file
  90
  91 [myshell@test.com:~/straw]$ python setup.py build_desktop
  92
  93 'python setup.py --help-commands' for more info.
  94
  95
  96 === Database Corruption: How to recover data ===
  97
  98 When you see following error ...
  99
 100 "Recovery Error: See README for details on how to recover data."
 101
 102 ... run ...
 103
 104 [myshell@test.com:~/straw]$ db_recover -h $HOME/.straw -c -v
 105 [myshell@test.com:~/straw]$ db_checkpoint -1 -v
 106
 107 ... after which you can now restart straw and everything should be fine.
 108
 109 If it still errors, read the last paragraph of the next section (... conversion problems)
 110
 111
 112 === Database conversion problems ( for version 0.21.x and below ONLY ) ===
 113
 114 The database format changed between Straw versions 0.21 and
 115 0.22. Straw will automatically convert your database, but people have
 116 experienced problems which we have been unable to trace.
 117
 118 If the conversion fails, you will be shown a dialog reporting the
 119 problem. The exception will be saved to a file, the dialog will tell
 120 you the name. You should see what's the problem; if it contains an
 121 error telling you to run recover, you should try running db_recover on
 122 the $HOME/.straw directory, like this:
 123
 124 $ db_recover -h $HOME/.straw -c -v
 125 $ db_checkpoint -1 -v
 126
 127 However, this does not always help. If all else fails, you should
 128 rescue your $HOME/.straw/config file and put it in a new, empty
 129 $HOME/.straw directory. You will lose all the articles and images, but
 130 your subscriptions will be safe.
 131
 132 We apologize for the inconvenience.
 133
 134 === Environment variables ===
 135
 136 While most of Straw's configuration is stored in gconf and its own
 137 configuration file, there are also some more developer-oriented
 138 environment variables that modify Straw's behaviour.
 139
 140 STRAW_RELOAD_CSS: If defined, reload CSS every time an article is
 141                   displayed.
 142
 143 STRAW_THREAD_DNS: If defined, use a separate thread with the normal
 144                   name resolving instead of ADNS for name look
 145                   ups. Avoids the ADNS dependency and the various
 146                   problems with the library (spurious lookup failures,
 147                   resolv.conf parsing problems) but causes a frozen UI
 148                   in some installations.
 149
 150 STRAW_NO_ETAGS:   Don't use ETags. Causes extra network traffic, but
 151                   occasionally useful for debugging.
 152
 153 STRAW_IN_SOURCE_DIR: Tell Straw it's running in the source directory,
 154                      so it knows where to look for dependencies.
 155
 156 === Help? ===
 157
 158 1. Visit http://live.gnome.org/Straw for mailing lists and reporting defects.
 159 2. We have a channel in irc.freenode.net called #straw.
 160 3. For more installation commands, run:
 161
 162 [myshell@test.com:~/straw]$ python setup.py --help-commands
 163
 164
 165 - Straw Maintainers