In this podcast I describe why Acrobat shared review is so good and why the closest things I could find (WebNotes and SharedCopy) just don't do what I'm looking for.

Links

• Acrobat Pro: http://www.adobe.com/products/acrobatpro.html
   
• WebNotes: http://www.webnotes.net/
  
• SharedCopy: http://sharedcopy.com/
  

This video shows how to configure and create a shared review in Acrobat Pro. Because it goes through the configuration steps for setting things up, it makes it all look much more time-consuming than it actually is. Once you've set this up, generating the shared review is simple. We used the same internal server approach demonstrated here (using a WebDav folder on the server) and it works really well for us.

Answer: download and install the free, open source alternative to Illustrator:
 
http://www.inkscape.org/download/

Inkscape allows you to import Illustrator-format .ai files. You can then edit the diagram in Inkscape and output a new .png or .emf for the manual.

The only problems I found doing this were:

1. Text entered in Illustrator will typically have some automatic kerning added to make it look just right. Inkscape can’t handle kerning and you won’t be able to edit the text until you remove it. So you need to select the text you want to edit and choose Text > Remove Manual Kerns.
2. Inkscape add lots of object groups. Things are grouped within other things within other groups within other groups … So, to move individual objects around you need to click on the thing you want to move (which will usually select everything in the diagram) and keep pressing Ctrl + Shift + G until enough of the groups are ungrouped and you can see a dotted selection box around the object you want to move.

I really like Inkscape. It does most of the things you can do in Illustrator – in a slightly clunky way perhaps, but it’s a powerful tool and will allow you to produce professional-looking diagrams.

If you just want to create diagrams from scratch and you don’t need to edit existing Illustrator diagrams, you might prefer to try out a true Web 2.0 solution instead: Raven – one of the suite of image tools from Aviary.

Raven is a free online vector design tool that works completely within the browser. It’s got a very good-looking interface and I found its Bezier curve editing much easier to use than the same thing in Inkscape. But, because some of the functionality is happening on the server side, you have to put up with a little delay uploading and downloading files to and from the server if you’re going to be creating and maintaining them in Raven. For a browser app, though, it’s a pretty amazing piece of coding and design work.

I only create simple diagrams, but if you’re a bit of an artist you should have a look at this video to see what you can do in Raven:

And if you’re looking for a free alternative to Photoshop or SnagIt, check out what else Aviary does in the browser:

As it happened, the only thing that used Times New Roman in the template I was using was page number in the index. These came out with hash marks followed by numbers that were completely different from the numbers in the original index:

I went into Control Panel > Fonts and deleted the Times New Roman fonts, then downloaded new versions from typedfont.com.

Note: If you’re using typedfont.com you might not, at first sight, notice the download link. It’s a little link halfway down the page, just above the font table:

However, after installing the new fonts (in Vista: right-click the font file and choose Install), the problem remained.

The problem is that when there’s a font problem the printer’s Font Substitution Table gets modified, telling the driver to use another font instead of the font that has a problem. You can repair the font, but the Font Substitution Table doesn’t get modified back to remove the substitution. You’ve got to do that yourself.

To remove the font substitution for a printer (in my case the Adobe PDF “printer”):

1. Go to Control Panel > Printers.
2. Right-click the affected printer and choose Properties.
3. In the Properties dialog box, go to the Device Settings tab.
4. Expand the section headed Font Substitution Table:

     

5. Find the affected font.
6. Click the substituted font and change the setting back to <Don’t Substitute>:

   

7. Click OK.
8. While you’re about it – for good measure – go to the General tab.
9. Click Printing Preferences.
10. In the Printing Preferences dialog box, go to the Paper/Quality tab.
11. Click Advanced:

    

12. In the Advance Options dialog box, change the TrueType Font setting to Download as Softfont:

    

13. Change the PostScript Output Option to Optimize for Portability.
14. Change the TrueType Font Download Option to Outline.
15. Click OK on all the open dialog boxes.

If you were having the same problem I was having, it will now be fixed.

Note: I’ve changed the names.

From: Lesley …
Sent: 10 March 2009 15:00
To: 'Alistair Christie'
Subject: best tool for the job?

Alistair,

I have a requirement to capture a demo the solutions team has been working on – all screen activity and voiceover.  What I want to be able to do is give this to the sales team along with the kit so they can do the demos themselves.  I also want to take this file and have our designers create a flash movie for download from the web site.

I wanted to ask your advice on the best tool to use for this job?  I have looked at GoTo Meeting and Webex Meeting recorders as well as Camtasia.

My slight problem is that Mike is my voiceover person and Ben is my demo click through person – both based in different locations.  This is why I looked at webinar software for recording but it doesn’t look like its straightforward to record voice and clicks on screen in multi locations.

Any advice/hints or tips – I know you have carried out this kind of thing before.

Thanks,
Lesley

Lesley

Here's how I've done this before. You're probably not going to like this! But you asked.

I've never been able to do voice over + what's on screen in one go. One of them always goes wrong. So the system I settled on is as follows:

1) Write the script!

I've tried improvising but you end up with lots of editing to do, so it's quicker to spend the time up front writing a complete script (word for word, not notes).

2) Go through the demo speaking the script and recording what's on screen - but concentrate on getting the screen capture right. I usually don't even bother recording the voice at this stage. That way, if you make a slip with the voice you just stop clicking/moving the mouse until you're ready to pick up the script again, make a note of the time, then continue (i.e. just keep the screen capture rolling). That way you can go and edit out a bit from the screen capture.

3) When you've captured the screen stuff OK and you're happy with it, go into Camtasia and chop out the bits you noted down. When you do this you've got to go through that bit of the script so that you make sure you haven't cut too much out.

4) In Camtasia, generate a video (Flash or AVI or whatever - doesn't matter at this stage).

5) Using sound recording software (like Audacity, which if free), record yourself speaking through the script while watching the video. You generally have to do this a few times until you get the timing right.

6) Save the recording as a .wav or .mp3.

7) Back in Camtasia, import the sound recording and drag it onto the time line of the video.

