Round trip to Word

[wclass]

Round-trip Word imports, or there and back again ...

I have been experimenting with exporting AND importing Word documents from Flare. In the past, I have managed to successfully import from Word, and later on I've managed to create Word output from my Flare topics, but this is the first time I've experimented with creating a "round-trip" document. My final deliverable is webhelp for the application and Word for the release notes. I also use the Word version to send to the reviewers, and I get comments back (usually with track changes). I wanted to be able to do the round trip mainly for the reviewed information.

Hopefully this posting of my findings will help those people with Import questions at the moment. My source files are stored and updated in Flare, not Word, but some of the information might still be of use if you want/have to live in Word.
Caveats - I have a style sheet already set up that I link to in the import, and I NEVER select preserve Word styles when importing. The trick might be that I create in Flare and export the first version of the document from there to Word.

Styles
When I export to Word, Flare generates style names like "p" (that's OK), but then it does p_1, p_2, and so on. It does similar things for list items (I get li_1, li_2 etc), and td items. This sort of thing is done, I assume, when I have a list within a list, or a paragraph within a list - it also creates the extra ones for lists and paragraphs in tables. For Word, you need to have a different style so that you can get the indenting right (some are not really necessary, but I digress).
For a round-trip, I don't really want these extra styles when the document imports back in, so in the import editor, I select the Paragraph Styles tab and I map the extra "p_numbered" styles back to "p" - this works. There is a problem with the "li" and "td" styles - they just aren't in the list of Flare Styles on the mapping page - what gives! So far, I think li, td and th are not available for mapping. I lose the indentation of sub-lists (workaround - don't have sub lists).

There is also a problem with styles set as independent classes. For example, I have a navigation style class that I apply to some paragraphs ".navigation". This is exported as "p_navigation", but I can't bring that back in except as a plain old p. I have a workaround for now - if I set it up as a dependent class, p.navigation, it works. I'd rather not have to change all my styles though.

Re-import
The re-import works OK if all I have done is change the text in the sub-sections (and made sure I have cleared any track changes). I have a problem if I add in a new section to the document in Word with a style that I have specified as a topic split (for example a H1 style). Flare scans the file and then waits ... for quite some time ... longer than it takes to make coffee ... then I get impatient and kill the job (which normally takes about 5 seconds). If I remove the old files from the import folder first, there is no problem - this is an OK workaround for now.

Master pages
Here in Australia we use A4 size pages, not "Letter" size. Exporting is no problem as I can set the master page. When I import a Word document that has a page size of A4, the import process automatically generates a master page of the default "Letter" size. While I can work around this by quickly re-applying my valid page, there are a few things wrong here.
1 - If you create a master page, get the size right. Also, get the even/odd page settings as well.
2 - I'd like to be able to set my own defaults in a "preferences" section somewhere.

TOC set-up
There are several ways to create a table of contents in Word - the Flare way is to put in TC fields, which is more work and adds hidden text all over the place, and the other way is to use the styles and heading levels. When you round-trip a document, the topics end up suffering from "TC build-up". While this doesn't break anything, the tags in Flare and the hidden text in word just clutter the interface. I'll put in a request to the developers to reconsider how they build the table of contents - heading levels is much preferred.

And finally ...
After all that testing, I am not totally happy with the final result. My original export included topics from a number of different folders. My main Word output is a set of release notes for the version of the software that can contain information from just about any section of the help project. When I re-import, it all goes into a new import folder - there is no connection with my original topics and I end up with copies. Kinda runs against the single sourcing idea. (Of course, if I started with an imported Word document, this would not be a problem).
I'm not sure how you could fix this - maybe assign Word variables, or document properties or something at the time of the export? I wouldn't trust hidden text as that is too easy to delete. Anyway, food for thought.

[SteveS]

Thanks for sharing, Margaret.

I know round tripping is a bit of a holy grail and to do it with something like Word is a real challange.

I don't know if you're going to look at Analyzer, but it's "duplicate styles" functionality may help with li_1 issue.

[wclass]

I haven't fully tested Analyzer, but hope to soon - we had issues with SQL Express. We are a big company and have a large DB department who don't want the rest of us installing express (it has caused problems). We will probably get a separate test machine for trials, but are more likely to wait a few versions on the off chance we can use something our DB team can manage.

[kittim]

Since this post is a bit dated, I thought I would bump it up to see if I can get any help with this. I am new to Flare, and I have the requirement that I need to provide a word document to reviewers, who will edit. I will track/accept changes, then I need to get it back into Flare. My original project was imported from Robohelp. The final output will be HTMLHelp and a paper manual (either pdf or word). These two outputs will closely resemble each other with the exception of the obvious differences that each format requires. I am at a loss as to how to proceed even after having read this very detailed description. I thought that since there is a new version of Flare, and since reviewers are a fact of life for most of us, perhaps there are some good tips out there as to how to manage this, other than manually cutting and pasting, which is what I am considering now. Of course I have a very tight deadline, and the software is not yet completed. And as usual, at least in my experience, the manual has to be run through the release process before the software development is even complete.
thanks in advance for any help.

[wclass]

... I have the requirement that I need to provide a word document to reviewers, who will edit. I will track/accept changes, then I need to get it back into Flare.

<prepare for long topic>

Well a lot has changed in the past year - there have been many improvements to Flare, some of which make the reviewing process much easier, but unfortunately I am still not convinced that a "round trip" works properly yet. Some things may work for your scenario, though.

One of the main new features of Flare is the XEdit product. This lets you send individual topics for review, and have updates sent back and incorporated into the project. I don't use this at the moment because you can only "review" one topic at a time, but it is worth keeping an eye on.

Another new feature is the ability to set custom file names to sections in your Word document so that you can determine what the topic will be called when it is created. This is a good improvement, but it is not yet perfect.

When importing, all generated topics still get put into the one import folder. When I generate output, I include topics from many different folders. Now I can set the right custom name for the new files, but I will still have to move them back to the original location if I want real "round tripping". I have hundreds and hundreds of topics - I just can't keep them in one folder. Also, if I move and overwrite the original topic, I lose any condition tags that were originally set - this is not good.

Other things that don't survive the round trip are variables and snippets - these things come back "hard-coded". This is a pity.

Issues mentioned in the earlier post:
Styles - nothing has changed here - a pity.
Re-import bugs - the new and missing files bugs have all been resolved.
Master pages - we now have Page layouts as well. But the same comment holds though - any master page generated on import should be duly ignored. Note that only master pages seem to be generated - no page layouts yet (but I don't think we need that, other opinions may differ).

Table styles are a problem. My original topic uses "th" for the table headings. This is translated to Word OK - they are treated like real headings and repeat at the top of pages and so on. When I import, though, they get converted to a plain old table row. Even if I reapply my original table style they don't look the same as my styles operate on "th" - I have to update the code. Column widths seem a bit random as well.

And images are an issue. If I send a document for review, I have to embed the images, but an import generates numeric names for imported images. If I don't embed and leave the link to the folder the image is in, the proper path name gets lost in translation - I think it is looking for the file in the output folder (this one probably needs a bug report).

Other alternatives:

Having said all that, if I was going to generate a full Word document plus HTMLHelp, I might consider leaving the original in Word, do all my edits and reviews with track changes, only only import it in to Flare to generate the CHM - this works, but you can't take advantage of the features like snippets, etc.

For what its worth, I edit fully in Flare. As well as generating my required output types, the philosophy of Flare works for me, like the topic based authoring, and single sourcing, and snippets, variables, etc and so on. But a lot of my reviewers are Word based people, and that won't change. I get by with generating a Word document for review, and then manually updating my topics as needed. But I tend to look at review comments as "suggestions" and will reword them anyway, so I don't feel that the manual updates are much of an overhead.

I'd like list and table style mapping improved, and image mapping improved. What might be nice is to import topics into a temp folder, and then have a compare/merge function with the original topic - this way I could get the updated bits without overwriting variables or snippets.