Chapter 3. Help and FAQ

Frequently Asked Questions

Frequently Asked Questions

This page tries to answer frequently asked questions. If your question is not answered here, have a look at the Getting in contact section.

1.1. What is FreeGuide?
1.2. How do I install FreeGuide?
1.3. How do I use FreeGuide?
1.4. I got an "Execution Error" message. What is wrong?
1.5. FreeGuide used to work for me but now it's stopped. What is wrong?
1.6. How do I completely uninstall FreeGuide on Windows?
1.7. How do I completely uninstall FreeGuide on Linux?
1.8. The "Choose Channels" grabber configuration step gives me an error. What is wrong?
1.9. What version of Java does FreeGuide need?
1.10. Can I use FreeGuide from behind a proxy server?
1.11. How do I change the order in which channels are listed?
1.12. I've downloaded the listings but FreeGuide says some are still missing! What's happening?
1.13. Something is going wrong - how can I help to diagnose the problem?
1.14. How can I make FreeGuide download more than 1 weeks' XMLTV listings at a time?
1.15. I run linux, how can I setup a cronjob to have freeguide retrieve listings?
1.16. How do I use a listings grabber that is not part of the XMLTV project? (E.g. for using FreeGuide in Australia.)
1.17. FreeGuide doesn't list the look-and-feel I installed - how do I use it?
1.18. How do I change my GTK theme?
1.19. Are there any other web sites about FreeGuide?
1.20. How do I find out what's being planned for future versions?
1.21. How do I ask more questions?
1.1.What is FreeGuide?

FreeGuide™ is a TV listings viewer that works offline.

See "What is FreeGuide".

1.2.How do I install FreeGuide?

See the installation instructions.

1.3.How do I use FreeGuide?

Look at "Using FreeGuide".

1.4.I got an "Execution Error" message. What is wrong?

Note: if you very quickly get an "Execution Error" message, check that you're connected to the Internet and try again. If you have to wait quite a while and then get the "Execution Error" message, everything may still be alright - click "Continue" to see.

If you get a message about "Username not specified" or "Config file not found" or "re-run --configure", try going to the "Tools" menu and clicking "Choose channels for XMLTV", and following the instructions to choose your channels again. If you are in North America, don't forget to enter your username and and password, even though it says this is not recommended.

If you keep getting the "Execution Error" message and you don't see any listings when you click "Continue" then click "Show Details" and copy the error messages shown into an email and send it to freeguide-tv-users@lists.sourceforge.net with an explanation of what you were doing, what operating system you are on and what versions of Java and FreeGuide you are using.

1.5.FreeGuide used to work for me but now it's stopped. What is wrong?

If FreeGuide used to work for you and has now stopped, it is probably because the web site it grabs listings from has changed its format. Check the whether there is a new FreeGuide version.

If there isn't a new FreeGuide yet, you can see whether there's a new xmltv version and then follow these instructions to install it:

  • Under Windows unzip the xmltv-x.x.x-win32.zip file and copy the file xmltv.exe over your file "C:\Program Files\FreeGuide\xmltv\xmltv.exe"

  • Under Linux, download the file xmltv-x.x.x-tkgui.tar.bz2 and install it as usual.

Now try downloading and see whether it works.

1.6.How do I completely uninstall FreeGuide on Windows?

You can uninstall FreeGuide on Windows by going to the "Add/Remove Programs" screen in the Control Panel. That should be all you need to do.

However, uninstalling FreeGuide leaves your settings (such as favourites, colours etc.) on your computer. Often, this is useful, since if you ever re-install FreeGuide it will already be set up for you, but sometimes you might want to delete these settings, for example if something has gone wrong and you want to start again from scratch, or if you just don't like programs leaving stuff all over your computer.

To remove the FreeGuide settings from the Windows registry, follow these instructions:

WARNING: messing with the registry can break your computer! Don't do it if you're not confident.

  • First, uninstall FreeGuide from the Add/Remove Programs screen. (Under Control Panel).

  • Click the Start button then "Run".

  • Type "regedit" and press Return.

  • In the menu at the top chose "Edit" and click "Find"

  • Make sure all three "look at" boxes are checked.

  • Type "freeguide-tv" in the search box.

  • Click "Find Next".

  • Regedit should find a node called freeguide-tv. Right-click the node and choose "Delete".

  • Now press F3 on the keyboard to find any other nodes also called freeguide-tv, and delete all of them in the same way.

