Contents:

also see RcsLiteTest

Partial implementation of RCS in 100% Perl

RcsLite will implement only those parts of RCS used by TWiki.

Why do this?

Many uses of TWiki have been put off by the difficulty of getting RCS going. Additionally:

• Want to generalise so other storage/revision mechanisms could be used
• Want to improve diff display
• Reduce out of process calls for easier error handling ...

Support the existing format so that no file conversion is required by a user using RcsLite in place of RCS. Alternative would cause considerable difficulties for users. Having said that, the software could be used to (automatically) transfer data to another medium e.g. a database.

What RCS functionality will be ignored

• Branches
• The command line interface
• Locking

Approach

• Have class RcsLite and Rcs that implement the same interface
• RcsLite will have a simple state machine based parser for reading RCS histories - done (but needs some improvements)
• Simple patch to generate old revisions (done - lots of testing needed)
• Use Algorithm::Diff from http://cpan.org for generating differences between revisions for both updating the RCS file and showing differences to the user.

Note that I've done no work on binary files yet, but I've yet to find a reason why they won't work, my main concern will be one of efficiency when updating a large attachment.

This is now largely working, although still much to do. It's led me down the path of DataFramework. [ JohnTalintyre 9 March 2002 ]

Testing

Making sure RcsLite is equivalent to RCS is very important. I plan to:

• Write some simple Unit Tests for simple test input
• Use RcsLite and RCS to read back all revsions of topics and attachments in TWiki.org to check read
• Reproduce all these version by version to prove write is correct

-- JohnTalintyre - 31 Jan 2002

Also see

• GetRidOfRcs

Discussion

This is good stuff. Some thoughts:

• We will probably see a performance gain because we get rid of the system calls to RCS.
  • In some cases this will be true, but it will depend in part on the efficiency of my implementation[Main.JohnTalintyre - 06 Feb 2002]
• A new switch in TWiki.cfg should determine the version control backend.
  • Yes - but in time perhaps it's not just the version control backend but the general storage and searching of data (e.g. some peoples' desire to use a database)
• Some installations might not want to have the dependency on Algorithm::Diff. Any chance to make this configurable, e.g. use Algorithm::Diff or a system call to diff? Possibly make diff the default so that TWiki runs out of the box without installing the Algorithm::Diff package? Or, ship TWiki with the package?
  • I think we should ship Algorithm::Diff with TWiki, being able to switch to diff certainly makes sense
• Performance: Algorithm::Diff might be slower then diff. This should be no big deal since it is not as performance critical as retrieving the top topic revision.
• Make sure that RCS and RcsLite are interchangeable. That means, RcsLite should read and write exactly the same files as RCS does.
  • Exactly - it's not been as bad as I thought puzzling out the file definition and extensive testing is fairly easy in the area.

-- PeterThoeny - 05 Feb 2002

Are you sure that Algorithm::Diff is a problem? Downloading and installing from CPAN is simple. If people really don't want to mess with their Perl installation, we could repackage it as TWiki::Diff (though I'd wait with that until somebody really requests it).

-- JoachimDurchholz - 06 Feb 2002

I've inserted some comments above. On adding in Algorithm::Diff. It's quite small so I'm inclined to include just the .pm file in TWiki, under the original name. Installing from CPAN isn't always so easy behind firewalls and where you don't have writes to update your local Perl setup. For Algorithm::Diff this isn't so bad since it's a single file, but a major reason for doing RcsLite is to make TWiki installation less of a chore, so I'd rather avoid the added step of "now go to CPAN and get ...".

I do wonder if TWiki will be slowed down (on no ModPerl installation) with the extra code for RcsLite, Algorithm::Diff etc. Should this be dealt with by optional use statments using eval, such as used by Plugins.pm or doesn't it matter?

-- JohnTalintyre - 06 Feb 2002

Use 'require' maybe instead.

With regards to CPAN, if someone can download the TWiki tar ball to a machine, then they can certainly get the associated CPAN tar balls. Possibly the best solution is to distributed the specific core requirement CPAN modules with TWiki but in seperate files. People can then use the standard mechanism to maintain and install those packages. Saves us having to support those packages furthermore makes it easier, say, if we want to use perl DBI or whatever. Which definitely is not a single file.

John, is this done completely in perl. I'd be interested in that patch stuff you've done.

-- NicholasLee - 06 Feb 2002

