The title of this post pretty much says it all. We were using the PushOK plugin to allow us to check files in and out of our Subversion (SVN) version control system from within Madcap Flare. When we upgraded to 6.0 this broke and we duly reported it to Madcap. After a bit of to-ing and fro-ing of questions/answers with my colleague Graham, Madcap promised to try and fix the issue for the next release.

And, lo and behold, version control is now working again in release 6.1.

Thanks Madcap - much appreciated!

A word of warning for Flare users who also use the Subversion version control system (SVN). The PushOK plugin that provides SVN support in Flare does not work in Flare 6. As a result, although my team have licences for Flare 6, we may stick with Flare 5. If you're considering an upgrade to version 6 you may want to think again if you're currently using the PushOK plugin.

Flare has had built-in version control support for some time now - but only for Microsoft's Team Foundation Server and Visual Source Safe. If you use a non-Microsoft version control system you have to make other arrangements.

If you're a CVS or SVN user then, of course, you can just use something like TortoiseCVS or TortoiseSVN from within Windows Explorer. But in the past Madcap have pointed Flare/SVN users in the direction of the SVNSCC plugin produced by PushOK Software as a solution that allows you more or less the same functionality offered to TFS/VSS users, in terms of being able to work with a source control repository directly within Flare.

This worked OK in Flare 5. It wasn't brilliant, it was a little clunky, but it did work, and it provided real benefits. Specifically it made it easier for writers to update the repository and it made it less likely that you'd forget to get the latest version of a file before starting to work on it. Using the plugin has definitely resulted in fewer version conflicts to resolve.

Unfortunately, after installing Flare 6, try and get the latest version of files and you get this:

Unexpected exception: Access violation - KERNEL32.dll

After clicking OK, the Progress dialog box shows an error message like this:

Querying source control server. This could take several minutes.
: D:\Alistair\ITauthor\Flare-demo-project\itauthorflare\: CustomScc:GetLatestVersion - call failed with error code -15 (Nonspecific error.)

The source control operation finished with warnings and/or errors. Press Close when you are done reviewing the messages.

This is really disappointing for a number of reasons:

• I'd obviously prefer us to use the latest version of Flare rather than having to stick on version 5.
• Flare 6 has been out a few weeks now and the forum shows no positive response from Madcap or indication that they're going to fix this. Yes, I know the plugin is third-party software, but Madcap do not provide their own alternative and have, in the past, suggested SVN users use this plugin: I found out about it via Madcap.
• I had to push to get my purchase request for plugin licences signed off and right now that's looking like a bad decision. I don't want to use something else. I don't want to write off that purchase. I won't get another similar purchase signed off next time.
• I generally have a high regard for Madcap, but in this instance I feel they've let me down. Subversion is not some weird, new, little used system. If you have Microsoft blinkers on you might think that, but you'd be wrong. Subversion has been around since 2000, it's the successor to CVS and is used in software companies around the world.

For more tales of Flare/SVN woes go to: http://forums.madcapsoftware.com/search.php and search for pushok.

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

In my last podcast I talked about a couple of unscripted screencasts I'd recorded for colleagues at work, to show them how to use some Flare extensions I'd created. My question in the podcast was: is something like this (knocked together very quickly) good enough to put in front of paying customers - or potential customers?

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

Madcap have, very sensibly, made it easy for you to add your own buttons to the toolbar of Flare’s WebHelp. You can use these custom buttons to … well, to do pretty much whatever you need them to do, within the power of JavaScript.

In this example, all the new button does is change the h1 heading style, giving it an orange background, but you could have buttons to completely change the whole look and feel of your WebHelp – to give readers some variety – or you could add a button that darkens the window and display a lightbox-style popup containing a video of you juggling cats. You might have more useful applications for this functionality, but you get the picture: the functionality is there for you to use however you want. The trick is how you add a button and then how you make that button call a JavaScript function. After that the rest is down to your own JavaScript/jQuery skills. 

So, the following assumes that each topic page in your WebHelp calls a JavaScript file where you keep all the cool, dynamic stuff you want to do when a reader clicks around in your help files. For example, I have a JavaScript file called MyWebHelp.js that uses a lot of jQuery to do stuff, so the head element of each HTML page in my help projects contains the following:

<script type="text/javascript" src="Resources/JavaScript/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="Resources/JavaScript/MyWebHelp.js"></script>
        

To add a function button to the WebHelp toolbar
    

1. Create an image to serve as the toolbar button and save it as a .gif file.

   If you want the button to change on hover, or when clicked, then you can create 2 additional images for these states.

   These are the 3 images I used in this example:

        

2. In your JavaScript file add a function that you want to call when the toolbar button is clicked. For example, this function (using jQuery) adds an orange background to the h1 heading on the page (pretty useless, I know, but it illustrates the point):

   function makeHeadingOrange() { 
       $('h1').css('background-color','orange');
   }

3. From the Project Organizer in Flare, open the skin you want to modify.
4. Click the Styles tab.
5. Select Toolbar Item.
6. Right-click Toolbar Item and choose Add Class.
7. In the New Style dialog box, enter a name for your button class (for example, makeHeadingOrange).

   

8. Click OK.
9. Expand the Toolbar Item list and select your new class.
10. In the Basic properties for the class, click in the value column for Icon (this will currently be displaying “not set” as its value).
11. Click [Browse for image…] and find the button image you created.

    Notes:
    - When you specify an image it becomes part of the binary project data. The image file itself is not saved as a resource, like your screenshots, so you can only choose one of the existing images that have been absorbed into the project file, or incorporate a new image by browsing for it.
    - The images in this list are not sorted into alphabetical order. New images are simply added to the bottom of the list.

    

12. Choose images for the PressedIcon and HoverIcon properties (you can use the same image for all three states if you want).
13. Add a tooltip – for example, Make main heading orange.
14. In the Type properties for this class set ControlType to Button.
15. Set Onclick to the name of the function you want to call – in my example it’s makeHeadingOrange().

    

16. Click the WebHelp Toolbar tab.

    Your new button class is now shown in the Available list.

17. Move the button class into the Selected list and position as required using the up/down arrows.

    

18. In the section “Custom Javascript to include in Toolbar page”, click Edit.
19. Paste the following into the Toolbar JavaScript dialog box:

    function makeHeadingOrange() {
          parent.frames['body'].makeHeadingOrange();
    } 

    

    This creates a function called makeHeadingOrange which, when called, in turn calls another function called makeHeadingOrange. This second function is the one you added to your main JavaScript file in step 2 of this process. You could call them by different names if you wanted – but I think it’s clearer to call them the same thing. This second function is in a JavaScript file that’s referenced in your topic files and it isn’t directly accessible from the toolbar frame, so the first function (the one you added in Flare) is used to call it from within the context of the frame named “body”. The “body” frame in Flare WebHelp is the main frame within which the help topics are displayed. You could locate the code for the second JavaScript function within the topic HTML itself, but it’s going to be far easier if this function resides in a JavaScript file that you reference in the head of your topic pages.

    You can include as many custom Javascript functions as you want, listed one after the other in this dialog box. When the project is compiled, the text in this box becomes a file called Toolbar.js in the Data/<skin name>/ directory of your WebHelp output.

    So, if you want to, you can have lots of buttons, each calling a different function in your main JavaScript file (via the functions in the Toolbar.js file).

20. Click OK to close the Toolbar JavaScript dialog box.
21. Save your changes.
22. Build the WebHelp target output and test the results.

    Hovering over the button:
     

    Clicking the button: