Changing variable mid-project

[Dodo1]

Hey all,
I have one particularly difficult project I need some help with. We are using Flare 9.0 in our company to make manuals and help files at the same time, and have around 80 actively maintained Flare projects running, some of them small, some large. The problem I have is with just one of those.

Basically, this project covers helps and manuals for one exceptionally variable product, but basically the majority of the text is the same. I have created the project with a lot of conditional texts (based on the variation) and variables, and this all works pretty fine for manuals, because in case of printing a manual, it is just for a single variation of the product and therefore must include only the relevant parts (which I can control using Flare conditional texts) with the proper labels (which I can control with the usage of variables).

HTML output is, however, where the problems start. I need a single help (*.chm) output file, because regardless of the product variation, just this one chm file will be called. However, I need the topics which cover the differences (this is, for example, the configuration process which is different for each product variation) to have proper labels, text and screenshots, and I need the whole Flare output to have all of these product variations incorporated. Therefore, the chm file TOC would look like this:

Generic configuration (basically just links jumping to particular product variation descriptions)
- Product 1 configuration
- Product 2 configuration
...
- Product X configuration
Generic device usage (again, just links to particular pages)
- Product 1 device usage
- Product 2 device usage
...

You get the point. For this to happen, I need to be able to change the variables/conditional texts in the middle of the building the project, because the "Product 1 configuration" and "Product 2 configuration" topics should be build from the same Flare topic using different conditions/variables. I am not aware of any means how to do so. Can you help me with that?

To clear up things a bit more, there is nothing I can do with a single file output (no way to create more than 1 chm file that would still function) and no way to work with the general output structure (need output section for each product variation in the same help). As we currently have more than 20 different product variations here (and more will come), you can see that I am not too eager to duplicate the configuration topic twenty times in the project, given the fact that when something needs to be repaired in the help, I will need to repair it on 20 different places instead of the current one place.

Thanks in advance,
Daniel

[NorthEast]

I think you should look at snippet conditions:
http://webhelp.madcapsoftware.com/flare9/Default.htm#Snippets/More_About_Snippets/Using_Snippet_Conditions.htm

Snippet conditions are applied at the topic level, not the target level; so that means you can re-use a snippet in multiple topics, and set different conditions for that snippet in each topic.

So for your example, you might set this up as follows:
- Create a snippet for 'Product configuration', and mark the text for different products using conditions 'Product1' and 'Product2'.
- Create a topic for 'Product 1 configuration', insert the snippet, and set the topic snippet conditions to exclude 'Product2'.
- Create a topic for 'Product 2 configuration', insert the snippet, and set the topic snippet conditions to exclude 'Product1'.


As for variables - these can only be set at the target level, so you can't apply different values to a single variable for a single target. If you need to do this, it may be better to replace the variables with snippets (which can be conditionalised).

[Dodo1]

Dear Dave,
thank you for the answer, however the proposed snippet way is probably doing the opposite from what I want to achieve (or I didn't understand the usage properly). The information is super-helpful anyway as we are using the snippets for repeating parts of the text throughout the topics and projects (using imports) and it may reduce some overhead in using the topic conditions in the snippet itself.

My current situation is more like a single topic containing a paragraph:

Code: Select all

{DeviceNameVariable} device works with the {ScripNameVariable} script, which is loaded by clicking the Load Profile button and browsing to {condition1}sometext{condition1 /}{condition2}differenttext{condition2 /} folder (check the folowing picture):
{condition1}picture1{condition1 /}{condition2}picture2{condition2 /}

Now I need to include this same topic into the TOC twice, in first case it should read:

ALPHA device works with the Alpha.scr script, which is loaded by clicking the Load Profile button and browsing to sometext folder (check the folowing picture):
picture1

while in the second instance of the ouputed topic it should be:

BETA device works with the Beta.scr script, which is loaded by clicking the Load Profile button and browsing to differenttext folder (check the folowing picture):
picture2

Now imagine I have 20 diferrent sets of variables and 20 different conditional texts (in fact sometimes the conditional texts are fewer, but repeated through different devices). Unfortunately I cannot se how the snippets could help me in a single topic...

[NorthEast]

Now imagine I have 20 diferrent sets of variables and 20 different conditional texts (in fact sometimes the conditional texts are fewer, but repeated through different devices). Unfortunately I cannot se how the snippets could help me in a single topic...

You wouldn't be using a single topic in the TOC twice though.
You would put the topic content in a snippet, and then use that single snippet in two separate topics.

Taking your example, instead of using variables, you'd use conditions to set the device and script names:

{condition1}ALPHA{/condition1}{condition2}BETA{/condition2} device works with the {condition1}Alpha.scr{/condition1}{condition2}Beta.scr{/condition2} script, which is loaded by clicking the Load Profile button and browsing to {condition1}sometext{condition1 /}{condition2}differenttext{condition2 /} folder (check the folowing picture):
{condition1}picture1{condition1 /}{condition2}picture2{condition2 /}

I'm assuming there's a correlation between Alpha and condition1; if not, you would have conditionA for Alpha, conditionB for Beta, etc.

You could put that whole block in a snippet, then insert the snippet into two separate topics for Alpha and Beta. For each topic, set the snippet conditions to exclude the conditions you don't want, e.g. for the Alpha topic exclude all snippet conditions apart from condition1.

So then you'd have two (or more) topics that contain variations on the same text, which is all managed in a single snippet.

If you have 20 products, it may take a little time and experimentation to set this up in a way that makes sense; but by using snippets it means you don't have the situation of having the same content repeated 20 times.

[Dodo1]

Thank you for the explanation, now I see how can this be done with only a small overhead compared to current (not sufficient) situation we have.

[Msquared]

It looks to me that what you actually want here are snippet variables, rather than snippet conditions. I have some very similar text that I have often thought would be much improved with snippet variables.

Incidentally, the other snippet single-sourcing feature I'd really like would be the ability to specify the snippet condition (or variable!) to apply at the point where the snippet is placed in the topic, rather than having to set the condition on the topic itself.

There are multiple reasons for this.

If you place the snippet condition on the topic, the setting of the condition is one step removed from the content it affects, so it is more likely to give a maintenance headache later on. There are all sorts of reasons why you set topic conditions, and only some of them are to drive snippet conditions. I know snippet conditions are set differently from ordinary conditions on topics, but you could change the ordinary or snippet condition at the topic level, and fail to notice you've broken a snippet condition in the topic that depends on it, because the full effect isn't apparent without building the output.

I occasionally want to include the same snippet twice in a topic, with different conditions. For example, I have some installation instructions that are very similar for several different servers in the same system, but some types of server need a few more steps. If the steps are in a snippet for reuse, with conditional code based on the type of server they apply to, I can't put the same snippet twice in the same topic with different conditions as I can only set one combination of options for the snippet condition at topic level. I may want to include the installation instructions for all servers in our configuration in the same Flare topic. Not possible at present.

Finally, if the snippet condition was set at the point where you placed the snippet, and could not be overridden apart from at the point of placement, you would be able to see exactly what the snippet text looked like in that topic, as you were working on it, to be sure you had set it correctly. This would also make maintenance easier. At present, you can set a topic to include a snippet condition so the text in the snippet placement is correct for your usage. Then you can exclude that condition at target level, and that exclusion will override the inclusion at the topic level and the text in that snippet placement will no longer be correct.

I've been meaning to raise a feature request for these two items (snippet variables, and setting snippet conditions/variables at the point where the snippet is placed in the topic, not on the topic itself) for ages. Anyone fancy joining me?