Perforce and Flare

[anniep]

I manage and author WebHelp files outside of our source control application, Perforce. Once a Webhelp project is complete, I submit the output files to Perforce. Basically, I check in/out files- that's it.

IF we were to completely manage WebHelp from within Perforce:
--Can you manually update WebHelp files from within Perforce without "breaking" the Webhelp output?
--Can you open a WebHelp file in Perforce, tell Perforce to open the file in Flare, and then regenerate the WebHelp project? IF yes, how exactly do you establish a destination folderin Perforce for the Output files: Content, Data, and Skin if you're working in multiple branches for the same WebHelp project (one branch per a product feature)??

It is very clear to me how to check in/out my WebHelp output files to Perforce as a specific branch is set up for me for each project. However, I am clueless as to how Flare functions or "plays with Perforce" if our dept. were to switch from Checking in/out to actually managing ALL WebHelp files from within Perforce vs authroing and managing WebHelp from Flare and submitting the output to Perforce as we do today.

Guidance on this is much appricated. Is it as complicated as it appears? PLEASE specify all issues you've experienced and why or why not you would use Perforce to author and manage your Flare WebHelp projects.

Thanks!

[Andrew Heard]

FWIW

I've been trying to bind to Perforce since V3.5 or so, without any luck.

Am just testing with Flare 5 and although there is some improvement I still haven't been able to make it useable.

In production I manually check files in and out, add, delete, move, etc.. I am going to continue to do it that way.

[Andrew Heard]

My observations, which I'll submit as a bug report when I find out how, are as follows:

Pros

• Flare 5 does bind with Perforce
• interface really good, good options available, e.g. check in/out, diff; all work OK
• responsive
• works with Analyzer, bound with Perforce
• can edit files and add new files
• no longer have remanent Flare process when Flare closed (was a problem with earlier versions of Flare).

Cons

• on closing, Flare does not check files in; have to manage manually in Flare before closing or in Perforce after closing.
• On closing Flare, files in source control are left as read-write on the local drive, so that they aren't checked out by Flare when it is next opened. To have Flare perform source control actions, you must manually make the local files read-only.
• cannot delete files - Flare freezes and you have to kill the process
• once Flare has frozen, it hangs when re-opened; to open:
  1. kill Flare process
  2. open without connecting to Perforce
  3. unbind
  4. re-bind
• sometimes (after crashing and when trying to import a project from source control) throws up the following message about read-only memory:
  FlareMemory.png

On the whole very promising, but still too many bugs to use in production.

[Andrew Heard]

Another development -

Managed to get past the read-only memory stage (Flare just decided to let me in on one go) but couldn't get the Import project from Source Control wizard to recognise the project file.

[KevinDAmery]

Useful info, Andrew.

Since you asked, you can submit bugs here:

http://www.madcapsoftware.com/bugs/submit.aspx

[Andrew Heard]

Thanks Kevin. Bug submitted.

More info: just had our resident Perforce guru look at it and after various tweaks and prods he came to the conclusion that it's a Flare thing, not anything wrong with my Perforce configuration, as far as he can tell.

[ltnunes]

I have a more simple question about Perforce and Flare. My company uses Perforce for source control and will not be making a different SCS purchase just for tech pubs. Setting Flare's internal source control process aside... can I use Perforce ONLY for source control processes outside of Flare - synch, check in/out, revert, etc. Then take the project from the P4 workspace and work on it in Flare. I have heard everything from what files should not be checked into P4 to issues with the region that lists your files with their status (checked out, etc.) not displaying (that woud be an issues..). What I'm looking for is a "go/no go" answer, or that I have to test to make sure P4 works for us...just something more than rumor.

Sorry for the frustrated tone....

[KevinDAmery]

Basically, everything in a Flare project is a flat file, so there's no reason why you couldn't use any SCS if you don't intend to try to have Flare talk to the system. Manually checking things in and out is a chore, but as long as the files are checked out when Flare tries to save something it really should be oblivious to the whole process. It would be no different than maintaining Microsoft Office or Adobe FrameMaker files in an SCS.

[ltnunes]

You rock, Kevin!
I agree that it's a chore, but it's a chore I'm stuck with right now. In my ideal world, I wouldn't be having to write up a detailed process for the writing team to follow to use the SCS, but that's just the nature of the beast right now.

[Andrew Heard]

Actually you don't have to have the files checked out, but it does make life a bit easier - you avoid a few dialogs!

If a Flare file is not checked out in P4, the local file is, of course, read-only. Flare is smart enough to recognise this, and can, on request, make the file read-write before saving. This applies to all associated files, e.g. css, as well as edited topic files.

When you've finished, you check out all files, do a revert unchanged (as you would anyway) and, hey presto, your changed files are in the changelist.

The real chore is when you add, delete or move files - you have to do this manually in P4. New graphics, snippets, all have to be added manually - I see this as Flare's job.