I think the replacement of the RCS by Perl functions could be a solution for situations, where you have no RCS even in an UNIX environment (e.g. internet provider, see TopicSaveErrorOnHostedSite). Is there already a testable version of the RcsLite ?

-- HardyHaardt - 06 Feb 2002

I'm attaching the current state of play with RcsLite, at present the code only reads Rcs files, but I've got a first cut in there for generating the diff/patch using Algorithm::Diff. Comments welcome.

-- JohnTalintyre - 06 Feb 2002

Work on this is progressing slowly but surely. A things people might be interested in that I'm thinking of or not sure about:

• I'm having trouble dealing cleanly with carriage returns at the end of files. The trouble is that I'm treating each line as a Perl list item and you get interesting effects dealing with missing final new line and multiple new lines when it comes to patching and differencing.
  • One minor thing was that split by default throws out trailing blank recrods. I couldn't find a way of alterting this behavour so added them after the split - which is a bit messy.
• I thought one switch parameter in TWiki.cfg could deal switch between Rcs and RcsLite (and others in the future). One extra config entry could have set of values for pushing into a hash for specific settings e.g. all the RCS specific items in TWiki.cfg would move into this.
• I'm now able to use RcsLite to read old version, write new versions and show the differences between two versions, I can switch back to RCS by changing one line in TWiki.cfg

-- JohnTalintyre - 25 Feb 2002

For most unix folks we probably wont care a hill of beans whether we are using true rcs or your Perl RcsLite, unless of course we see a substantial performance increase or something.

But I see an opportunity for a feature in RcsLite that is present in cvs & sccs but absent in rcs, namely version annotation. If you are familiar with "cvs annotate" then that is what I mean.

Having the ability to show an entire wiki page annotated line by line with who last modified the line and the date I think would be very useful.

Any chance you could implement an rcs annotate in RcsLite?? Yeah I know it would probably be better called RcsLite+ then, but I cant help myself...

-- JohnCavanaugh - 25 Feb 2002

Certainly sounds possible, but I'd look to do it so that it would work for Rcs and RcsLite. I was already looking to have more options for diff output, this sounds very similar. Initially (at least) RcsLite is likely to be slower than RCS, in part because I'm not putting effort into efficiency.

-- JohnTalintyre - 26 Feb 2002

I'm now able to perform viewing of revisions, adding new ones and doing diffs via Rcs and RcsLite wrapper. I've current altered =TWiki.cfg as follows:

# For Rcs
$dataImpl = "Rcs";
#$dataImpl = "RcsLite";
@dataSettings = 
  ( dataDir => $TWiki::dataDir,
    pubDir  => $TWiki::pubDir,
    ciCmd   => "$rcsDir/ci $rcsArg -q -l -m$cmdQuote

RCSLite doesn't work for binary files with 5mb files and more than 4 history changes.

-- Main.SrikanthNagella - 23 Jul 2008
%COMMENT%$cmdQuote -t-none -w$cmdQuote%USERNAME%$cmdQuote %FILENAME%",
    coCmd   => "$rcsDir/co $rcsArg -q -p%REVISION% %FILENAME%",
    histCmd => "$rcsDir/rlog $rcsArg -h %FILENAME%",
    diffCmd => "$rcsDir/rcsdiff $rcsArg -q -w -B -r%REVISION1% -r%REVISION2% %FILENAME%",
    breakLockCmd => "$rcsDir/rcs $rcsArg -q -l -M %FILENAME%",
    nullDev => $nulldev
  );

# For RcsLite
$dataImpl = "RcsLite";
@dataSettings = 
  ( dataDir => $TWiki::dataDir,
    pubDir  => $TWiki::pubDir
  );

Sounds okay?

-- JohnTalintyre - 28 Feb 2002

This will be very useful under ModPerl, where the rdiff script in particular can avoid forking one rcsdiff and a couple of co commands for every revision in the RCS file! Particularly slow under Windows.

I can see that it's more elegant to put things into the @dataSettings structure, but it would be nice if we could avoid changing the variable names used in TWiki.cfg (as you have done for a couple of variables). While these names are mainly used by Store.pm, they are also referenced in many Codev pages, in documentation such as TWikiInstallationGuide and WindowsInstallCookbook, and by testenv, which I have just managed to get running under use strict (not yet uploaded, but will be at CookbookActivePerlTestenv - also detects mod_perl etc.)