This should remove all trace of FreeGuide from your computer.

1.7.How do I completely uninstall FreeGuide on Linux?

First, uninstall FreeGuide using your normal package management tool.

Now, for each user that used FreeGuide, delete the ~/.freeguide and ~/.java/.userPrefs/org/freeguide-tv directories.

1.8.The "Choose Channels" grabber configuration step gives me an error. What is wrong?

If your grabber fails to configure or run because it can't seem to get any data from the Internet, it may be because you need to use a proxy server. Read the proxy section for information on how to set one up.

1.9.What version of Java does FreeGuide need?

FreeGuide needs Java version 1.4.0 or above. You can find out what version you are using by opening a DOS window or Cmd prompt and typing "java -version". If it says you've got an earlier version, or if you get an error, you need to get an upgrade from http://java.sun.com/getjava/.

1.10.Can I use FreeGuide from behind a proxy server?

Yes. Have a look at "Configure proxy server"

1.11.How do I change the order in which channels are listed?

To change the order of channels, you need to make a channel set. Choose "Channel Sets" from the "Tools" menu and create one there, than choose it from the drop-down in the top right hand corner of the screen.

1.12.I've downloaded the listings but FreeGuide says some are still missing! What's happening?

If you grab some listings late in a day, nearing the grabber's idea of the end of a day (e.g. close to 6am for the UK grabber) then you may be told that there are missing listings for that day even though you've just grabbed new listings. This is because the grabbing has started from tomorrow, so what's left of today doesn't have a full set of listings. Don't worry about this - just say "No" and you should be able to see what you need.

1.13.Something is going wrong - how can I help to diagnose the problem?

If FreeGuide is not working or acting strangely, you should contact the developers - see How do I ask more questions?. When you do contact the mailing lists, it would be useful to know various pieces of information.

You should find out your operating system (e.g Windows XP™), the version of Java™ you are using, and the version of FreeGuide. Linux users should also check theit XMLTV version.

If you are having problems downloading, the first useful piece of information is the contents of the "Show details" window. Copy and paste the information in there into your email.

If you are having more complex problems, the developers may ask you to try running FreeGuide from within a DOS or Cmd Window. Here is how to do that in Windows:

From the Start menu choose Programs, Accessories and click "Cmd Window" or "DOS Window".

Now type the following 2 lines:

cd "C:\Program Files\FreeGuide" <PRESS RETURN>
java -jar startup.jar > log.txt <PRESS RETURN>

Now copy and paste the contents of C:\Program Files\FreeGuide\log.txt into an email, remembering to CC the mailing list you first sent your message to.

1.14.How can I make FreeGuide download more than 1 weeks' XMLTV listings at a time?

Go to the "Tools" menu and choose "Options". Open the "Advanced" node and open the "Grabbers" node, and choose "XMLTV". In the lower text box is the command used to run the XMLTV grabber. It starts something like this:

"%xmltv_path%/xmltv.exe" tv_grab_uk_rt

(The uk_rt bit will be different if you are not in the UK.) After this bit are the other bits of the command, e.g. "--quiet", "--config-file" etc. If you add the string " --days 14 " after the main command (shown above) and before the other options (e.g. "--quiet") this will tell XMLTV to download 14 days instead of the default of 7.

If something gets messed up and listings won't download, click the button labelled "Default" to get the old command back.

Note that some of the listings sources do not provide listings for such a long time into the future, and some of the XMLTV grabbers for some countries do not listen to the --days option, so this change may not make any difference for some people.

1.15.I run linux, how can I setup a cronjob to have freeguide retrieve listings?

You can't, at least not with freeguide. You can use XMLTV to download the listings for freeguide to use.