8) Play through the whole thing and make sure the sound and video match up. Usually at this stage you need to do some fine tuning, but Camtasia allows you to pause or cut the video and/or pause or cut the sound recording, so it's pretty easy to get it all spot on

9) Output the final demo video.

Camtasia has a huge variety of output formats, resolutions, styles - including .wmv for showing in Windows Media Player, .m4v or .mov for iTunes, or a .swf (Flash) file nicely embedded in a Web page. If you want you can easily grab the Flash file from this page and stick it in another page (e.g. on the company Web site).

Technically there's nothing to it, but if you want to produce something half decent it will take lots of time and patience. The one I did for … last year took 3 full days to produce.

As for folks being in separate places, that shouldn't be difficult, Mike can be on the phone speaking the script, looking at what Ben's doing on screen (Acrobat ConnectNow is good for this - like WebEx but free), while Ben records what he's doing in Camtasia. Ben can then put together the video (without sound) and send this to Mike for him to record the voice over. When Mike's got this just right he can send the sound file back to Ben and Ben can finish it off.

Job's a good un!

Alistair

Just an idle thought.

I just installed the Twitter Notify plug-in for Live Writer and I’m about to see how it works. The idea is that when you post to your blog a dialog box pops up with some boiler plate words, the blog post and a TinyURL. You can modify the template, and you can edit the message before it gets tweeted - or at least I’m hoping you can. Let’s find out.

What she said (about 24 minutes into the show), while discussing Charlene Li and Josh Bernoff’s book Groundswell, was:

There’s this ladder of involvement in social media. Some people like to write blog entries. Some people only like to comment on blog entries. Some people like to review products. Some people just like to read other people’s reviews and act on that review.

I’m an occasional blogger. Sometimes I’ll post every day, other times months will go by and I don’t post at all (usually when I’m up to my eyeballs at work). In some ways I admire the committed bloggers who write lengthy and well thought out posts every day without fail – and sometimes more than one a day. But I do often wonder why they’re spending so much time and thought on this rather than on their paid employment, or their family.

I’m also an occasional blog reader. I use Feedblitz to mail me posts from lots of blogs, but a lot of the time I just read the summaries and never the whole blog post, or I just delete the email without reading anything. My reason for not reading more blog posts is that I know that if I didn’t ration myself quite strictly I could easily spend several hours a day doing nothing else but reading blogs.

What I’m not is a commenter. I rarely ever comment on blog posts and as for forums, I can’t remember ever answering a question on a forum. And this makes me feel bad for two reasons:

1. I love it when people email me, or add a comment to my blog, with a point about something I’ve said in a post, or on a podcast. However, I rarely ever contact the writers/hosts of the blogs/podcasts I enjoy reading/listening to regularly. So they never know I’m out here, one of an invisible audience, enjoying their work. I really should do something about that!
2. I don’t use forums except as a last resort – at which times they often prove invaluable. I have some questions out in forums at the moment as part of my search for the right online help architecture/method for our new applications. And I remember back in 2002 when I was doing some pretty hairy stuff with RoboHelp, I got a lot of help on the Help forums from people like Rick Stone, Rob Chandler and Char James-Tanny. But I’ve never felt any inclination to become an MVP of anything myself and watch the forums on the lookout for people to help.

Am I just a bad, self-centred person?

Well, no, I don’t think so. For me it’s all about a balance of guilt. I hate spending much time at work doing anything that’s not what I’m being paid to do. I pretty much feel like my company has bought my time from nine to five (with an hour off for lunch) and therefore they own my labour during those hours and if I’m writing a blog post or helping someone on a forum I’m essentially cheating my employers. So I make every effort not to be drawn into this kind of thing, and if it does happen I make sure I work extra hours at the end of the day to make up for it. I think this is the generations-old Calvinistic influence showing through.

And when I’m not in work I feel guilty if I spend too much time blogging or preparing podcasts, because I have a wife and kids who deserve some of my time and attention. So once I’ve done some blogging and some podcasting, that just doesn’t leave much time for anything else that would take me away from my family.

Or maybe I’m over-complicating things. Maybe, as Ann Gentle suggests, it simply that there are some people who mainly just blog, some people who mainly comment and some people who never blog or comment.

About six years ago we got a new manager at work and he had trouble with all the names and acronyms we use. He asked me to put together a Web page of terms and explanations for our intranet. But - without doing any consumer research - I thought I’d go one better and, using a vast amount of home brewed Perl and Javascript, I construct a Glossary site that was essentially a Web front end for a little database. Anyone in the company could add new glossary terms and definitions or edit existing ones. I spent quite a bit of time on it (my own personal time because the guilt thing prevented me from effectively charging the company for my work on this), and the end product was pretty damned good and did things like emailing specified addresses every time a change was made (because I was a little bit worried that a loginless system would tempt someone to go in there are write scurrilous definitions). However, in six years, although I know people (mainly new-starts) refer to it, no one but me ever adds or changes anything. It’s exactly like me and Wikipedia. On average I probably use Wikipedia a few times a week and have done for years. But I’ve never ever edited or added a single thing. I’m not proud of this, I’ve just never felt any desire or obligation to do so.

Communications from DMN:
Talking shop with Anne Gentle

So I’ve been having a dig around on Madcap’s forums and I came across a really interesting discussion (starting in November 2006 and, currently, ending in December last year). This centres around Madcap’s in-your-face branding of their .NET Help Viewer. It had the following problems:

• A big Madcap splash screen that was displayed every time you started up the help,
• Madcap branding on the title bar of the Viewer – rather than the name of the help project.
• Madcap branding in the Help menu called from within the Viewer.

There is much lively discussion in the string of messages. One contributor makes the point that there is no earthly point in Madcap promoting themselves in a Help system that is not going anywhere near anyone who would ever buy, or be remotely interested in, Flare or any other technical authoring application. Another contributor makes the point that I’m sure I would face: customers running a mission-critical IT system do not want to see a big, jokey splash screen suddenly appearing. It reeks of malware! Even the name “Madcap” would set teeth grinding if it appeared in the applications my company produces.

