Saturday, August 21, 2010

Off-line Wiki - using TWiki with Subversion

As part of my personal productivity setup I use a wiki, and for a while now I've wanted to be able to use it off-line as well - on a laptop without Internet connection.

I finally took the plunge, and converted my previous on-line-only TWiki into an on-line/off-line setup based on FosWiki. It was remarkably easy. At least, after I finally decided not to use any of the fancy alternatives.

There is a surprisingly large number of experimental wikis in this area, but most do not look very usable or stable. For example I looked at Ikiwiki and Gitit, two Git-based wikis. Both looked interesting but it turned out that neither supports Windows. One of my requirements is to run it off-line on a Windows laptop. I also looked at various extensions for TWiki and FosWiki that are supposed to support off-line work, such as MercurialContrib, Subversive and SubversionStoreContrib. In the end I decided to focus on Subversion (instead of Git and Mercurial) because subversion is simpler. When I tried out SubversionStoreContrib for FosWiki it turned out to be incomplete and didn't work. 

In the end I selected the following straightforward setup:
  • First I migrated my on-line TWiki to FosWiki, because FosWiki is easy to install on Windows and more up to date than my aging TWiki setup, while still 100% compatible with the TWiki page format. This will allow me to create off-line copies on various Windows environments easily.
  • I imported the pages from the Main web into Subversion, but only the ones I'd written myself. All system pages (such as WebPreferences.txt) were added to the ignore list, as well as all files ending in ,v and .lease. I did the same for the attachments in pub/Main. 
  • Next I created two simple shell scripts to update and commit the local svn workspace from/to the repository. These scripts add new files to the repository where needed. They can be called from links on the main WebHome page.
  • For the off-line setup I installed FosWiki to my laptop and used TortoiseSVN to check out the page and attachment parts of the repository into the right FosWiki directories. 
  • The main trick here is to leave the normal TWiki/FosWiki RCS-based store unchanged, but simply add *,v to the SVN ignore list.
  • The result is that most use cases are covered both on-line and off-line; editing, updating, committing and adding new files. I haven't covered deleting and renaming files yet in the on-line scripts because those are pretty rarely used, and can be done easily off-line using TortoiseSVN.
  • Another result that is not very elegant is that because the RCS ,v files are not in SVN they are basically worthless and the history view in the wiki itself will be incorrect. I simply chose to ignore this, and when I want to see the page history (pretty rare again) I can do so using the SVN tools.
All in all I'm very satisfied with this setup, it does what I wanted it to, and is suitable for use by one or more users with technical / Subversion experience. It seems less suitable for very large user groups and non-technical users.

If you're interested let me know in the comments and I can supply more details (scripts, ignore lists etc.)

2 comments:

  1. Hi Steven
    I'm very interested in your setup as I also want to run foswiki locally as well as on line. I my case I'd rather use git but I'm happy to use subversion instead: I'm familiar with both.
    Would it be possible to have a copy of your scripts?
    Gareth

    ReplyDelete
  2. Hi Gareth,

    You can find a zip file with the scripts here: https://docs.google.com/file/d/0B0WvUvHSerCAWjl3dEI1SGcxNnc/edit?usp=sharing

    I put them in the bin directory of my Foswiki install.

    ReplyDelete