Here are three minor gotchas:

1. To ignore a directory, use -i path/relative/to/the/src/root/ with a “/” at the end (or “\” for Windows). You MUST have that trailing slash, otherwise the directive is treated differently (filename match)
2. To ignore multiple directories, you cannot use multiple -i -directives. If you do, they will overwrite one another, and only the last one will be applied. Instead, use a comma to separate the paths: -i first/path/,second/path/
3. If you happen to use 1.4.3 and use the ”HTML:frames:earthli” template, you will notice that the images and css files won’t load because they are missing one character at the end for some reason. Solution: rename or copy the template from a previous version to “./PhpDocumentor/Converters/HTML/frames/earthli”.

Really, this is simple but the documentation is rather unclear as to how this works (particularly the point about the significance of the last slash character). I found some comments in the bug tracker which helped me find the correct syntax (here). Both of these things are implied in documentation, but I figure writing this might save someone else some time.

I went through a number of articles as well as my own CSS files, and here are my suggestions for semantic CSS layouts (names of ID’s and classes) as an image.

There is an article that could be written on the information, but I can’t be bothered. View the full-size version here.

Here is a quick, up-to-date (as of 05/2009) guide to installing and troubleshooting trac, mercurial and trac-mercurial on FC10. I started with a fresh VM install for this guide.

1. Get the dependencies and tools

yum install wget
yum install python mercurial trac trac-mercurial
yum install python-devel python-setuptools python-genshi python-docutils python-pygments mod_python


2. Get easy_install to work on FC10

wget http://peak.telecommunity.com/dist/ez_setup.py

Here is the first (minor) pitfall. You need to force the update of easy_install. If you only run “python ez_setup.py”, then you will not get the easy_install command (bash will not recognize it). Run:

python ez_setup.py -U setuptools

3. Install the mercurial plugin

From: http://trac.edgewall.org/wiki/MultipleRepositorySupport

Check out the mercurial plugin:
svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.12

Build the mercurial plugin. From within the checked-out directory, build the egg file (it will end up in the dist subdirectory):

python setup.py bdist_egg

Check out the multirepos branch:

svn co http://svn.edgewall.com/repos/trac/sandbox/multirepos

Install the multirepos version of trac (from within the multirepos directory, as root):

python setup.py install

4. Get the development branch of Genshi

Here you will run into the error “No local packages or download links found for Genshi>=0.6dev-r960″. To fix this, you need to force an update of Genshi to the latest dev version:

easy_install -U "Genshi==dev"

5. Create your trac environment directory

For example:

trac-admin /path/to/trac/myproject initenv
chown -R apache:apache /path/to/trac/myproject

6. Setup Apache for Trac

nano etc/httpd/conf/httpd.conf

Add something like:

<Location "/trac">
SetHandler mod_python
PythonInterpreter main_interpreter
PythonHandler trac.web.modpython_frontend
PythonOption TracEnvParentDir /path/to/trac
PythonOption TracUriRoot /trac
</Location>


And if you haven’t added mod_python already:

LoadModule python_module modules/mod_python.so

7. Continue with the setup

From: http://trac.edgewall.org/wiki/MultipleRepositorySupport

Copy the mercurial plugin egg file to the <trac-env>/plugins directory. Make sure the following is somewhere in <trac-env>/conf/trac.ini, adding all the desired repositories to the [repositories] section:
[components]
tracext.hg.* = enabled[repositories]
my_repo_a.dir = path_to_a_repository

8. Restart apache and test

service httpd restart

Navigate to http://localhost/trac .

Some possible errors

If you get something like:

Available Projects

    * attachments: Error
      ([Errno 2] No such file or directory:
'/path/to/trac/env/attachments/VERSION')

Check your TracEnvParentDir in httpd.conf, it is probably incorrect. (And restart apache.)

If you get the error:

"Unsupported version control system "hg": Can't find an appropriate component, maybe the corresponding plugin was not enabled? "

Check if you copied the TracMercurial-0.12.0.6dev_r7902-py2.5.egg file to the correct location. (And restart apache.)

References:

http://trac.edgewall.org/wiki/TracOnFedoraCore

http://trac.edgewall.org/wiki/TracMercurial

http://trac.edgewall.org/wiki/TracModPython

http://trac.edgewall.org/wiki/MultipleRepositorySupport

http://www.smallroomsoftware.com/articles/2008/2/14/trac-0-11-installation-on-centos-fedora

I figured the first thing to do in order to get my book reviews online was to set up the functionality to get them from Amazon and display them on my site. This way I can write reviews on Amazon and have them automatically added to my own site.

Amazon offers an RSS feed of your reviews under your profile, see the link in the “Public Reviews Written by You” heading on “Your Profile”. What we will do is use this RSS to create a new site.

Get Simplepie (and CodeIgniter, if you want to)

I am going to set up the site using the CodeIgniter MVC framework and the SimplePie RSS reader library. You don’t really need to use CodeIgniter, but I wanted to give it a try. First download SimplePie and move the simplepie.inc file under /application/libraries and rename it to “simplepie.php”. Set up CodeIgniter as instructed in the user guide.

Controller code

