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.3
  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 DB3 or DB4 and their python bindings (pybsddb)
  33 4. PyGTK and PyGNOME.
  34 5. libglade
  35 6. GConf
  36 7. Python Distutils for installing Straw (python-dev for some distros).
  37
  38 You should already have (4), (5), and (6) if you're using GNOME as your
  39 desktop environment. (5) & (6) should also come with your distribution.
  40 Installing PyGTK should suggests or even install PyGNOME.
  41
  42
  43
  44 === Installation ===
  45
  46 1. Make sure you have the required packages to run Straw
  47
  48 [myshell@test.com]$ cd straw
  49 [myshell@test.com:~/straw]$ python setup.py install_modules_check
  50
  51 2. Build the necessary files to run Straw
  52
  53 [myshell@test.com:~/straw]$ python setup.py build
  54
  55 3. Install
  56
  57 [myshell@test.com:~/straw]$ python setup.py install
  58
  59 ... Or if you want to install straw in /usr/local..
  60
  61 [myshell@test.com:~/straw]$ python setup.py install --prefix=/usr/local
  62
  63
  64
  65 === Notes on Installation ===
  66
  67 Straw installs files into three locations:
  68
  69 1. The straw executable into a directory that should be in your $PATH, like
  70    '/usr/bin/' or '/usr/local/bin'.
  71
  72 2. A library directory to a location that should be in python's search path,
  73     like '/usr/lib/python2.2/site-packages' or '/usr/local/lib/python2.3/site-packages'.
  74
  75 3. And a data directory into a location that should be an architecture-neutral
  76     directory like it '/usr/share/' or '/usr/local/share'
  77
  78 If the library directory[2] isn't in your search path, or if you for some
  79 reason installed it elsewhere, you should point the STRAW_LIB
  80 environment variable at the directory under which the straw library
  81 directory was created.
  82
  83
  84
  85 === Notes on Translation ===
  86
  87 (1) Updating the POT file
  88
  89 [myshell@test.com:~/straw]$ python setup.py translate --pot
  90
  91
  92 (2) Merging LANGCODE.po with straw.pot
  93
  94 [myshell@test.com:~/straw]$ python setup.py translate --dist LANGCODE
  95
  96
  97 (3) Merging translation with desktop file
  98
  99 [myshell@test.com:~/straw]$ python setup.py build_desktop
 100
 101
 102 'python setup.py --help-commands' for more info.
 103
 104
 105
 106 === Notes on Configuring your Web Browser ===
 107
 108 If you click a URL, straw loads the URL in whatever browser is set in your
 109 environment. This is set through the following easy steps:
 110
 111  1. Applications -> Desktop Preferences -> Advanced -> File Types & Programs
 112  2. Click on Documents -> World Wide Web -> HTML page
 113  3. On the left hand side, choose Edit.
 114  4. Choose your browser in the "Default Action" box inside the Actions Frame.
 115
 116 ***NOTE***: This doesn't work for some. Help is very much appreciated here.
 117
 118
 119 === Database Corruption: How to recover data ===
 120
 121 When you see following error ...
 122
 123 "Recovery Error: See README for details on how to recover data."
 124
 125 ... run ...
 126
 127 [myshell@test.com:~/straw]$ db_recover -h $HOME/.straw -c -v
 128 [myshell@test.com:~/straw]$ db_checkpoint -1 -v
 129
 130 ... after which you can now restart straw and everything should be fine.
 131
 132 If it still errors, read the last paragraph of the next section (... conversion problems)
 133
 134
 135
 136 === Database conversion problems ( for version 0.21.x and below ONLY ) ===
 137
 138 The database format changed between Straw versions 0.21 and
 139 0.22. Straw will automatically convert your database, but people have
 140 experienced problems which we have been unable to trace.
 141
 142 If the conversion fails, you will be shown a dialog reporting the
 143 problem. The exception will be saved to a file, the dialog will tell
 144 you the name. You should see what's the problem; if it contains an
 145 error telling you to run recover, you should try running db_recover on
 146 the $HOME/.straw directory, like this:
 147
 148 $ db_recover -h $HOME/.straw -c -v
 149 $ db_checkpoint -1 -v
 150
 151 However, this does not always help. If all else fails, you should
 152 rescue your $HOME/.straw/config file and put it in a new, empty
 153 $HOME/.straw directory. You will lose all the articles and images, but
 154 your subscriptions will be safe.
 155
 156 We apologize for the inconvenience.
 157
 158 === Environment variables ===
 159
 160 While most of Straw's configuration is stored in gconf and its own
 161 configuration file, there are also some more developer-oriented
 162 environment variables that modify Straw's behaviour.
 163
 164 STRAW_RELOAD_CSS: If defined, reload CSS every time an article is
 165                   displayed.
 166
 167 STRAW_THREAD_DNS: If defined, use a separate thread with the normal
 168                   name resolving instead of ADNS for name look
 169                   ups. Avoids the ADNS dependency and the various
 170                   problems with the library (spurious lookup failures,
 171                   resolv.conf parsing problems) but causes a frozen UI
 172                   in some installations.
 173
 174 STRAW_NO_ETAGS:   Don't use ETags. Causes extra network traffic, but
 175                   occasionally useful for debugging.
 176
 177 STRAW_IN_SOURCE_DIR: Tell Straw it's running in the source directory,
 178                      so it knows where to look for dependencies.
 179
 180 === Help? ===
 181
 182 1. Visit http://www.nongnu.org/straw for mailing lists and reporting defects.
 183 2. We have a channel in irc.gimpnet.org called #straw.
 184 3. For more installation commands, run:
 185
 186 [myshell@test.com:~/straw]$ python setup.py --help-commands
 187
 188
 189 - Straw Development Team