Finally, bowing to the weight and vehemence of the postings, Madcap gets around to providing a way of disabling the splash screen – but no word on configuring the title bar text and icon. As for the help menu, I think there’s a workaround.

One of the interesting things, reading through this, was the exasperation evident in the postings. People really, really wanted to use this product but were unable to because Madcap couldn’t go that extra mile (or 100 yards) for them. And the change from vitriol to delight and gratitude when Madcap staff contributed to the discussion with some positive news was quite touching, although it did seem a bit like: “Thank you for making it possible for us to use your product!”

I'm hoping for some advice on a way to provide server-based online help. The trouble is it can't be Web-based. Does anyone know of something out there that would solve this problem?

We've got a client/server software application that needs user assistance. It can't be traditional client-side HTML Help because this leaves help files on the PC, which not good for us because of the confidential nature of parts of the IT system. For a similar reason (plus some technical reasons) it can't be Web help.

What I'm looking for is a help viewer that will be launched from within a client application but which will fetch it's help topics from the same secure server used by other parts of the application. The help viewer can be located on the client side, but the help topics must be pulled down from the server.

I have had a look at Adobe AIR Help, but this seems to download files to the client and leave them there for use next time, which is no good for our purposes. I have also had a look at Madcap Flare's .NET Help, but I think this is also client-side, plus Madcap supplies very little information about .NET Help which worries me because I'd rather not migrate to a system/method that is poorly documented (unlike HTML Help or Webhelp output from Flare, which is well documented).

So I'm looking for ideas. Am I missing something obvious? Can anyone suggest a solution? Please post a comment below.

It just so happened that, today, I'm collating some review comments on some release notes I wrote. I have three copies of a Word document and I need to merge the comments into a single document. The TextFlow video promised that it could do just what I was needing to do and would make my life easier. I therefore took the time to register for the beta and install the software.

The problem when you try it out is that TextFlow destroys the formatting in your Word documents and any images and tables simply disappear.

Now, okay, it's beta software. But Google and others have changed the definition of beta software. Just a few years ago "beta" meant the software was well short of release quality and you could expect it to contain bugs and missing chunks of functionality. The Gmail beta is an example of software that was perfectly usable, and used day in day out by millions of users, for a long time while it was still labelled a beta.

TextFlow, on the other hand, is an old-fashioned beta. Interesting to try out. But not much use for any serious use yet. The real problem is that the demo has left me seriously hacked off, with a very negative feeling towards the makers of TextFlow. If they'd just been a bit more honest about what the product can't yet do I wouldn't be left feeling duped by the video.

I thought it would be interesting to check how many other broken links there were throughout my blog. I remembered writing about a link checker and a quick search revealed it was almost exactly five years ago. More interesting though is that the a) the Web page for Xenu looks just as I remember it in 2003 b) you can still download Xenu free of charge c) it runs fine on Vista and d) although it's a no-frills application it's an extremely thorough and effective way to identify broken links buried deep within a Web site. 

One nice feature is that at the end of the check you can output a report as a Web page that contains list of all the broken links and the pages they appear on (which you can click on to check the page) and another list of all the pages containing broken links - it's useful to have both orders because you probably want to check through page by page, but it's also useful to identify multiple broken links for pages on a particular domain.

Download Xenu from here:

http://home.snafu.de/tilman/xenulink.html#Download

There's an interesting page about The Story of Xenu Link Sleuth which reveals how the program was written by Tilman Hausherr in 1997.

Incidentally, when I ran it against www.itauthor.com today, Xenu reported that I had 2363 links, and just under 200 of them are currently broken:

ok	2167 URLs	91.71%
not found	162 URLs	6.86%
no such host	8 URLs	0.34%
no connection	5 URLs	0.21%
forbidden request	12 URLs	0.51%
skip type	1 URLs	0.04%
the resource is no longer available	2 URLs	0.08%
auth required	1 URLs	0.04%
temporarily overloaded	3 URLs	0.13%
timeout	1 URLs	0.04%
precondition given in request failed	1 URLs	0.04%
Total	2363 URLs	100.00%

]]> http://www.itauthor.com/2008/11/29/xenu-link-checker-5-years-on/feed/ 0 http://www.itauthor.com/2008/11/23/itauthor-podcast-21-three-generations-of-computer-users-part-2/ http://www.itauthor.com/2008/11/23/itauthor-podcast-21-three-generations-of-computer-users-part-2/#comments Sun, 23 Nov 2008 22:44:21 +0000 ac /?p=734 I wanted to find out how people of different generations use computers, what they use their computers for, how they use them and what they feel about computers and software generally. So who better to ask than three generations of women from my family.

In this, the second in a series of three podcasts, I talk to my 17-year-old daughter, Martha Christie about how she uses computers at school and at home.

Of online help Martha says:

"Those things drive me crazy. I don't think I've ever actually used any of those help systems for anything on the computer. I just don't find them useful at all.
...
There's so much writing to read and I hate that kind of thing. It's like ... if you get like a help manual with something you just throw it away before you start
...
I just can't read through it all. I'd rather just try it and then if it goes wrong I just scrap it and start again."

On the most effective way of learning, she says:

"If you want to learn something, asking a person is the best way to do it."

"I don't think I just want to be told the answer ... Getting something explained to you and getting it shown to you is different from just getting told an answer. Like if I asked a teacher for help and they just told me the answer, I wouldn't be like: 'Oh that's great, thanks' ... The best teachers don't tell you an answer - they tell you how to find the answer yourself."

She makes an interesting point about how when she wants to do something on the computer she'd naturally try and use one of the applications that are already on the computer - even if it wasn't purpose built for the thing she wanted to do - rather than search for, download and install a new application from the Internet.

I also found it revealing that she wasn't aware that most help systems for applications have an index and a search facility.

She didn't like the idea of help videos, because she wouldn't want to sit through a whole video to find out how to do something.

Finally, she's also the only person I know who's ever had anything good to say about the Microsoft Office Assistant dog. 

One of the software applications mentioned in the interview is:

Painter Classic
Metacreations Painter Classic came bundled with a Wacom tablet I bought years ago. Used with a drawing tablet it was a very impressive bit of software. Corel bought Metacreations and the latest incarnation of that software is Painter X (i.e. version 10).

