conditons required to keep from publishing topics

[cayennep]

What's happening is that a bunch of extraneous topics are publishing every time I build. They are marked with a condition 'Later' which I exclude from the Target and the Skin (do I need to do both, btw?). Yet they still publish.

thanks for any help

[LTinker68]

having Flare publish things outside the scope of that TOC or Target when creating html is extremely painful.

Perhaps you're thinking a bit too linearly. Online help is designed to be interactive. For example, say you have an image of a screenshot of a program and want your users to be able to click on the fields in the screen and have information appear in a pop up window. If that text is just a few lines, you wouldn't want the user to be able to open up that short topic from the TOC because it would be out of context, but you do still need it in the output so that it can be called by the popup effect.

So if you think of online help as being interactive, that might help.

Also, you don't need to apply conditions to TOC entries. If you apply a condition to a TOC entry, you're only controlling the inclusion/exclusion of that TOC entry -- the topic it's pointing to is still included in the output, at least for online output. However, if you apply the conditional tag to the topic file itself, then you're controlling the inclusion/exclusion of the topic and the TOC entry. Applying conditional tags to TOC entries is generally used when you're single sourcing the TOC file and you don't want a topic that's in the online output from being used in the print output. Excluding the topic from the TOC prevents it from being included in print output.

If there are a group of topics you do/don't want to appear in a specific output, then you could put all those topics into one folder in the Content Explorer and then apply the conditional tag to the folder.

[RamonS]

Do they by any chance have a condition applied that also includes them? There always has been much discussion about how conditions work and each time the arguments against the way they work now are understandable, but changing Flare to work as requested would be even more cumbersome. Here is a summary of what Flare does and why.

A) No conditions whatsoever
There must be a default for Flare to fall back on when there are no conditions applied. The choice here is to either exclude everything or to include everything. The design decision was to include everything by default and it makes perfect sense. Otherwise one has to always create at least one condition and always apply it to everything that needs to be included. I am sure that in any given project more topics are to be included than excluded. So picking anything else than including by default would be just stupid.

B) Excluding content using one condition
Now, when excluding content a condition is needed, it needs to be applied to the content to be excluded, and Flare needs to know what to do with it. One could think that applying a condition alone would mean excluding things, but that severely limits things when working with multiple conditions. More about that later.
So why exclude things in different places? Well, if you do not want a topic definitely set the condition on that topic. It surely helps to condition out the entry in the ToC, but since you can have as many ToCs as you want within a project (you need to tie one eventually to a target) you may also opt to create several ToCs and remove what you don't want.
Now, here is a bunch of pitfalls. When you do online help (CHM, WebHelp, DotNetHelp) the ToC doesn't mean that much. You can pick a topic deep down in the guts of everything as the default and from the link to any other remote place in the entire project. Surely, the ToC helps organizing content and finding things, but in theory you could do online help entirely without a ToC. That is why for online help you need to go to the topic itself to exclude it. Also, what to do with links? When a link points to a topic that is not to be included what happens with the link? Older versions of Flare ignored the directive to exclude and included the topic anyway so that you won't end up with dead links. As far as I know, the more current versions of Flare shifted the ignorance a bit and now don't include the link (it will be plain text) and adhere to the directive of excluding the topic. I think the current implementation is most likely the better way to overcome this problem.
Now lets throw print(able) output in the mix. On paper we need to follow a fixed sequence. The wild linking across the entire project is no longer working in this context. Flare needs a guide to know what to put on page 1, page 2, page 3, and so on. The MadCappers could have added a new tool to the mix, but the ToC editor was already there and almost all print(able) matter will have a table of contents that in order to make it useful shows the content in sequence. That is why for print the ToC is very essential and a mandatory element. That explains why for print(able) output any conditions used for excluding content needs to get applied to the ToC.
As for skins, I am not that familiar with tweaking those. For the few things that I do anything out of the box works. But I'd assume that the same principles apply here.