I moved away fom RoboHelp, and have no regrets in doing so, but source control with Perforce is one thing that RH does faultlessly, and I'd very much like to see it in Flare.

[ltnunes]

Thanks for the additional info! My main concern right now is putting together a process that's clear for a team that is new to both Flare and source control/Perforce. Every little bit of info helps.

[cayennep]

The real chore is when you add, delete or move files - you have to do this manually in P4. New graphics, snippets, all have to be added manually - I see this as Flare's job.

I'm confused about this - source control should be able to add/delete/move things in a folder recursively, and a developer just told me it does do that. Are you saying it doesn't, if I submit at the top level of a directory?

I've found perforce challenging, and can't get the integration w/ flare to work at all - won't even bind, tho it was at one point. I never used it, but the perforce fiddling seems to have broken it the rest of the way. But if what you say is true, that's even more trouble, and counterintuitive.

tips appreciated, thx

[Andrew Heard]

Hello there cayennep(epper?)

Perforce is fine, and of course it handles all the things a source control system should do - in fact I really like Perforce.

What I was trying to say is that because you cannot bind Flare to Perforce, any files added or deleted in Flare must then be added or deleted in Perforce. As far as Perforce is concerned, renaming a file in Flare is the same as deleting one file and adding another, so you must go to Perforce to delete the file with the original name and add the renamed file.

For example, although you delete SingingInRain.htm from the Flare interface, and therefore from the Perforce workspace on your hard drive, it still exists in the Perforce depot, so next time you "get latest', on your Perforce project, the Flare-deleted file will be added to your workspace again. Similarly, if you add GoodMorning.htm to Flare, it will exist in your hard drive workspace but won't exist in the Perforce depot until you Mark for Add. The extension of this is that if you rename SingingInRain.htm to SingingInTheRain.htm, you'll have to go into Perforce to (1) add SingingInTheRain.htm and (2) delete SingingInRain.htm.

If Flare could bind to Perforce, Perforce would do these things automatically - this is the way it should be.

The rider is that I haven't yet tried doing a Perforce-bind in Flare 7.

[samjones6]

Here is another perforce user....

Flare project is in perforce. Output is not.

Bummer that flare doesn't hook nicely to perforce.

[Michele]

We use Flare for writing and Perforce for source control. There are a total of seven writers accessing our projects.

As long as the same writer works in the same project, we don't have too many issues between Flare and Perforce. However, we recently lost two of our writers and brought two new writers to the team. When the new writers accessed the projects they have been assigned to work on, they get errors.

"File could not be loaded. Data at the root level is invalid. Line 1, position 1."

When I look at the file in a text editor, line 1, position 1 shows this at the beginning:



At least 13 files have these characters inserted at the beginning of the files.

Another problem, our TOC (.fltoc) file is corrupted. When I look at the file in a text editor, I see this (and more):

믯㲿砿汭瘠牥楳湯∽⸱∰攠据摯湩㵧產晴㠭㼢ാ㰊慃慴異瑬潔ൣ 嘠牥楳湯∽∱ാ 㰠潔䕣瑮祲਍††楔汴㵥䠢浯≥਍††楌歮∽䌯湯整瑮弯潃敶彲䥄⹓瑨汭 . . .

In Perforce, the TOC file is saved as <utf16>.

My questions:

- Has anyone else experienced similar issues with Flare and Perforce?
- Has anyone tried installing the API option mentioned here http://webhelp.madcapsoftware.com/flare ... ontrol.htm?
- Does anyone have any useful workarounds with these files?
- At what point do you save the TOC as binary (as mentioned in some earlier posts)?

We want to have multiple writers working on all our projects but we cannot keep dealing with these problems just because we have multiple writers.

Changing source control is not an option but we are seriously considing moving away from Flare if I can't find a reasonable workaround to these issues.

[samjones6]

At least 13 files have these characters inserted at the beginning of the files.

Hmmmm, at least the file is under version control so can be easily rolled back!

One thing to check:

The Flare files are (I believe) utf-8

It is important that the Perforce client be a relatively fresh version (I think anything in the past year is good), so that the file is not damaged. I have seen older Perforce clients damage utf-8 files in a way similar to what you describe.

In Perforce, the TOC file is saved as <utf16>.

Ahhh, sounds like my suspicion above is correct.

This is best handled by Perforce support. Send them the valid and invalid Flare file (e.g. two revs of the same file, one as it should be, one damaged), and ask for a hand.

- Has anyone else experienced similar issues with Flare and Perforce?

With Flare: Never
With utf-8 files from other apps: Yes

- Has anyone tried installing the API option mentioned here
http://webhelp.madcapsoftware.com/flare ... ontrol.htm?

No, but I may try!

- Does anyone have any useful workarounds with these files?

The key is to figure out at what stage the files are damaged. I believe it will be at the moment the files are checked in to P4.

- At what point do you save the TOC as binary (as mentioned in some earlier posts)?

I would never save anything as binary, because then I lose the ability to diff....

Changing source control is not an option but we are seriously considing moving away from Flare if I can't find a reasonable workaround to these issues.