http://www.corel.com/servlet/Satellite/gb/en/Product/1166553885783

This is one of the paintings Martha created using Painter Classic, in 2003, when she was twelve:

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:


comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:


http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

I love keyboard shortcuts. Each little shortcut saves you a few seconds and over a year that's a lot less time spent clicking around, choosing from menus and more time being productive. It's all about getting on with the stuff you want to be getting on with, and spending less time/effort just getting there.

So here's a good one. Texter is a little application written by someone at LifeHacker. When you run it it sits in your system tray and replaces predefined sets of characters with longer text. So if you type the same thing several times a day, you can type a few characters and it's automatically replaced by your name as you type. For example, to type Alistair Christie I could just type ac, hit the Enter key and ac is replaced by my name.

If you're a coder you'll probably find this particularly useful as it lets you enter big chunks of code with just a few key presses.

Download Texter from the Download link on the Texter home page.

Important

• Go to the Preferences and turn off Enable Universal Spelling AutoCorrect. It's clearly supposed to work on whole words to correct spelling, but unfortunately it corrects before you've finished writing a word. For example, if you try to write agree, as soon as you get as far as agre it changes the word to agree, which means you end up with agreee. Similarly, if you try to write another you get aanother. This maybe works on some platforms, but on my Vista laptop it's obviously broken. But no matter, Texter is fine without this.
• Replacements don't work everywhere. For example, they don't work in the Run dialog box. From what I've read, this used to work in XP, but doesn't in Vista. Shame, because it would be useful to be able to run a program by just typing a few characters in any application.

Jing is a cut-down version of Camtasia that provides a quick way to record a screen capture video and audio recording and then share it, for example on a blog. The real benefit of this is that, rather than writing out procedural steps you can quickly record a "here's how it's done" mini-demo and post it - e.g. onto SharePoint - for people in your team or organisation to view.

Makers TechSmith have a simple little animation that explains the benefits of Jing very nicely:

http://www.pcpro.co.uk/reviews/137286/adobe-framemaker-8.html

For the most part it sounds like users of 7.2 (like myself) wouldn't notice much of a difference. However, the thing that intrigues me is the ability to incorporate Flash movies into documents. When I'd heard of this, months ago, I'd thought: okay but what's the point in that? However, Tom Arah's description suddenly reveals how great that might be:

... this hardly seems like rich media, since the 3D models and vector movies are represented in the FrameMaker document as static bitmaps. Everything changes, though, when you export your document to PDF. Suddenly, when viewed within Adobe Reader, the embedded Flash movie and 3D model spring into interactive life.

Now, suddenly, I can imagine how useful it might be to have a PDF that was designed purely for online viewing and was, perhaps, quite a small document but with a series of inbuilt Flash demos. Anything that's show rather than tell has huge appeal, and this could really transform how we think of PDFs.
 
Screenshot taken from PC Pro website.  © Copyright Dennis Publishing Limited

http://docs.google.com/Doc?id=d9kcf59_11dp5wj2

It's a nice example of how to use Google Docs + a blog to disseminate information to a wider audience.

One of the slides has the following useful set of links to wikified documentation:

Adobe Labs: labs.adobe.com/wiki/index.php/Main_Page
Apache wiki: wiki.apache.org
eBay: www.ebaywiki.com
Microsoft Developer Network (MSDN): msdn2.microsoft.com/en-us/library/default.aspx
Motorola Q: www.motoqwiki.com
Everything Q: wiki.everythingq.com
SplunkBase: www.splunk.com/base
Sun's OpenDS: www.opends.org/wiki
iMIS Community: www.imiscommunity.com

The other excellent addition to Windows Live is a replacement for Windows Picture and Fax Viewer, which, until today, was my default application for viewing image files from Windows Explorer and doing a slideshow. It's called Windows Live Photo Gallery. It does all the stuff Picture Viewer used to do, like rotating your photos and doing a slideshow, but it also makes it really easy to adjust your images, including cropping and resizing them.

If you have a look at my recent post on My podcast recording setup, the photos in there were fixed up using Live Photo Gallery. I took the photos in my poorly lit study, beside a very yellow desk lamp, without any flash lighting. The results were not great, but clicking the Auto Correct button worked wonders and made it look like I'd taken the photos beside a window with plenty of natural light. I also increased the brightness and contrast a little and then cranked up the Sharpness setting to the max just so's the settings on the mixer were as clear as possible. Compare a detail from the original photo and the fixed version:

Original:
 
Fixed:
 
The fixed version is quite grainy because of the artificially high sharpness setting I used, but I think the result are really good, considering the original photos were so poor.

I've always used Photoshop for most image adjusting, but for little quick things like this, I'll be using Live Photo Gallery from now on. By the time Photoshop has loaded I could have done my colour correction, cropping and resizing and posted the results to my blog.

For more information about Windows Live, see:

http://get.live.com/wl/all

http://notepad-plus.sourceforge.net/uk/site.htm

As its name suggests, it's a Notepad replacement aimed at programmers. I recommended JEdit a while back, but I find JEdit is slow to load and memory hungry. Its interface is also very Java-ish, which seems like a nice change to begin with but after a while it starts to feel clunky and unresponsive and you want to get back to native Windows apps. I still use JEdit for Search/Replace, but Notepad++ is good if you want a decent text editor but don't want to pay for UltraEdit.

• Six Reasons to Love Flare
• Six Persistent Flare Problems

I'd agree with the reasons to love Flare, with the exception of what he says about CSS and the XML editor. 

Flare's XML editor

I'm not sure if Paul uses structured FrameMaker but I suspect not because I find it hard to believe anyone who has used FrameMaker's Structure View could think Frame's XML editor anything but seriously flawed. FrameMaker's Structure View is deceptively simple. It works so well, so intuitively, that it's easy not overlook how well conceived it is, until you start using something like Flare's XML editor and you find that:

• you can't multi-select elements
• you can't drag elements anywhere in the structure, just to other places at the same level in the hierarchy and not always then either
• you can't always select elements easily and it's not always clear when you have selected an element
• cutting, pasting and deleting elements is a multi-click operation
• it demands that you use the mouse all the time, so if you're more productive with the keyboard, hard luck
• I could go on ...

Madcap trumpet the XML editor as a feature of Flare, but in reality it's an unfinished feature. It has the feel of something that they got 75% finished and then decided it was good enough, so they moved on to work on other things and never got back to finish the job.

I would give my eye teeth to have FrameMaker's Structure View grafted on to Flare. Because the editor is the place you spend so much of your time, any little drawback, like having to do two extra clicks each time you want to copy or paste an element, in time becomes very wearying - especially when you have a really intuitive interface to compare it with.

On the plus side, I never ever used to use the editor in RoboHelp, preferring to do all my editing in Dreamweaver. With Flare I do use the editor, and it does the job - but like all things you like you want it to be as good as it possibly could be, and the XML editor falls short in some very obvious ways.

Flare's CSS editor

Not much to say on this other than the fact that Flare's interface for editing CSS over-complicates the task of styling up your content. Endless clicking around, scrolling up and down, expanding and contracting sections and searching round for what you need drives you, inevitably, back to the CSS file to edit it in a text editor.

My Flare projects typically have three or four CSS files and by far the easiest way of modifying styles is just to open the files in UltraEdit and edit the text.

When I want to change a font size, or a background colour, I can just type in the new font size or colour, I don't need to fiddle around with the mouse to select the size or colour I want.

I guess it depends what you're looking for, but personally I want to be able to do things quickly and easily. A user interface should facilitate you and help you to be more productive. It shouldn't slow you down, which is what Flare's CSS editor does.

But - to end on a positive note - the good thing about CSS in Flare is that the look of almost everything is driven by CSS, which allows you huge flexibility to determine the appearance of your final output. Apart from a few features of the navigation panes, pretty much everything can be customised to look just the way you want it to look. So if it's important to you to be able to produce something good-looking and different to everyone else's online help, then Flare's definitely worth investigating.

Flare gets pretty close to allowing you to single source, but it still has the following major issues that prevent you from outputting PDFs (via integration with FrameMaker).

1. PDF bookmarks

   There's no effective way of controlling what becomes a bookmark in you PDF. When I output direct to PDF I get some bizarre results. This precludes being able to issue the PDF to a customer. I have to output to FrameMaker, specify the bookmarks and then output the PDF myself. This might not seem too much of a hassle, but the fact is that it means Flare just isn't doing what it claims to be able to do. What I want to be able to do is make a quick change in Flare and output the PDF without having to do anything in FrameMaker at all. At the moment this just isn't possible.

   For those of you debating the value of taking out a Support contract with Madcap, you might be interested to know that this is an issue I queried with Madcap a couple of months back and I still haven't had any word on a resolution of this issue. Is a fix going into the next release. Who knows?

2. Cross-references to another part of the same chapter

   The problem here is that if you have a multi-chapter document, and you create a cross-reference to somewhere in another chapter, it works fine - but if the cross-reference goes to somewhere in the same chapter, the link does not work.

   The reason for the problem is identified in this forum correspondence:

   http://forums.madcapsoftware.com/viewtopic.php?p=18143#18143

   There are two solutions (both ugly):

   a) Output the chapters to MIF, edit the MIF, remove the XRefSrcFile value for the broken links, save the MIF file to FrameMaker format again and generate the PDF.

   b) Search for broken cross-references in FrameMaker, edit the cross-reference, specify the correct marker that it should be pointing to, save the file and generate the PDF.

   Both of these are time-consuming and, again, you need to do this each and every time you make any change to your source files. So, say a button name changes and you need to change a single topic file, this means this one-word change could take you half a day to implement and produce the corrected PDF. That's unacceptable.

3. Hyphenation

   Flare always turns hyphenation on. There's no way of specifying, in the CSS within Flare, whether you want hyphenation or not. So all paragraphs get hyphenation, even when they're unjustified.

   Even headings get hyphenated, which just looks ridiculous.

   And because FrameMaker isn't very smart about hyphenation - that is, it doesn't adjust the word and character spacing in a line in order to avoid hyphenation where possible - it means you get a lot of hyphenation, some of it incredibly clumsy.

   Again, this is something I queried with Madcap weeks ago, under my Support contract, and, despite going back to ask them what's happening, have heard nothing to give me hope that this will be fixed soon.

Conclusion

All of this is very disappointing. As I've said before, I'm a fan of Madcap and I'd like them to do well, but all evidence from them lately leads me to believe they're too busy rushing forwards to the next thing, and trying to stick to their masterplan of producing an Adobe-beating authoring suite, to spend time getting their products to work correctly.

Sadly, this is the same old story we had from eHelp of old. A basically good product, but with lots of really annoying issues for which we, the users, had to work out tortuous workarounds. Would I recommend people buy Flare? Yes, I would and I do. However, I always have to tell them that this is a new product and it still has several very annoying new-product issues.

The trouble is Flare is no longer a new product. It leaves me wondering: how long before I have to stop forgiving Flare on the grounds of being a new product and recommend it - if indeed I do continue to recommend it - on the grounds that it's the least annoying authoring tool available right now.

As well as zip file, you can also create tar file.

Website: http://www.7-zip.org/

User interface:

OK, nightmare might be pushing it a bit in this instance, but severe headache is certainly no exageration.

In this case I'm talking about building WebHelp in Flare 2.5.2. The message that appeared out of the blue was:

The error message might lead you to believe that the problem is one of the files you've been working on. Don't be fooled. I tried taking a backup of my entire project directory and then reverting to a previous version from our Subversion repository, saved prior to the error occurring. It didn't solve the problem.

Neither is it something obvious like a temporary file sitting around somewhere. I tried cleaning out Flare's temporary directories. No good.

Don't bother reinstalling Flare. I tried it. This is a stone cold bug and you need to get the fix from MadCap.

Solution

If you are using Flare 2.5.2 and you get the following error message when you build your output:

"Internal error: Cannot create a file when the file already exists."

