Batch build/publish not deleting removed files/Output folder

[jhamrick]

I'm building and then publishing Webhelp and a PDF in batch, and I'm seeing a couple of problem with the WebHelp that I can't figure out how to change. I'm also having problems with the location/creation of the Output folder.

1. When I delete a topic from my project altogether, it continues to exist in both the build and publish areas. Although I could manually delete the contents of the directory before the new build begins, this defeats the purpose of scheduling a batch job. Is there a way to get Flare to clean out the old build/publish before creating the new one.

2. Topics that are not marked "print only" are published in the Content folder with the WebHelp even if they aren't included in the TOC.

3. Is there any way to get the build to stop creating an Output folder in the Project folder and then to stop creating another Ouput folder within the specified output folder?
I'm trying to get the Flare project files integrated into our source control management system and then use the batch build/publish to make the help part of our continuous integration. Only source files and not generated output should be included in source control, but Flare seems determined to create an Output folder. The second half of the problem (creating a second Output folder in the build output folder) isn't critical, but it's just another layer that seems unnecesary.

Thanks!
Janice Hamrick

[LTinker68]

1. When I delete a topic from my project altogether, it continues to exist in both the build and publish areas. Although I could manually delete the contents of the directory before the new build begins, this defeats the purpose of scheduling a batch job. Is there a way to get Flare to clean out the old build/publish before creating the new one.

Normally Flare is supposed to clean out the contents of the appropriate output subfolder before it does another build. The publish destination is a different situation. If you're publishing to a different destination and enabled the option to clean the stale files, then it should automatically delete any files that don't exist in the latest build. I don't think I've ever had Flare not clean out the corresponding output subfolder. I tend to manually delete the parent output folder but that's to trick the browser into thinking it's going to a new site so it'll load the entire website instead of loading some elements from the cache. You're not building the output and publishing the output to the same file location, are you?

2. Topics that are not marked "print only" are published in the Content folder with the WebHelp even if they aren't included in the TOC.

Double-check your WebHelp target has the print only condition to be excluded. Also, double-check that those topics don't have both the print only and the online only conditions applied to them. If they do, then they'll be included, because an include overrides an exclude. So the online only condition is honored and the print only condition is ignored, but only when they're applied to the same content. (In this situation anyway.)

3. Is there any way to get the build to stop creating an Output folder in the Project folder and then to stop creating another Ouput folder within the specified output folder?

There will always be a parent output folder and there will always be subfolders, one for each target, even if you have only one target. You can specify a different location for the output folder, but it will still create a parent output folder then a subfolder for the output. I think this is done to keep you from inadvertently mixing two outputs into the same location. For instance, WebHelp and WebHelp Mobile are both a bunch of files and you wouldn't want those two set of files mixed together or have one set override the other set, so Flare goes to extreme lengths to make sure they never mix. And yes, there does seem to be a bug in WebHelp where if you specify a different output location then it still creates some files in a temporary folder in the output folder in the project, so make sure you report that at http://www.madcapsoftware.com/bugs/submit.aspx.

I'm trying to get the Flare project files integrated into our source control management system and then use the batch build/publish to make the help part of our continuous integration. Only source files and not generated output should be included in source control, but Flare seems determined to create an Output folder.

I believe most people who tie Flare into source control just don't select the output or analyzer folders be added to the source control project. The analyzer folder is another one you don't want to add to the source control because it's always changing and if you delete it, it will be recreated automatically. Does your source control program only allow you to select the project at the parent folder, or can you add the content and project folders without adding the output and analyzer folders?

[Andrew]

2. Topics that are not marked "print only" are published in the Content folder with the WebHelp even if they aren't included in the TOC.

Double-check your WebHelp target has the print only condition to be excluded. Also, double-check that those topics don't have both the print only and the online only conditions applied to them. If they do, then they'll be included, because an include overrides an exclude. So the online only condition is honored and the print only condition is ignored, but only when they're applied to the same content. (In this situation anyway.)

I suspect Janice was wondering why topics that are not in the WebHelp TOC are still present in the WebHelp output. If that is the case, the answer is because, for WebHelp (and HTML Help, and, I would guess, mobile help), Flare includes every topic that is not specifically excluded.

If you think about it, this makes sense; we frequently may include topics that do not appear in the TOC, but are linked from another topic (which may be included in the TOC, or the index, etc.), so we wouldn't want to exclude the linked file, and it's not reasonable to place *every* topic in the TOC, especially for large projects -- that leads to poor TOC design.

[ccardimon]

...it's not reasonable to place *every* topic in the TOC, especially for large projects -- that leads to poor TOC design.

Maybe I'm doing this incorrectly. The way I learned was, if the topic is not in the TOC, it doesn't get published. Am I wrong? Let me down gently. Hint, hint.

[Nita Beck]

Maybe I'm doing this incorrectly. The way I learned was, if the topic is not in the TOC, it doesn't get published. Am I wrong? Let me down gently. Hint, hint.

Well, I guess you can put an air mattress on the floor first... because what you learned is not correct when the target is a Help system (WebHelp, HTML help, DotNet help, Mobile WebHelp). For a Help target, all topics in your project are included in the generated Help system, regardless of whether or not they are present on the Help system's TOC. For instance, a Search may likely yield hits in topics that aren't on the TOC. The TOC itself is simply what determines what topics will be listed in the generate Help system's Contents tree. If there are topics that you do not want to appear in the generate Help system, you must conditionally tag them to be excluded. (TIP: You can exclude a whole folder of topics in the Contents Explorer [not on the TOC!] by conditionally tagging the folder, rather than all the individual topcis within the folder.)

When the target is a print target (PDF, Word, XPS), then what you learned is correct. If a topic is not on the TOC, it won't be included in the generated print document.

Frankly, I think it's unfortunate that MadCap uses the concept of "TOC" for both online and print targets. My best practice is to give my print TOCs a name such as "PDFOutline" instead of just "PDF."

[ccardimon]

Hi, Nita,

Thanks for replying. Guess I'm not totally lost at sea. Most of my output is in PDF format. So I'm correct in thinking my topics have to be in the TOC.

[jhamrick]

Thank you very much for the help!
The Remove Stale Files option solved the first problem.
The exclude print only condition solved the second problem.
I reported the Output folder with the temp files as a bug, and I will live with Output subfolder.
The build will let me avoid checking in the output and analyzer folders.
Many thanks for your help.

[Andrew]

...it's not reasonable to place *every* topic in the TOC, especially for large projects -- that leads to poor TOC design.

Maybe I'm doing this incorrectly. The way I learned was, if the topic is not in the TOC, it doesn't get published. Am I wrong? Let me down gently. Hint, hint.

Nita explained perfectly, but for a practical example, we have a help system with about 7000 topics. The TOC is supposed to help people find things, but if we included all of those topics, there would be so many topics that it would be hard to find the topic you want. We'd have books with 5 levels of sub-books, and books with 30+ topics in them. So instead, we use our TOC as a way to find our "high-level" topics, which link to the detailed information.

[ccardimon]

Nita explained perfectly, but for a practical example, we have a help system with about 7000 topics.

OMG, that's a lot of topics.

[Andrew]

Nita explained perfectly, but for a practical example, we have a help system with about 7000 topics.

OMG, that's a lot of topics.

Talk to trent the thief...if I remember correctly, he's got a help system with close to 20,000 topics.

(It's a help system we've been developing for the past 15 years or so; anywhere from 2 to 5 writers on the team at one time. It would be smaller if we'd designed it better from the start, but inertia is a tough nut to crack.)