Placing subproject topics into the Master Project TOC

[kmiz]

We build WebHelp from a master project and a subproject. We insert the Subproject into the Master Project's TOC. We would now like to also place some topics from the subproject on the Master Project TOC in another location (separate from and in addition to the location where the whole project is bought in).

I don't think this is possible to do in any straight forward way, and just want to confirm that . One thought I had is that these topics - that we want to display in multiple places on the TOC - could be stored in a global project and imported into both the Master project and the subproject. Once they were imported into each of these projects we could place them on the TOC in the multiple places we want them to be. Has anyone had any experience with doing this? Would this be the simplest way to accomplish this?

Thanks for your help

Kmiz

[NorthEast]

I'd suggest having a look in the help for "global project linking" - using this you can import (and link to) individual files from another project.

It will take more effort to set up, but it provides a tighter and more flexible way to integrate your projects than project merging (the method you've tried).

[wst]

There are two parts to the answer to your question:

Flare's Import Feature
We use a "SharedFiles" project that contains all the things that are useful in all projects (variables, condition definitions, glossary, skins, stylesheets, some graphics, some snippets, MasterPages). Each Flare parent/child project has an <x>/Project/Import/<filename>.flimpfl file containing the script of "what" to import from the SharedFiles project. This gets tricky with Source Control, but is worth the effort:

(1) only add the original copy of these shared files to source control, never add the imported copies to source control.

(2) never add any /Project/Import/<filename>.flimpfl file to source control (Flare dynamically generates a database of what was imported and when, then stores that database inside the <filename>.flimpfl file!!! So a separate Read/Write copy of this file must be maintained on every computer you or your team members use.)

(3) if you remove a file from the "SharedFile" project or rename a file in the "SharedFiles" project, it does not get updated in your other projects the next time you "Re-Import"!! Everyone must remember to do that maually to keep their projects clean.

WebHelp Behavior
If you insert the same help topic file into multiple locations of your parent/child project's TOCs, the combined TOC behaves badly (when your customer clicks any link to that topic, the TOC highlight jumps to the last instance...very confusing to your customers when they keep loosing their place!). [Note: if you output-to-PDF the topic gets one and only one heading level, which messes up your TOC if you inserted it at multiple levels (H1, H2, H3).]

So if you really need to keep repeating something, create multiple help topic files with distinctive titles (so your customer can tell what is different about them when the same topic title turns up mutiple times in the Search results!) and use a "SharedProject" snippet file to insert the information into all the various topics at all the various locations in the TOCs of all your various parent/child projects.

TIP: In your "SharedFiles" project, store these special Snippets in a special directory SharedFiles/Content/Resources/Snippets/SharedFiles/*.flsnp so none of your team members will accidently add them to Source Control after Importing them into a project.

Happy authoring...

[kmiz]

Thanks so much for this useful information. I just have a few questions:

You advise not to check imported content into source control. What problems are created if you do check this imported content in?

Is checking the import file (.flimpfl) into source control not advised becasue this file is large?

Has keeping track of renamed or removed files in the import file been difficult? Do you have any tips on handling this?

Thanks again for sharing your experience in using global project linking!

[wst]

Why "never check imported content into source control"?

The imported content is updated dynamically according to two settings. Do these two things to make sure each time you generate output, Flare gathers the latest version of all imported files:

(1) Target file, Basic tab, "Auto-Sync" attribute. Make sure that [ ] Disable auto-sync of all import files is NOT selected.

(2) Import script file (<filename>.flimpfl file), Source Project tab, [X] Auto-reimport before "Generate Output". Make sure [X] Auto-reimport before "Generate Output" IS selected.

Flare needs to be constantly updating these copies of the files without your having any say about checking them out of or into source control. The imported copies of these files are just temporary. [The "SharedFiles" project has the only permanent version that needs to be in source control.]

Why not put the import file (.flimpfl) into source control?
The import file stores a database that keeps track of what is true on your work computer at any point in time. If you check that file into source control, then access Flare from home and use that file, your home computer will be hopelessly confused because the import file (.flimpfl) shows what is true for your work computer, NOT what is true for your home computer.

To avoid this problem:

(1) create the import script file to meet your needs.
(2) store it in source control in the same directory as your <project>.flprj file
(3) copy/paste that file into this location on each computer <FlareProject>/Project/Import/<filename>.flimpfl
(4) never check that "copy" of the /Project/Import/<filename>.flimpfl into source control

Has keeping track of renamed or removed files in the import file been difficult?
Yes, tedious and risky and requires that all authors on your team pay attention. But worth the trouble

[kmiz]

Thanks for your detailed help. I will use it as we imove forward with implementing global project linking.

[NorthEast]

To be honest, those settings are just for one particular project setup; in another project you may want to keep the import file in source control (we actually do), and use different import settings.

[kmiz]

Hi David,

Thanks for your counterpoint. This is helping me think the process out. I would like to check the import file into source control so that we are using the same backup system for all files. We do sometimes work at home, and I do work off my local desktop when I am at home - the other author works remotely off her remote (work) desktop when she is at home. My thoughts are that I would have to not check the import file into source control, or check it in but work remotely off my desktop when I am at home. But perhaps there is another way. I am curious when you say :

in another project you may want to keep the import file in source control (we actually do), and use different import settings

.

What are the different settings that you use? (I'm thinking that means different than described in wst's post.)
I have set up a test import file (and have read Flare's Help) so I am familiar with the settings in that file.

Thanks again...

[kmiz]

OK, I see: if I am working on my local desktop I can disable the Auto-reimport before generate output settings, or avoid generating ouput on my local desktop.

Thanks for your help.