You need to download a patched DLL:

http://madcap.vo.llnwd.net/o1/flare020-ke5g/B3.CoreKit.zip

and do this:

1. Unzip this file.
   This produces a file called B3.CoreKit.dll.
2. Exit Flare, if it's running.
3. In Windows Explorer, go to C:\Program Files\MadCap Software\MadCap Flare V2.5\Flare.app (assuming that's where you chose to install Flare).
4. Rename the existing B3.CoreKit.dll file in this directory as B3.CoreKit.ORIGINAL.
5. Copy the new B3.CoreKit.dll file to the C:\Program Files\MadCap Software\MadCap Flare V2.5\Flare.app directory.
6. Restart Flare.

Using Performancing is much more work. You first need to upload the image to the server, then you insert it in the Performancing window, then you publish. Also you only get the image full size. The nice thing about Live Writer is that it does the resizing for you.

But let's see if it works.

Let me just check out some formatting here. No colour, unfortunately, but one of the great things about it is that it allows you to edit existing posts.

The great thing about Flare is that it's easy to add stuff like this on. The bad thing about Flare is that - and this feels a bit like a hang over from the bad old RoboHelp days - the way it's been coded assumes the only files in your project are going to be ones put there by Flare and so it does some weird stuff. For example, if you include XML files in your resources, as I do for my home-grown glossary popups, Flare parses and rewrites these in its own particular way and, very annoyingly, removing the CDATA markers around content so that it is parsed by the XML parser rather than being treated literally so that tags can be passed through to the browser. So my original XML:

<glossentry id="delimit">
  <glossterm>
    <![CDATA[
      Delimit
    ]]>
  </glossterm>
  <glossdef>
    <![CDATA[
      To mark the beginning or end of a query term. Terms are delimited by spaces, punctuation marks, wildcards and special characters such as $, <, ~, # etc.
    ]]>
  </glossdef>
</glossentry>

Becomes:

<glossentry id="delimit">
  <glossterm>
    Delimit
  </glossterm>
  <glossdef>
    To mark the beginning or end of a query term. Terms are delimited by spaces, punctuation marks, wildcards and special characters such as $, <, ~, # etc.
  </glossdef>
</glossentry>

Which screws things up if the content contains characters like '&'.

http://www.adobe.com/cfusion/event/index.cfm?event=register_no_session&id=797489&loc=en_us

Note: You need to register to see this webinar, but registration is free.

The webinar is hosted by Michael Hu (Senior Product Marketing Manager for RoboHelp and FrameMaker) but revolves around a demo of about 30 minutes by RJ Jacquez (Senior Product Evangelist for RoboHelp and FrameMaker).

From what's shown in the demo it looks like RoboHelp 6 catches up with a lot of the things that went into Flare, like better support for conditional elements and variables. It's not a radical upgrade, but with the teething problems and young-product irritations I've come across in Flare, RoboHelp 6 looks like a good option if you like RoboHelp and have held off buying Flare because you knew a new version of RoboHelp was on its way. The biggest thing Adobe have in their favour is the product set. Most tech authors are using other Adobe products like FrameMaker, Illustrator, Photoshop, Dreamweaver, Acrobat and there's the promise that these products will be better integrated in future.

I'm committed to using Flare (because I'm currently using it write WebHelp for a major new software release), but I've also just ordered a copy of RoboHelp 6 for a new member of staff to allow him to work on our existing online help - so I've got a foot in either camp and I've not decided yet which is going to be the best long-term solution.

It's a Java-based application, so you need Java installed (version 1.4 or higher). But, if you don't already have java, there are install packages for Windows and Linux that include the Java Virtual Machine.

Being Java, of course, it works across Windows, Linux, Mac and other UNIXes.

Download from:

www.freexmleditor.com/fxeeditor/downloads.html

Here are some screenshots (click for full-size screenshots).

The main pane is an editor. The helper pane on the left shows the valid attributes and elements at the insertion point

The right-click menu offers you a variety of useful context-sensitive options. For example, you can select text, right-click and wrap the selected text in element tags

Quick access to valid elements by dynamically filtered lists

The Navigator tab shows the structure of the document as a collapsable hierarchy of the elements

You can validate against the referenced DTD at any time

You can reformat the XML (pretty-printing style) - but be warned, doing on a DocBook file produced in FrameMaker removes all of the NOTATION and imagedata ENTITY declarations at the top of the file, which removes the links to your images!

The only thing I looked for and it didn't do was to allow you to do drag and drop of elements in the Navigator tab - like you can do in FrameMaker's Structure View window.

Note:
I said it was "free-ish". What I mean is that it's free for non-commercial use. If you want to use it in a work/commercial environment it currently sells for $130/€110/ £75 (with discounts for bulk purchases). There are lots of XML editors out there, but for  £75 this one's got to be worth it.

As a Flare user I know that MadCap have done a serious amount of work on Flare and come up with a serious bit of software. It's still got a few bugs and oddities, but for a brand new product it is extremely impressive. However, maybe that should have been expected. Some of the top people working on Flare used to work on RoboHelp, and were kicked out by Macromedia, and you get the feeling they were on a Crusade to rebuild RoboHelp but make it better and incorporate all the new stuff they would have liked to have put into RoboHelp but had been prevented from implementing by Macromedia's lack of interest in the product. Now, with these other products, you just wonder how they'll get on, without all that experience and religious zeal to spur them on to more super-human feats of development endeavour.

But, with Blaze, in many ways they've done most of the hard work already. There's still a lot to do to take Flare and use it to create an XML-based tool that does everything FrameMaker does - but it's very do-able and the end result could be just what I for one have been looking for for the past 3 or 4 years.

More about Blaze on MadCap's website:

www.madcapsoftware.com/products/blaze/home.asp

and some interesting observations about Blaze and Flare on the monkeyPi blog:

http://monkeypi.net/?p=40

http://monkeypi.net/?p=61

Madcap's Marketing department have produced a flier describing what version 2.0 will offer:

www.madcapsoftware.com/support/files/downloads/mc_flare_v2.pdf

To quote the hype:

