Publishing Problem: Builds in TOC vs Project Files

[Mark Jerde]

In Microsoft's Live Writer it is very easy to handle text and screenshots. Here is the blog post I created while investigating the publishing issue.

http://markjerde.blogspot.com/2010/01/h ... issue.html

[Tim Green]

Hi Mark,

It is normal and desirable that topic files and their TOC entries can have different build options. These are two different objects and there are many good reasons for them to have different build settings. For example, your help system may contain files that you only want to make available by linking, without TOC entries. Then you would exclude the TOC entry and include the topic file only. The same applies to topic files you are only including as snippets -- although there you want to exclude both the TOC entry and the topic file, as the topic file is not needed at runtime at all (it is only copied into the other topic at compile time).

From your description I'm not at all sure how you have arrived at your current build settings for these topics. If you can provide 1-2-3 instructions for reproducing an issue we'd be happy to check it, but I'm pretty sure it is not a bug as these mechanisms are fundamental and very thoroughly tested. The logic is quite simple: When you change build options in the TOC the topic file build settings are changed automatically. When you change build options on the topic file the TOC build settings are not changed automatically. This is necessary to enable you to apply different settings to the two items.

[Mark Jerde]

Hello Tim.

I admit I don't understand the H&M details very well. As usual there is great pressure to finish and deliver by last month... Therefore we are very results-oriented. We don't have the luxury of working through any H&M samples. We started the project by importing 500 files and have met requirements and solved problems as we encountered them. We use the very first solution for each need or problem. I am sure there must be better ways than some decisions we have implemented. Next project we may do better -- though by that time our tool may be H&M 7 and again we will slam full-speed into the guard rail, scattering all sorts of debris behind us as we smash our way around the learning curve...

I studied your reply and H&M Help before posting this. Perhaps the main issue is that I don't understand the fundamentals of H&M's "Builds". ISTM that if the topic in Project Files is

Text_Files.xml (All Builds)

then this topic should appear in, umm, ALL BUILDS! It seems to me that in our project it should appear in all 10 Custom Builds, for a total of 30 separate deliverables. (Each Custom Build is to have a PDF, CHM and HTML.) But so far none of the 20+ xml topics marked "All Builds" (apparently by default when created in H&M) have shown up in unexpected Builds.

*** FLASH *** *** FLASH *** *** FLASH ***

I just figured it out. I will leave the above paragraphs untouched to show how badly I was confused about H&M. I have owned H&M since 2002 IIRC. I am an "occasional but heavy-duty" H&M user, a reasonably-competent programmer and an extremely-competent computer user. But I was confused... That almost never happens anymore. I will write an outline below of something I think would have saved many hours, and I suggest it be included in future H&M Help. It would have saved me time, and may help others understand H&M quicker too.

"All Builds" does indeed mean "All Builds". I didn't notice the unexpected topics because I had been generating just PDF and CHM output and didn't see the "All Builds" topics. I got the idea of making HTML for a single-topic "stub build" to see exactly what is created. Yes, the "All Builds" topics are there, not TOC accessible from index.html but they can be displayed via search.

I understand now. I didn't a few paragraphs ago.

I'm glad this happened. If it hadn't we would have shipped 30 documentation products with unwanted, invisible, but searchable topics!

Reproducing the error is trivial.
1. Create a new help project. Use the default Table of contents.
2. Select Introduction in the TOC. Drag Welcome topic and Second topic into the Introduction Page Editor. This creates links to these two topic on the Introduction page.
3. In the TOC set the Build to PDF for Introduction, Welcome topic and Second topic.
4. In the TOC set the Build to CHM for Chapter 2, Overview, Sub chapter 2.1 and New topic.
5. Publish both PDF and CHM to verify the expected results.
6. Set the Introduction topic Builds to both PDF and CHM.
7. Publish the CHM. Observe the Compiler Messages about topics Welcome topic and Second topic.

It is so obvious, now that I understand!

Please see this post for my recommendations. ... and realize I'm trying to be helpful!
http://markjerde.blogspot.com/2010/01/h ... ue_08.html