Here is what I would do: add a condition for explicitly excluding, add a condition for explicitly including, and apply those to the topics, ToC, and skin. Is that a lot of work? Yes! Is it over the top? Probably. Will it generate the results that I expect? I am quite sure it will. And when applying conditions to both topics and ToC it doesn't matter if I do online help or PDF or something else. As mentioned above, you could use two or more ToCs. Likewise, if you want to go down to individual paragraphs or tables you need to condition all that as well.
When you have a large project the going through all this work of assigning at least one condition to every piece the effort is rather large. Make a copy of the sample project, add a few topics and try things out. What happens when you apply conditions to a ToC book? What if entire file folders are marked with conditions? Which other shortcuts can be used? Keep in mind that anything that doesn't get explicitly excluded will be included. You can also try out what happens for online help versus print output.
In case you use explicit includes you can quickly run into cases where a topic is set to be both included and excluded. In that case the include will win. So if something is included it either was not excluded (means not conditioned at all) or there is a collision and the include wins - or you do print and you didn't apply the condition at the ToC level or have a collision at the ToC level and the include wins.

C) Multiple conditions
My guess is that you may not have a yea or nay situation. There are different versions of the software that need different pieces of the help and out of a sudden you look at four or five conditions at least to get the exclusions nailed down. If you go with the explicit inclusion you look at twice that. I worked on projects where I had to create three variations and that was already good enough to confuse the heck out of me. Flare never did what I wanted, it always did what I told it to do! There was always something added to the output that I didn't want in there. And it was always that I goofed it up with multiple conditions stating the opposite, even when I had three excludes on something that one include always won. I eventually got it done and was very happy that I never had to touch things again after that. The help was for a legacy project that wasn't going to change.

If I'd ever face that again I'd go with at least two ToCs, one for online and one for print. I may use more. From my experience users access content in mainly through one of two ways: ToC or full text search, because users are used to these concepts (only few value a well-done index, which to create is an art that is difficult to master). Taking things I don't want included out of the ToC will shut down one avenue and it won't even need conditions for that. Topics or parts of topics then still need to get conditioned, but if a topic slips through that isn't linked to from anywhere the worst case is that it just happens to be in the upper part of search results and a user accesses it. That isn't nice, but chances are quite low. And looking at the files in the output it should be easy enough to find such an orphan - assuming that the file naming convention is followed that allows for finding files in cases like this one. Making use of flat but meaningful folder hierarchy will help. If you see a folder that shouldn't be there due to exclusion then something went wrong. Ah yes, you can also exclude at the file level, which comes in handy when you have external files such as PDFs in WebHelp that you do not always want to have included.

Multiple conditions make things very complicated very quickly. If you lose overview and control take a step back and do something else. Next day you can see the crooked tree in the condition forest no problem. And if not, figure out on paper what the best approach is that strikes a balance between number of ToCs and number of conditions. Always keep in mind that print goes by the ToC, online goes by the topic. Keep in mind that include is by default and in case of collision include always wins. Evaluate file folder structure (which can be different from any of the ToC structures!) and organize files and file folders in a way that makes it easy to find the topics that slipped through the cracks.
And if all else fails think about splitting the project up into smaller projects that get tied together in one or more master projects. Or make two or more entirely independent projects. Sure, then you say good-bye to single sourcing to some extent and you need to make sure that any changes go into each project, but sometimes the caveman approach of copy & paste plus some formatting is quicker than the techie geek approach of having everything in one project with some insanely tricked out conditioning (that is so fragile that it breaks just by looking at it).
Ah, and before I forget the simple stuff, take a good look at the conditions you are using. Do you have to use all of them? Can you get away with less? This is another case where less is more and KISS is the way to go. There may be reasons where excluding something is a non-negotiable necessity, but sometimes it would be nicer to do so, but not direly necessary, Do yourself a favor and go with the less perfect approach. I'd cringe myself doing that, but there is typically not enough time to overthink and overengineer things. In the end it is a case by case decision and my view may not fit what you are expected to do. Honestly, I included things in the online help that was special order for a single customer and nobody ever wondered about it. We typically make things so generic that if another customer can use it we can give (sell) them a license for it. Only in a very few cases we get sneaky and have F1 show a different help than what you'd get when clicking the Help button.