"Flare will be the first true single-sourcing tool with the ability to import and export in both Microsoft Word and FrameMaker formats. Nobody else comes even close."

I also mention an error message I got when switching back to the normal view from the tag view:

http://madcapsoftware.com/products/demos.asp#

My thoughts on this demo are mixed.

My immediate thought was what a dull demo it is without sound. Well, in fact it does have sound, the sound of mouse clicks, but not speaking. Having looked at a lot of screencasts recently (particularly those of Jon Udell) silent demos like this with balloon text that you need to read are just so dull and lifeless. Compare it with Robert Scoble's off-the-cuff interview of, and Office 12 demo, by Julie Larson-Green for Channel9:

http://channel9.msdn.com/showpost.aspx?postid=114720

My next thought was that I was pleased to see the structure feature being touted as a product feature and being included in a well thought-out and nicely designed way. However, I'm also a little bit concerned because one of my fears about Flare is that it feels like it might be being developed with the same dummed-down, "let's keep it simple for the users (they won't understand anything that's not graphical or drag-and-drop)" approach that plagued early versions of RoboHelp. Only latterly did RoboHelp start to escape this "we know better than you, so we'll do stuff for you (whether you want it or not)" mentality. In my experience the main users of RoboHelp (and in the future Flare) are technical authors who know all about XML and XHTML and CSS and JavaScript and header files. I'm a little worried that Flare might be very good-looking application that doesn't offer much in the way of functionality we don't already have. What I'm hoping for is an application that maybe won't be that single-source solution we're all looking for, but will be a key component of a single-source solution.

When it comes to ways of showing the structure of a document that's one thing that FrameMaker 7 does well. I really like the variety of ways FrameMaker has of showing structure: in an expand/collapse diagram, as tagged text, as text with element markers, in the status bar, etc.

I don't want to be negative about Flare before I've even seen it, but we're at this pivotal point as technical authors, with both of our main tools (FrameMaker and RoboHelp) being left to wither and die, and a huge need for a new kind of tool to deliver on the list of requirements that technical authors have for a new tool - requirements we know can be delivered built on XML. When I first heard about Madcap I pinned significant hopes on it being the company to deliver the killer app for our profession. I hope they can, but the more I hear about Flare the more I worry that it's just going to be a new version of RoboHelp, rather than the successor to RoboHelp and FrameMaker.

cvs [update aborted]: cannot rename file _new_myhelpfile.chm to myhelpfile.chm: Permission denied

in WinCVS, or:

Unable to rename file _new_myhelpfile.chm to myhelpfile.chm for 1 second, still trying...
Unable to rename file _new_myhelpfile.chm to myhelpfile.chm for 2 seconds, still trying...

in TortoiseCVS, it means that some other program on your computer is using the file in question and preventing CVS from overwriting it.

In the example above, myhelpfile.chm is an HTML Help file, so the chances are that the file is currently open in a Help viewer (or perhaps being used by RoboHelp or HTML Help Workshop). Exit whatever program has a lock on the file and you will be able to update it successfully.

Get the software

If you've got a 1.x version of WinCVS, uninstall it now and restart your computer.

Download & install the latest stable version of WinCVS from:
www.wincvs.org

At the end of the install, the installer will tell you if it can't find Python. If you don't have python, download & install the latest stable version from:
www.python.org/download