Essentially, you'll use the XMLTV grabber to retrieve the listings and redirect to an .xmltv file in the freeguide directory. The next time you start freeguide, the new listings will be read in.

  • First, figure out exactly what the xmltv grabber command is. Under 'options', 'advanced', you can highlight the 'xmltv' grabber and see the command that's used. For me, the command is:

    tv_grab_na_dd  --quiet --config-file "%config_file%"

    The config file is stored in the freeguide working directory under a sub-directory called xmltv-configs. You will need to specify the exact path, the variable in the command above won't work right.

  • Just to keep the crontab cleaner looking, create a shell script with the command in it:

    #!/bin/bash
    tv_grab_na_dd --quiet --config-file ~/.freeguide/xmltv-configs/na_dd.conf  > ~/.freeguide/list.xmltv
                      

    If your freeguide directory is *not* in your home directory, then you'll need to replace the ~/ part with the path to the freeguide directory.

    chmod the file 700 and try running it. The script should download the latest listings and dump them out to an .xmltv file in your freeguide directory.

    Go ahead and start freeguide. There should be a short delay as it reads in the downloaded listings.

  • Assuming the command worked right, then you can create a cron entry for calling the script.

    If you're unfamiliar with cron, I suggest reviewing the crontab man page via "man 5 crontab".

    There are 5 fields that define *when* a cronjob is run. To do a cronjob that runs at 5:30 on Sunday, then run 'crontab -e' and put on a single line:

    30 5 * * 0   ~/bin/SHELLSCRIPT

    Use whatever you called your shell script instead of SHELLSCRIPT.

    If your cronjob is run as the user, it should work at the correct time. If you end up with an error about command not found or something, you will probably need to specify the exact path to the shell script like this:

    30 5 * * 0 /home/YOUR_USERNAME/bin/SHELLSCRIPT
1.16.How do I use a listings grabber that is not part of the XMLTV project? (E.g. for using FreeGuide in Australia.)

Here is some advice from one of our users on how he got Australian listings working:

I went to http://minnie.tuhs.org/twiki/bin/view/TVGuide/ and signed up for an account, then i downloaded http://www.wireplay.org/xmltv_au/tv_grab_au.exe then i just went into tools, options, advanced,grabbers,xmltv, picked any one and changed the command path to C:\Program Files\video\FreeGuide\TVGuideGrabber\tv_grab_au_tuhs.exe --config-file "C:\Program Files\video\FreeGuide\TVGuideGrabber\tv_grab_au_tuhs.xml"

If you manage to get any non-official grabbers working, let us know on the developers' mailing list so we can help others do the same. If any third-party grabber works well, and is not going to go into XMLTV for some reason (e.g. it's not written in Perl),and it's GPL licenced, we will consider distributing it as a part of FreeGuide to make it easier for others to use.

1.17.FreeGuide doesn't list the look-and-feel I installed - how do I use it?

If you have installed a look-and-feel that FreeGuide was unable to identify, you may type its class name into the combo box in the General section of the Options screen. Note that you must provide the fully-qualified classname - one that includes several words separated by periods, such as javax.swing.plaf.metal.MetalLookAndFeel. The fully qualified classname should be given in the look-and-feel's documentation.

If you type in the class name and nothing happens, FreeGuide is unable to find the specified class. Make sure you spelled the class name correctly. If everything is spelled correctly, make sure you installed the look-and-feel correctly.

1.18.How do I change my GTK theme?

If you're using a Unix-like operating system, use the tool provided by your distribution vendor to install and select the theme. Now, simply start FreeGuide and, if you haven't already done so, select the GTK+ look-and-feel and enjoy the new look. In general, themes are installed by extracting their files into the ${USER}/.themes directory. If you do not have a tool for working with GTK+ themes, GTK Theme Switch 2 is a nice lightweight program for installing and selecting themes. Note: If you do not want to install and/or select the theme, you may follow the Windows instructions below.

If you're using Windows (or you don't want to install the theme on your Unix-like operating system), it's not necessary to install the theme. Extract the theme files to a directory, keeping each theme in its own directory, and keep all the theme directories together in a single directory to make them easy to find (I recommend using C:\gtk since it's short and easy to type).

Since most of the themes will be distributed in "tarballs" (a common way to distribute software for Unix-like operating systems), you will need an extraction tool that can handle tape archive files (tar files) and GZIP and/or BZIP2 compression. One such tool for Windows is 7-Zip.

Once you've extracted the themes, you're ready to use them. To do so, just specify the location of the gtkrc file in the swing.gtkthemefile system property on the command line, as shown below:

java -Dswing.gtkthemefile="C:\gtk\Theme Name\gtk-2.0\gtkrc" ...

Where "..." means fill in the rest of the shortcut command that was already present.

1.19.Are there any other web sites about FreeGuide?

Richard Turnbull has assembled lots of useful information about FreeGuide on his site, along with a clever script to keep you up-to-date with the very latest versions of XMLTV and FreeGuide. You can find all this at www.kudos.byethost15.com/freeguide/.

1.20.How do I find out what's being planned for future versions?

Check out the TODO list on the developers' wiki.

1.21.How do I ask more questions?

See "Getting in contact".