However, that's all very short term, and I imagine you are thinking ahead to other storage backends, e.g. databases... So maybe we should just bit the bullet, as long as the variable names don't change format again!

-- RichardDonkin - 02 Mar 2002

Yes, thought was to support different storage backends. However, as you point out, should only change once and so it will be worth making sure that all storage related settings move to the new format.

-- JohnTalintyre - 03 Mar 2002

This is working fairly well now, but is not yet robust enough to deal with deltas for binary attachments.

-- JohnTalintyre - 27 Mar 2002

Now much improved, especially after I realised I'd made dealing with line endings far more complicated than it needed to be. Should now work fine for binary files. There a large set of tests in tools\test\rcslitetest, they all pass.

-- JohnTalintyre - 07 Apr 2002

Can I use RcsLite to install TWiki on a host where I don't have shell access (and therefore no RCS or GCC)? As near as I can tell all of the other installation and configuration tasks can be done without shell access. Is this correct?

-- MattWilkie - 28 Apr 2002

RcsLite is definitely suitable where RCS and GCC are not available, though it has not been as heavily tested on live servers as the RCS version of the code. To get round not having Telnet/shell access, see the CGItelnet script on TWikiDebugging, which works pretty well.

-- RichardDonkin - 28 Apr 2002

I didn't have any luck with CGItelnet on my host. Unfortunately the error message is so general I have no idea where to start debugging. In any case I've decided to go ahead and try TWiki+RcsLite.

...keeping my fingers crossed...

-- MattWilkie - 29 Apr 2002

Good luck with this and please let me know of any problems. I would currently regard RcsLite as beta quality - so please be careful before you entrust much data to it.

-- JohnTalintyre - 30 Apr 2002

I think I'm missing something: I have downloaded the newest version of rcslite from sourceforge and put it in ../TWiki/lib/Store/RcsLite.pm, RcsWrap.pm and RcsFile.pm. Then I changed my TWiki.cfg as shown above. But that can't be all I have to do because nothing happens with rcslite. What is missing? May you can give a little bit more "hands on" instructions?

-- HardyHaardt - 30 Apr 2002

You probably need to download the whole TWikiAlphaRelease rather than just the RcsLite files - I'm not sure if these would work with some other release, in fact they probably won't because Store.pm has been changed quite a lot.

-- RichardDonkin - 01 May 2002

I have a semi-working install of RcsLite, see RcsLiteTest

-- MattWilkie - 05 May 2002

How production-ready would you consider RcsLite to be? Are there any known problems?

-- MartinCleaver - 25 Jul 2002

I'm not aware of any outstanding bugs, but I think a lot more testing by many users is needed before I would say this was production ready.

-- JohnTalintyre - 29 Jul 2002

Check out UsingRCSDirectoryResultsInInitalVersionAndBrokenDiff for another feature of RCS that is very useful regarding checkin's where the file is a symbolic link. Rcs preserves the link. I claim that RcsLite should as well.

-- JohnRouillard - 15 Aug 2002

As of today (just before the BeijingRelease) how reliable would you describe using RcsLite? What can we say in the documentation about it, if anything?

Thanks,

-- GrantBow - 12 Jan 2003

I'm using the RCS binaries from ModPerlWindows - they take an age to complete many functions and my load is really high. I am therefore quite keen to push ahead with RcsLite.

One snag: I encountered a problem with RcsLite on Windows today. A zip file is attached. There are four files - two outputs from TWiki and the associated WebHome.txt and WebHome.txt,v file.

The two outputs are different. The RcsLite one does not produce any output from my history brought over from a UNIX machine, when processed by RCS it works fine. I'm guessing that the RcsLite module perhaps figures out what the line endings are from what it reads from the start of the file and then continues to process the rest accordingly. RCS does not do the same.

Whether this is a bug or not is debatable. I don't expect anyone to fix it. I just figured it should be documented.

-- MartinCleaver - 16 Jul 2003

I've been looking at the discussion around this extension, and I agree that RSSLite would be the greatest plugin as a package. TWiki is a great app, easy to install, but for users that use a hoster that does not have RSS pre-installed; it becomes a nightmare. I for sure know about computers, but am not a Linux developer or adming by any stretch. The way RSS needs to be installed is beyond my level (I can't even read the only doc/help that seems to be stuck in help files). So here I am, I can't figure out how to install RSSLite, since it is not packaged, and can't install RSS. So the only solution is to change hosters..... I've installed Twiki with other hosters, but having to move sites because of TWiki-RSS problems is a pity at best. All the blocks of RSSlite are there, if someone could please indicate how to use those and what to change where, that would be really really nice. I'll help where I can to go from there.