In your controller:

  function index($start = 0, $length = 5)
  {
      $this->load->library('simplepie');
      $this->simplepie->set_cache_location('./system/cache');

      // amazon uses class and id attributes in their review, which are useful for styling the content inside CDATA - so allow those two, and the rest is default.
      $attribs = $this->simplepie->strip_attributes;
      // unset class and id
      if (($key = array_search('class', $attribs)) !== null) {
          unset($attribs[$key]);
      }
      if (($key = array_search('id', $attribs)) !== null) {
          unset($attribs[$key]);
      }
      $this->simplepie->strip_attributes($attribs);
      // change this to your Amazon book review RSS feed address
      $this->simplepie->set_feed_url('http://www.amazon.com/rss/people/A31F72N3CBFDG2/reviews/ref=cm_rss_member_rev_manlink');
      $this->simplepie->init();
      $data['feed'] = $this->simplepie;
      $data['start'] = $start;
      $data['length'] = $length;
      $this->load->view('show_rss', $data);
  }

View code

After that, create the view (show_rss in my case). Create code to process the feed. I used the pagination code from the SimplePie documentation as the basis so that you can have separate pages for the items:

  foreach ($feed->get_items($start + 1, $length) as $item) {
      $feed2 = $item->get_feed();
      echo '

' . $item->get_title(true) . '
Source: ' . $feed2->get_title() . ' | ' . $item->get_date('j M Y, g:i a') . '


' . $item->get_content() . '

              ' . $item->get_date('j M Y, g:i a') . '
            


';
  }

  // Let's do our paging controls
  $next = (int)$start + (int)$length;
  $prev = (int)$start - (int)$length;

  // Create the NEXT link
  $nextlink = 'Next »';
  if ($next > $max) {
      $nextlink = 'Next »';
  }

  // Create the PREVIOUS link
  $prevlink = '« Previous';
  if ($prev < 0 && (int)$start > 0) {
      $prevlink = '« Previous';
  } elseif ($prev < 0) {
      $prevlink = '« Previous';
  }

  // Normalize the numbering for humans
  $begin = (int)$start + 1;
  $end = ($next > $max) ? $max : $next;

  echo '


Showing ' . $begin . '–' . $end . ' out of ' . $max . ' | ' . $prevlink . ' | ' . $nextlink . ' | 5, 10, or 20 at a time.


';

CSS stylesheet

Finally, add a stylesheet. I used one from Free CSS Templates. I also made the following minor tweaks:

span.amzRssByline {
  /* Adds newline before the by line in reviews */
  display: block;
}

div.entry img {
  /* Floats the review picture */
 float: left;
 display: block;

}
div.entry table div {
  /* Adds a margin after the review heading */
 margin-bottom: 10px;
}

Here is the result: http://books.mixu.net/

Update 2 (Oct 2009): Since this is reasonably popular content, here are some additional findings:

First, Flash does not always use the same settings as your browser – try the proxy settings in Internet Explorer/Chrome. These seem to work better. The vast majority of problems are a result of Flash using different settings than your browser, revealing your actual IP to Hulu.

Second, if this does not work you can always use Proxifier (commercial product with 30 days trial), a TCP wrapper which forces all connections on the computer to use a particular proxy. This can be used in conjunction with a Hulu downloader, such as Hulu Video Downloader to download the videos.

Update: Still works even after Hulu tightened their geofiltering. As long as one isn’t using a mainstream service like Hotspot Shield, I doubt Hulu will be able to fully block this since they are in essence removing access from legitimate US computers. Probably the best thing would be to have a server set up in a legitimate, large institution such a US university or have a home-based server on a consumer ISP in the US. Both would make it hard to block the IP without causing legitimate users to be blocked as well. Then again, for me this is more of an interesting thing to do rather than a necessity. Mileage may vary depending on how proactive Hulu gets, in the end all anyone needs is one non-blocked legitimate IP address in the US.

If you haven’t heard of Hulu, it’s basically a website like YouTube but with full episodes of recent TV series – legal and with short commercials inserted into the video streams. For instance, the HBO show CSI is available on the site very soon after it has been shown in the US and you can watch it directly as streaming video. There is one caveat – the website blocks non-US viewers from watching any of the videos. So, no luck for us Finns.

However, this is rather easy to get around if you happen to have a server based in the US with SSH access. What you need to do is set up a SSH tunnel to your US server, then instruct your web browser to connect via that tunnel. This will cause all connections to Hulu to go through your US server, and will make it possible to watch Hulu videos.

Setting up using the SSH command/PuTTy

SSH allows you to connect securely to the server and create a secure tunnel from your computer to the US-based server. You can set up a local SSH client program to do this.

ssh -D 8080 -p 22 -f -N username@yourserver.com

As the SSH manual page states the -D option:

-D port. Specifies a local "dynamic" application-level port forwarding.
 This works by allocating a socket to listen to port on the local side, 
and whenever a connection is made to this port, the connection is
forwarded over the secure channel, and the application protocol is then
used to determine where to connect to from the remote machine.  Currently
the SOCKS4 and SOCKS5 protocols are supported, and ssh will act as a SOCKS server.

You can also do this in Windows using the PuTTy SSH client. Look under Connection -> SSH -> Tunnels. Add a dynamic port forward, use port 8080 and no need to specify the destination.

Setting Firefox to use the tunnel

Then set up Firefox to use the local SOCKS server (localhost:8080). The relevant settings can be found under Tools -> Options -> Advanced -> Network -> Settings … -> Manual proxy configuration.

Testing

This works very nicely, because you are now connecting from an US IP. To verify this, open up Internet Explorer and check http://www.whatsmyip.org/ and do the same in Firefox. You should see two different IP addresses. Just remember that any videos you watch will be transferred twice (from a bandwidth usage perspective) – once to your US server and then back. A single video is only about a hundred megabytes or so, so this not particularly bad for the convinience though.