The following instructions assume you already have PuTTY and you already use it for SSH connections to the remote network (which I'll assume is your office).

If you don't have PuTTY, you can download it from:
www.chiark.greenend.org.uk/~sgtatham/putty/download.html

Port forward the CVS port

Set up a new tunnel in PuTTY (i.e. forward a local port to a port on a remote computer).

By default the CVS server listens for connections on port 2401 and this is the port to which WinCVS talks. You therefore have to forward port 2401 on the local machine (127.0.0.1) to port 2401 on the remote CVS server (e.g. cvs.yourcompany.co.uk).

To do this in PuTTY:

1. Load the session that you use to connect to the remote network (e.g. you office network).

   I'm assuming you already SSH to this network so you have already set up and saved the settings for a login session to this network in PuTTY.

2. In the left pane, go to Connection > SSH > Tunnels.
3. Enter 2401 in the Source Port field.
4. Enter either hostname:2407 or IPaddress:2407 in the Destination field.
5. For example: cvs.yourcompany.co.uk:2407
6. In the left pane, click Session.
7. Click Save.

The next time you use this saved session to login to the remote network, the tunnel will be established, so that anything sent to port 2407 on your local computer will be forwarded through to port 2407 on the CVS server on the remote network.

Setting up WinCVS

If you're upgrading from an old version of WinCVS you will notice that the CVSROOT is no longer specified in the Admin > Preferences dialog box. It's now in the Admin > Login dialog box.

:pserver:[username]@[servername]:/[path]

For example:

:pserver:john@cvs:/yourcompany/repository

WinCVS sends the above login request to the server as the command:

cvs -d :pserver:john@cvs:/yourcompany/repository login

This is what you would enter if you were using CVS from a command line.

If you try to log in now, the login will fail because your computer will not be able to find the host you are trying to connect to. In the above example, the server name is cvs. Your computer needs some way of resolving this host name to an IP address. You do this using the Windows hosts file.

Use a text editor to edit the hosts file. This usually resides in the directory:

[Windows installation directory]\system32\drivers\etc
e.g.
C:\WINDOWS\system32\drivers\etc

At the end of this file add:

127.0.0.1  [server name]          # Your comment

For example:

127.0.0.1  cvs                    # Map this host name to the local host
127.0.0.1  cvs.yourcompany.co.uk  # Map this domain to the local host

Save the file.

Now, when you try to access a server named cvs or a domain named cvs.yourcompany.co.uk, your computer knows to use the IP address 127.0.0.1, which is the local computer. The name "cvs", in this example, is identical to "localhost" – both are aliases for the IP address 127.0.0.1.

The result of this is that, while you are logged on to the remote network, local port 2407 is forwarded to the remote CVS server, so connections to port 2407 on cvs (in the example above) are directed to the remote server (which, in our example, also happens to be called cvs). Using the hosts file in this way allows you to use the same server name (e.g. "cvs") as you do when you are working on a machine in your office that is part of your office network domain.

Logging in

Usually you can simply log in to the CVS server using your network username/password. However, the server may be set up to use localhost authentication, using its own password file. The server may also be set up to use both types of authentication, trying to authenticate locally first and then falling back on network authentication.

If the server uses local authentication, you must ask the administrator to add your password to the password file. Usually this is done using an encryption program to generate an encrypted password which you then give to the administrator to put in the password file.

A typical scenario would be to use a mkcvspwd program on a networked server to which you *do* have access to:

1. Run the encryption program (using the command mkcvspwd – if that's what it's called and it's in a sensible place like /usr/local/bin, or [path]/[program] if not)
2. Type in the new password twice.
3. Copy the encrypted version that the program supplies.
4. Email this to the administrator and ask him/her to put it in the password file for CVS.

Once you've set up a server-specific password, you obviously must remember it or you won't be able to use CVS. If you forget your password, repeat the above process.

Once you've logged in you can do all the usual CVS stuff, just like you were working on a PC at the remote location: e.g. check out a module, work on a file, update it, commit it.

cvs.exe bug

The one irritation I've come across is that the version of CVS I'm using (WinCVS 2.0.0.2) displays an empty console window each and every time I do something like updating or committing. The window disappears again once the task is finished, but it's annoying that this DOS-like window appears for no apparent reason. This didn't happen in WinCVS 1.3, so I can only assume it's a bug in the current version (though I haven't found any mention of it anywhere).

I tried downloading and installing CVSNT separately, from:
https://secure.march-hare.com/cvspro/

The version I downloaded was 2.5.01.1927 – compared with version 2.0.51d which came with the version of WinCVS I downloaded.

Unfortunately this didn't solve the problem.

http://blogs.pcworld.com/techlog/archives/000614.html

One correspondent makes the observation that, with such a huge product line now, Adobe will not want to spend money developing all of these lines. RoboHelp must surely fall into this bracket. As a product that has not been actively developed over the past few months, and a product that needs a thorough overhaul to be able to produce XML-based Help - e.g. using MAML (Microsoft [User] Assistance Markup Language) - Adobe either need to spend a lot of money on RoboHelp, or its future is bleak.

Adobe may, of course, adopt the same approach to RoboHelp that they have to FrameMaker. Like FrameMaker, RoboHelp is a niche product with a small user-base whose members do not have much choice in the way of alternative products. Adobe have kept FrameMaker on life-support for the past few years and they may choose to do the same with RoboHelp. This provides them with a small but steady income for next to no outlay and, because of the product is so well established in the market, it stifles competition quite effectively, which leaves Adobe's options open should they ever choose to create a replacement product.

www.macromedia.com/macromedia/proom/pr/2005/adobe_macromedia.html

It's going to be very interesting to see what will happen to RoboHelp and Dreamweaver now.

See also my entry on the demise of RoboHelp.

At the time of writing there's an interesting discussion about this on the Macromedia General Discussion forum:
www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=447&threadid=979594&forumid=65

At first it seems odd that Macromedia should spend $65M on aquiring eHelp and then decide not to continue development on eHelp's flagship product. However, probably shouldn't be too surprising. The future of technical documentation is XML-based and many technical authors are looking for tools that will support the creation and maintenance of MAML-based documents. Whatever the eventual successor to FrameMaker and RoboHelp turns out to be (perhaps something from Madcap, perhaps something from ArborText, perhaps something Macromedia have up their sleeves) it will need to be built around MAML, and almost certainly (though perhaps as a by-product rather than a main aim) make DocBook authoring much simpler than it is right now.

I didn't write this (although I might have) - it's from an "open letter to the technical communications community" by Mike Hamilton, former product manager of RoboHelp and now vice president of product management at MadCap Software.

I'd never heard of MadCap Software until this morning, when a Google Alert I have set up to look for articles about FrameMaker directed me to this press release at biz.yahoo.com.

MadCap make heavy play of the fact that some of the founders of this new company used to work on RoboHelp. They are targeting folks like me: technical writers who use RoboHelp and FrameMaker and who would like to be using XML if it wasn't such a faff to set up given the currently available authoring tools.

MadCap's aim is: "to do the same thing for XML authoring that RoboHelp did first for RTF authoring and later for HTML authoring." Everything they mention on their web site sounds good. They obviously know technical writers because they're pushing all the right buttons. However, I've heard stuff like this before - marketing hype that sounds great but when you look closer what they're offering lacks some of the must-haves of FrameMaker in particular. Everyone who uses FrameMaker (particularly if they've tried to use it for XML) knows that it's an application that's way overdue to be toppled off its pedestal by something that's new, purpose-built for XML and is being actively developed (unlike FrameMaker). Maybe MadCap will be the people to do it.

MadCap's product is called Flare. Presumably this will be built around, or at least will be very well-matched for, MAML (the markup scheme Microsoft have developed for Longhorn user assistance). I've noted my interest in the beta - so I'll let you know if I find out more about it.

Marketing flier about Flare:
www.madcapsoftware.com/assets/brochure.swf

Acrobat 6 creates lots and lots of temp files named Acr<hex number>.tmp in Documents and Settings\<user name>\Local Settings\Temp
or in Windows\Temp

The problem is, it doesn't clean these up when it's finished with them. The result is thousands and thousands of little temp files. Each new temp file gets an incremented number in its name, but when Acrobat reaches AcrFFFF.tmp it sticks and can't create any more files. When this happens, Acrobat won't work. If you open a PDF from Windows Explorer, Acrobat hangs on the splash screen.

To solve the problem, just delete the temp files.

This is an incredibly shoddy bit of coding, I'm amazed Adobe let this slip out. Adobe, hang your heads in shame!

Note:
If you have reached AcrFFFF.tmp it means you have 65535 files to delete. Windows Explorer is not designed for seleting or deleting thousands of files and you'll find it difficult.

Much better to use a DOS command window. Or, if you have SFU 3.5 installed, navigate to the appropriate directory and issue the command:

rm Acr*tmp