And if all else fails and you are about to throw yourself behind a bus, contact support. There are people whose job it is to help Flare users. If you have a maintenance contract you paid for them already. They are happy to help you and when they fixed your problem it makes their day - and yours, too.
For throwing Flare out the window and going somewhere else, maybe there are conditions and maybe they work a bit different, but the logic will be the same and stuff will go wrong when collisions occur. Besides that, you'd need to convert all your projects, fix all the formatting, redo a whole bunch of stuff - and still face the fact that the ToC doesn't really matter for online and matters a whopping lot for print. Maybe the dishwater in your cup has a different color, but it is still dishwater and it won't taste good. Just think about what you'd need to do if there were no such thing as conditions!

So much for this dissertation. I don't know if it was helpful.


David

[i-tietz]

sorry David - didn't read your dissertation - it's a tiny bit to long for me to read. So I might repeat sth David has pointed out already.
My guesses are:
1.
Webhelp, HTML Help & Co.: If you apply conditions in the TOC they have no effect on the topics - wehn you use a conditioned target they are still part of the help, they're just not in the TOC.
PDF, Word & Co.: If you apply conditions in the TOC and use a conditioned target that leads to those topics not being part of the output at all.

If you want to keep topics out of online helps, you have to assign conditions to the topics themselves, not the TOC. And: Topics that are kicked out by a conditioned target are also not part of the TOC - automatically.

2.
You have a folder A that contains the topics B and C
You apply condition cond1 to folder A and cond2 to topic B and leave topic C unconditioned the way it is.
You have a target including cond1 and excluding cond2.
=>
Topics B and C are part of the help.
Why? Because the include overrules the exclude. You included topics B and C by giving the folder teh condition cond1, which is included in the target ...


Something else: ----------------------------
I produced a content management system with multiple output formats myself (programming GUI, tech doc on all levels). It was based on a database, not file-based like Flare. CMSs like that can make your every day work a lot easier.
BUT:
CMSs like that cost a lot more than Flare because somebody else is doing the job you don't like to do for you - by programming the automatisms into it so you don't have to worry about anything. So either you get at least one good programmer in your own company who does all that for you or you pay the external service. Either way it's pretty expensive ...

Flare is excellent quality for the amount of money you paid for it.
(I'm in the SW busines for 28 years, saw a lot of SW, and I keep saying that, because I'm utterly convinced.)

[lacastle]

Here is what I would do: add a condition for explicitly excluding, add a condition for explicitly including, and apply those to the topics, ToC, and skin. Is that a lot of work? Yes! Is it over the top? Probably. Will it generate the results that I expect? I am quite sure it will. And when applying conditions to both topics and ToC it doesn't matter if I do online help or PDF or something else.

This is what i do. I use the same content for print and online output, but i have a few topics (title page, toc proxy, etc.) that are only print output in the "print condition." if i want a print manual, i change the appropriate topics to the print condition and they get the intro pages. if i want online output, i change to the webhelp condition and the intro pages aren't included.

i explain my different conditions at the beginning of this topic - http://forums.madcapsoftware.com/viewto ... 13&t=11847

[cayennep]