-- BartLouwagie - 17 Nov 2004

RcsLite is already distributed with Twiki. To enable it you need to change the TWiki.cfg file. Here is the relevant section (around line 201 in the cairo distribution):

# Choice and configuration of Storage implementation
# Currently select either:
# RcsWrap - use RCS executables, see TWiki::Store::RcsWrap.pm for explanation of storeSettings
# RcsLite - use a 100% Perl simplified implementation of Perl
$storeTopicImpl = "RcsWrap"; 
#$storeTopicImpl = "RcsLite";

just comment the "RcsWrap" line and uncomment the "RcsLite" line and you're ready to go

-- RafaelAlvarez - 17 Nov 2004

Thank you so much for that tip. To help others in their install; may I thus suggest the following change in Main/testenv.pl around line 645

From:

# Check RCS
if( ! ( -e "$rcsDir/ci$exeSuffix" ) ) {
    # RCS not installed
    print "<tr><th></th><td><b><font color=\"red\">Warning:</font></b> ";
    print "RCS program <tt>$rcsDir/ci$exeSuffix</tt> not found. Check \$rcsDir setting in TWiki.cfg. ";
    print "TWiki will not work (unless you are ";
    print "using TWiki's built-in RCS implementation, <b>RcsLite</b>).";
    print "</td></tr>\n";

to

# Check RCS
if( ! ( -e "$rcsDir/ci$exeSuffix" ) ) {
    # RCS not installed
    print "<tr><th></th><td><b><font color=\"red\">Warning:</font></b> ";
    print "RCS program <tt>$rcsDir/ci$exeSuffix</tt> not found. Check \$rcsDir setting in TWiki.cfg. ";
    print "TWiki will not work (unless you are ";
    print "using TWiki's built-in RCS implementation, <b>RcsLite</b>).<br>";
    print "To enable RCSLite you need to change the TWiki.cfg file around line 210 where you <br>";
    print "comment out a line to become: <b>#$storeTopicImpl = \"RcsWrap\";</b> and<br> "; 
    print "uncomment a line to become: <b>$storeTopicImpl = \"RcsLite\";</b>";
    print "</td></tr>\n";

-- BartLouwagie - 17 Nov 2004

The installation guide currently says that, as of April 2002, RcsLite had not been widely tested. I presume that I has by now, but the TWiki.cfg file that comes with the latest stable release of TWiki (sept 2004?) says that it is not yet recommended for production use. How buggy is it expected to me at this stage? Besides Martin's comment above I see no indication that it doesn't work well..or works well. I guess many would like to know, because TWiki is really slow on windows. A perl replacement of RCS running under mod_perl would surely perform much better. (BTW, this topic is classified as "FeatureUnderConstruction".)

-- DavidBourget - 22 Jan 2005

I believe all the known issues are fixed, RCS Lite can be used in a production environment. As usual, please file a BugReport in case you find any issue.

-- PeterThoeny - 23 Jan 2005

Hmmm seems to be a little problem when using RcsLite. In running the testenv and clicking the relock all seems well. Behind the curtain a call is being made to RCS instead of RcsLite (in twiki/lib/TWiki/UI/Manage.pm).

-- DavidCamacho - 29 Sep 2005

The relock was a quick implementation and has problems. Please do the manual relock as described in TWikiInstallationGuide, Step 3: Set File Permissions.

-- PeterThoeny - 29 Sep 2005

Adding a comment for future TWiki installers of secure wiki-s open to the web. I found a problem with making TWiki work with Apache Chroot (specifically the SecChrootDir httpd.conf directive). Trying to use RcsWrap and the system's 'rcs' command gave me an error "mod_security: Access denied with code 403. Error normalising REQUEST_URI: Invalid URL encoding detected: invalid ch\aracters used..." in the Apache error_log file. By using RcsLite all problems disappeared and I can run Apache Chroot with ease. Hopefully enough keywords appear in this note to pop up in someone's search.

-- RichardFreytag - 03 Nov 2006

I also switched to RcsLite when ChrootingTWiki and everything is working perfectly now.

-- KeithHelfrich - 04 Nov 2006

ancient history - was implemented many years ago

-- SvenDowideit - 16 Mar 2010

Commenting is disabled while not logged in