Likewise, we would dump Flare loooooooong before we would dump Perforce. (IOW, we would never dump perforce....!)

HTH!

[RamonS]

Likewise, we would dump Flare loooooooong before we would dump Perforce. (IOW, we would never dump perforce....!)

Allow a question, why do you use Flare at all? Every single thing about Flare is apparently wrong and Flare supposedly is the worst piece of software ever compiled. Just wondering....

[Michele]

Please don't turn this into a what software is best debate. I have a serious issue that I need help with -- I need to know if it is a Perforce issue or a Flare issue.

In my experience, documentation is not very highly regarded and no one is going to take my word that Perforce is the problem. I have to back it up with facts. R&D uses Perforce and they aren't going to change that just because I am having problems . . . therefore, I need a work around or solution.

[emichaud]

I'm a new Flare 6 user and am designer and liaison to several offsite contractors who are building a big help system in Flare for our our new web client. We need to share Flare projects and files between Boston, where I am, and Sri Lanka, where the contractors are based.

Madcap Support confirmed that the only reliable way to share projects and files is to bind the project to source control and always to go through source control. At our company, the source control system we already have is Perforce.

Having read all the problems that other posters to this forum have had, attempting to integrate Flare with Perforce, I have a couple of questions:

1. Does using Flare 7 and an MSSCCI-compliant plugin fix all the problems people have had in integrating with Perforce?

2. If not, has anyone come up with a not-too-onerous set of workarounds for using Flare with Perforce?

The other alternative, I guess, would be to use one of the source control systems for which Flare has built-in support. I'm not sure my company would let me do that.

Thanks in advance for any information you can provide!

Elizabeth

[samjones6]

I need to know if it is a Perforce issue or a Flare issue.

As I describe above, this problem looks seriously like a Perforce issue. I have had this exact issue with other utf-?? files from other tools. The solution was to upgrade the Perforce client apps, as perforce was pushing the files to utf 16 when they are actually utf 8

[samjones6]

Madcap Support confirmed that the only reliable way to share projects and files is to bind the project to source control and always to go through source control. At our company, the source control system we already have is Perforce.

From what you write, I agree that version control is THE way to go.

And Perforce is an excellent version control system. (Most excellent, actually!)

I use Perforce, and our entire Flare project (about 1100 files) is in Perforce. This combo works great.

I have a kit of powershell scripts I use to:

1) Check out the entire Flare project and open in Perforce

2) Revert all unchanged files (prior to check in)

3) Add all new files to the perforce change list (new files are created all the time, new topics, images, etc)

4) Check it all in.

I have not used the scc plugin so far, but I plan on trying it.

hth!

[Andrew Heard]

Hi Michele -

Perforce integration has been quite widely discussed here - the more discussion the better, as it should alert the MadCap developers to our issues.

I've been using Flare with Perforce for about three years. Three of us share projects. We have a routine that allows us to share, even to work simultaneously on the same file, without any problems.

To answer your question, is it a Flare issue or a Perforce issue - I think it's slightly more of a Perforce issue than a Flare issue! But easily solved by saving the fltoc as binary. Search this forum for "utf-16" for some more threads.

To further elaborate:

• Yes I have seen the error you mention. The text-based fltoc file is being converted from utf-8 to utf-16. Perforce and some external text editors do this. I conversed with Perforce about it - they were extremely helpful and recommended a binary TOC. We have had no problems since saving TOC to binary. Personally, I can live with not being able to perform a diff on the TOC file.
• Perforce were not able to repair the corrupted ftoc file.
• The API mentioned is automatically installed with Perforce - it is the standard GUI with which Perforce communicates with other applications.

If you read through the other Perforce-related topics, you'll find the process for using Flare with Perforce - it's not difficult. Talk to your developers - they will use the same process. It's an inconvenience that Flare does not bind with Perforce using the MSSCCI plugin, but by no means a showstopper.

You should have no reason at all to change either Flare or Perforce - both are excellent products.

PS - samjones6 - would you be willing to share your Powershell scripts?

[samjones6]

PS - samjones6 - would you be willing to share your Powershell scripts?

Our stuff isn't generically useful, I am afraid. It is quick and dirty for internal use.

Also, we found getting the perforce environment working with powershell to be a challenge!

The key question is: How to get from powershell to perforce?

There is more than one way to answer this question... What we did was to use a .net assembly called "p4.net" which is here: http://downloads.sourceforge.net/p4dotnet/

Then we could reference those assemblies from powershell to do what we needed.

[Andrew Heard]

Thanks for that.

No biggie, to be honest - would just save a few minutes manual labour in Perforce.

[samjones6]

I should also mention that there is a great ruby lib for perforce. If you have ruby skills in house, this is a great way to go. (We don't.... or we would go this route.)

I find scripting to be a LARGE productivity gain. Yes, I can click around p4v, but if I am making the same clicks every day, or multiple times/day, scripting will save me time!