[Perhaps you're thinking a bit too linearly. Online help is designed to be interactive.

I have a good idea how online help is designed to be interactive, and want the tool to do what I want. I understand the case for changing processes, but not just to match the tool. I've been doing this for quite a while and have pretty good ideas of best-practice, but trying to address a very specific issue.

I can see cases where you _would_ want things to publish without being in the TOC, but that is clearly not the case here. I do not want every object in the project to publish each time, which is what's happening - and the conditions are not always working even when I do apply them.

but thanks anyway

[cayennep]

So picking anything else than including by default would be just stupid.

I disagree. Including everything by default is not intelligent. And the conditions don't work.

I don't care about print output. not at all. That works as expected - I build a TOC, Target, and publish. It publishes - what I told it to.

I do have separate TOCs for print, and some separate ones for html output. However, there's not much point in creating TOCs and Targets if what I put in them isn't honored. And the conditions don't work, as I've said.

I'd far prefer to have broken links, or have to fix those, than what I'm getting right now. And Authorit, which I've used extensively and may very well return to, simply does not publish a link if it can't find the target.

By the way, what I would do if there were no such thing as conditions - probably not call it a single-sourcing tool. However, if it worked the way I want, I could use conditions in a more useful and smarter way. As it is, there are so many that I can't really use them for anything else.

And yes, I've set include and exclude conditions, but some are not working, still.

Thanks for your lengthy input, appreciate the thought. But I'm not sure that such an extensive dialog really indicates a healthy working tool!!

[cayennep]

Flare is excellent quality for the amount of money you paid for it.

Don't think I agree with this one at the moment either - no matter how much or how little I pay, if it's not usable it's not a bargain.

I will get on a support call, and see if I'm missing something. But it seems people are not quite reusing the way I'm used to being able to do. I want to include some topics in a TOC/Target, exclude others, maybe permanently or just until they're ready. We have docs that overlap, and some that just use pieces of others. This seems a fairly standard use case to me, but not sure how others are using this. If you've only ever used Flare, maybe you've just adapted?

And I'd like the Target OR TOC OR skin (ideally not have all these pieces with no clear idea who does what or how they interact) to honor what I put in it, else why bother? That is not the case, and even applying conditions to exclude isn't working. (They are not included elsewhere, some are draft topics/notes that are not included anywhere, but they still appear in the output folders and would show up in a search. How is this a good thing?)

I'm going to keep looking at why the excludes are failing, but the whole thing doesn't seem right to me!

[cayennep]

ok, one thing I've just discovered (I think) - and this IS crazy, if true...

If I set a topic condition for Install (the book/toc/target it goes into) AND Print Only

Then in the html help I Include the Install condition and Exclude the PrintOnly - it will publish!

How is this helpful? Am I missing something, or can you only use conditions for one thing or the other??

[lacastle]

Include always wins. I try not to put multiple conditions on one topic anymore because of the problems it was creating. Can you just make PRINT or HTML conditions and separate the content into folders depending on what manual it's part of (instead of a manual name condition too)?

[cayennep]

well, the biggest problem is not wanting everything in the project to publish when I build html

this requires a rethink of everything, but maybe I don't need the print/html conditions. that's painful, but if I just use the manual/product conditions it might work better, as I have separate TOCs for the print with their front matter (title page, so far).

this still does not seem right to me, but I'll have a look at whether I need print & html conditions. It would certainly be useful! And this has been way too much work to find out what's happening.

thanks for this, it's always just when we discover the thing that somebody says, o yeah there is that thing!!

[RamonS]

What else is Flare supposed to do when you tell it to include and exclude something? The only viable alternative I could see is stop the compile and throw an error.

[wclass]

...
If I set a topic condition for Install (the book/toc/target it goes into) AND Print Only
Then in the html help I Include the Install condition and Exclude the PrintOnly - it will publish!
...

If you program it to include AND exclude at the same time something's got to give. This is where INCLUDE overrides EXCLUDE - for most use-cases (for me at least) having include win is the best option.

There is one use-case that I think is missing, however, and that can cause frustration - that is when you want to temporarily exclude a topic. I generate quite a few different output types and have a complex set of conditions that I apply to each topic. If I have to temporarily exclude a topic from a build, I have to clear all its standard conditions or else the exclude one will be overridden. This can cause an error later (forgetting to put the conditions back), but it is a workable work-around.

I put in a feature request once, to let me put in complex boolean expressions, or somehow say "just this once, let exclude override".
https://www.madcapsoftware.com/bugs/submit.aspx

[cayennep]

It does make sense, tho I think the way I'm using it having exclude overrule would have worked better.

I'm find to use it differently, but in other tools the conditions are actually available to be used for more complex situations than this, so they are more powerful. For me, I'd rather control what's in a TOC at the TOC level, and then also include things it links to. This would free up conditions for other uses, and also free up my time when trying to reuse.

just my $.02...

[wclass]

For me, I'd rather control what's in a TOC at the TOC level, ...

For me, only half my projects have TOCs, so I generally don't think from a TOC point of view. It would be nice if a tool could cover all our options.

[cayennep]

hmm, can you talk about how you work, without a TOC?
interesting...

[wclass]

We do some with and some without TOCs.

Many of our standard applications can be used from a Windows/PC or a web front end - for these I generate CHMs and webhelp (and release notes and import guides), with a TOC and conditions on the topics to get the right output for each platform. Most of the info is the same but since there are differences between the platforms I have different TOCs and I manage the build using a set of conditions.

But we have other "applications", which are probably better defined as procedures, where I have created unrelated help topics that all live in a "knowledge base" that is really one big Flare project. This help file explains things like how to use our Word templates, or what documents must be generated for a certain procedure, or how to do something in SharePoint, and a whole host of short office specific information. It is the sort of things that probably could live in a wiki type knowledge base. If you are in a Word document, or an Excel spreadsheet, or whatever, you click a help button (on the ribbon) and a help topic is displayed, usually in a long thin window/panel down the side. I use CSH calls to get to the right topic. A lot of this knowledge base stuff just needs a single page. There are a few more complex procedures that have Next/Prev buttons, or tabbed information. So for a lot of the information, not only is a TOC not really relevant, I don't want to use up the screen real estate displaying one. Some of the information might need to be delivered as a set of HTML pages that needs to be stored in someone's own folder, so I need to be able to generate a target with those pages only, but they don't need a TOC.

I keep them in the one Flare project because I can re-use my standard style sheets etc. Technically, when I compile, it compiles with the default TOC, but I use a skin that does not display the TOC, so I don't worry about setting it up.

[Andrew]

It does make sense, tho I think the way I'm using it having exclude overrule would have worked better.

I'm find to use it differently, but in other tools the conditions are actually available to be used for more complex situations than this, so they are more powerful. For me, I'd rather control what's in a TOC at the TOC level, and then also include things it links to. This would free up conditions for other uses, and also free up my time when trying to reuse.

just my $.02...

I've noticed that a lot of people who don't normally work with online help-centric tools (like Flare and RoboHelp) get confused over this, because they are used to looking at documentation from a TOC perspective. I started my professional career with RoboHelp, at a place whose standard practice was to produce almost exclusively online help, so the idea that a TOC is only a window into the help has been very natural to me -- a TOC is something that helps users browse the help, but in no way should it include every topic (which overcrowds the TOC, interfering with the browsability -- a TOC with 4000+ thousand topics in it is generally not very useful).

What you are talking about -- controlling what is in the help by what is in the TOC -- sounds worse to me. I have to make sure that all of my topics somehow link back to a topic in the TOC. I never know exactly what will be in my output and what won't.

[i-tietz]

I'm find to use it differently, but in other tools the conditions are actually available to be used for more complex situations than this, so they are more powerful. For me, I'd rather control what's in a TOC at the TOC level, and then also include things it links to.

What you are talking about -- controlling what is in the help by what is in the TOC -- sounds worse to me. I have to make sure that all of my topics somehow link back to a topic in the TOC. I never know exactly what will be in my output and what won't.

???
Maybe a little bit of "basic thinking" needs to be done:
Print is a strictly linear medium - in writing, printing and reading. The content is structured intuitively (if we're lucky), so users can find the piece of information they're looking for. Usually you don't have redundancies, i.e. saying the same thing again in 10 or so places.
HTML on the other hand is a hypertext medium (Hypertext Markup Language): Information is "portioned" into comparatively tiny topics which should be selfcontained, because noone knows what the user read before or what the next topic is that the user reads. Sometimes you need to produce redundancies to keep each topic selfcontained.

It's not hard to press hypertext into a linear structure or manual content into hypertext, but it's not the right choice for the medium. That's just like using a spoon to hammer a nail into the wall ... it works, but that's not the thing it's designed for.
Even the contents of the topics could be different for both media - having the same information in a browser and in a manual (or PDF) is a bit of a nuisance.

[cayennep]

I've said a few times that I've been single-sourcing and using online help for quite some time, but clearly differently than others, which is what I'll try to uncover. This is not a case of needing online 101 guidance but of meeting specific requirements.

I also said that other tools automatically include anything that's referenced/linked etc., so it's not strictly TOC but just for the general grouping.

While I would appreciate hearing how others use conditions, so far none are meeting my requirement - I have several TOCs/Targets, etc and I want to be able to mix and match topics into different groups. Pretty simple, and pretty common single-source task, from my experience. Flare conditions are not working for this currently.

[RamonS]

I also said that other tools automatically include anything that's referenced/linked etc., so it's not strictly TOC but just for the general grouping.

Flare does that unless you explicitly exclude it. Even more, Flare includes anything inside your project regardless if it is linked or referenced anywhere unless you explicitly exclude it. Maybe I misunderstand what your expectations are or what the specific problem is or both. That aside, the folks here are just trying to help....

[i-tietz]

I also said that other tools automatically include anything that's referenced/linked etc., so it's not strictly TOC but just for the general grouping.

Everything that is linked ... that's one thing. You could always post an enhancement request for maybe a checkbox in the target that does that. Compiling would probably take longer, because Flare would have to follow all links.

But
1.
We also have topics that are not linked from anywhere. We have embedded help and the connections needed for CSH are set outside of Flare ... embedded into the software. We don't have header files or alias files and most of those CSH topics are not linked from other topics.
2.
There are links that are made of javascript (i.e. popups) or topics have integrated dynamic HTML using javascript links (via "onclick" event).

How is Flare supposed to find out that those "things" are links and has to include the target?

As you see you have only seen your parcel of functionalities so far.
We looked at AuthorIt too and found it too inflexible for our purposes. With Flare you can do more - if you know how.

[cayennep]

Thanks all, still not sure how I'll handle and whether I'll switch from Flare, but interested in how you all are working. I'm still planning a phone call to madcap to see what the options are but onto other things at the moment.

It's great that flare is flexible enough for many to do what they need - perhaps it's not providing the out-of-the-box functionality on the other end. I also got used to working with author-it, where most here seem to be pretty flare-familiar.

So one question is, do you all use multiple projects for products? This does not seem ideal for reuse, but interested whether that's what some are doing.
There is a lot of crossover between our products, and more will be coming. So I have multiple product docs, with some crossover, in various stages of completeness. Which means I have to either:

1. let flare publish everything every time (not useful, and large number of files that aren't needed, plus search shows up everything) OR
2. Set conditions on all topics and images, and multiple conditions where there's reuse. This also limits using conditions to only publish/don't publish, whereas I have used them in a more complex way in the past so there were multiple layers. I understand it's on/off for publishing, but it does limit conditions capabilities

thanks again for any tips

[LTinker68]

So one question is, do you all use multiple projects for products?

No, I use one project per product, and some products have different levels or flavors, like basic and advanced, so I'll use conditions to control what content goes with what output. In the case of the basic and advanced levels of a product, the only conditions I really use are advancedOnly (to designate topics/info that's only applicable to the advanced version) and printOnly or onlineOnly (to design specific wording differences between the output types). As an example of the latter, I might have a toggler with the text "Click to view all screenshots" that has the onlineOnly condition applied to it, since I don't want that text to appear in printed output (the screenshots are already visible in print output -- nothing to click to make them appear).

I also tend to use one TOC for online and print with conditioning to specify print-only topics, like front page matter. I also use one stylesheet, although I do see the pros of using separate TOCs and separate stylesheets for the different output types (print vs. online) -- I just don't do that.

I should also mention that the way I break up content and organize topics makes it fairly easy to me to mark a whole folder as being advancedOnly. Also, when I write topics, I apply in-topic conditioning as I write instead of going back later to apply it. And personally, I tend not to import whole Word documents for the content -- I prefer to copy-and-paste the content into topics as I go so I can appy tags, classes, clean up the wording, and so on.

[TechnicalDisaster]

Cayennp,

I feel like I am in the same boat as you. I would like an option in a Flare target to only use the topics linked in the TOC when building the help system. This would save my team many hours of setting conditions throughout our development iterations. If Flare gave us the ability to only build topics from the TOC, making updates for us would be as easy as drag and drop the lastest feature version. As it stands we have to constantly swap conditions in the TOC and Content Explorer.

We've had many occasions where this has bit us in the butt. A customer will call with questions about Draft topics appearing in the html search results. Most of our projects contain over a thousand topics, and a dozen of our large projects contain well over 4,000. We miss apply proper conditions more than I would care to admit, and auditing our projects to ensure the content explorer is conditioned correctly is out of the question.

I suppose I can test this myself, but what would Flare do If I set every topic in the Content Explorer to Exclude? Would Flare build the project based on the topics in the TOC?