Hide popup topics in Help, show them in PDF

This is the place to discuss Help & Manual 4 issues. Please don't post questions on any other versions here!

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Hide popup topics in Help, show them in PDF

Unread post by Dean Whitlock »

Hello,
I am evaluating H&M4, and so far it looks very promising. One thing I would like to be able to do is to create topics that appear in an external window in online help (and therefore do not show up in the TOC), but do show up in the PDF file. They can't be invisible topics because I want them in the PDF. Is there another way to keep topics from showing up in the TOC?

(These topics don't have to show up in the PDF TOC either, as long as they are in the appropriate place in the body of the text.)

I have already figured out the external window part, using links from hotspots on a screen capture. It's the hidden/included part I haven't found documentation for.

Thanks,
Dean
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Dean,

You can achieve what you want to do with a little trick that is made possible by some of the powerful new features available in H&M4. Here's how it's done:
  1. Create your external window topic as an invisible topic in the Invisible Topics section. Open its Topic Options tab and select your electronic output format (e.g. HTML Help) in the "Builds which include this topic" section and leave all other sections unselected.
  2. Now hold down the CTRL key and drag the invisible topic into the TOC in the position where you want it to appear in the PDF output. Don't worry about hitting exactly the right place, you can always move the topic later. Note that this doesn't create a copy of your topic, it creates a second reference to the same topic (like two doors to the same room). This is where the magic begins... :)
  3. Now open the Topic Options tab of the new second-reference topic you just created in the TOC and select PDF Export in its Builds options. Leave all other options unselected.
That's it. Now when you compile to HTML Help (or Winhelp or whatever your electronic output format is) the "popup" topic will be excluded from the TOC but included in the output as an invisble topic and will be available for linking. When you output to PDF the topic will be included in the TOC and its content will be output in the correct position.

Neat, no? 8)

Note that to be included in PDF a topic must be in the TOC, by definition. That's why it's necessary to take this route to do this.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Tim,
That is indeed a neat way to deal with it.

Thanks for the quick reply. In general, I've been impressed by the forum: your quick replies and the intelligent input from the other members. You've also done a good job on the on-line help, which I've used a lot since downloading the evaluation version on Monday.

Now to convince management...

Dean
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Oops, just discovered a problem.

My external popups are all child topics to a Chapter-with-text parent topic. I want the chapter/text parent topic to compile in CHM help and in the PDF file. If I set its "Builds which include this topic" to be "All", H&M sets all of the child topics to be "All". If I set it to be only CHM and PDF, H&M again sets all of the child topics to match. I want the child topics to be only PDF. (These build changes do not get passed to the Invisible topics, which are the original versions, only to the child topics, which are the second references. And it is only when I change the final child topic that the change is made to the parent topic. Prior to that, the parent Build list shows both "All" and "PDF", though they appear dimmed.)

Is there any way to give the parent chapter/text topic a different Build setting from the child topics?
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Dean,
Is there any way to give the parent chapter/text topic a different Build setting from the child topics?
The limitation is that for technical reasons you are not allowed to set all of the parent chapter's child topics to a different setting --- i.e. you cannot create any situation that will exclude all of the parent's children, because a chapter without children creates an error in the output format. However, so long as the parent has at least one child topic in all builds you create it will work.

What you need to do is exercise the control through the child topics, not through the parent. Instead of making any settings in the parent just go through the children one by one and set them to PDF or HTML Help (CHM). So long as the parent always has at least one child in all builds this will work -- if you then look in the parent's Topic Options settings you will see that PDF and CHM are both selected, but are greyed out.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

I was afraid you were going to say that...

Unfortunately, in the info architecture for this topic, it makes sense to have all the child topics be external popups in CHM but printed in PDF. They are field descriptions called up by clicking hotspots on a screen image. The parent topic contains intro text and the screen image. In CHM, the field descriptions popup; in PDF, they print sequentially. In other similar topics, there is additional information to discuss in child topics that are not external popups in CHM, so the problem doesn't come up.

Ah well, I shall create a child topic that isn't an external popup.

Thanks for the clarification. I really appreciate the quick and knowledgable replies.

And how do I submit a change request to EC Software? I've decided that it's a good program for what I'm trying to accomplish and worth putting in my suggestions.
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Dean,

You can mail in change requests directly to EC Support or post them in the Wish List section here on the forum. It's very unlikely that this would get changed, however, because a chapter with text without children is actually an error, by definition.

There are a couple of other strategies for dealing with your problem that you might want to consider:

There's nothing to prevent you from having more than one additional reference to each of your hidden external topics. So you could have an entire chapter in the TOC that you switch on for PDF only and off for HTML Help, and another entire chapter with the HTML Help version. Both these chapters could contain references to the same source topics in the Invisible Topics section. You can juggle the build options for these as you like, depending on what you want to display in which build.

Also, instead of making a second reference to your hidden external topics in the TOC you could make real topics in the TOC and "inject" the contents of the hidden topics into them using the Insert > Embedded Topic command. You can then enclose the embedded topics with conditional text tags inserted with Insert > Conditional Text to include and exclude the content depending on the output format or your own user-defined build conditions. If you use this approach the topic containing the embedded topic can have a different build condition from the embedded topic it contains, which might be helpful under some circumstances. However, it still won't get around the limitation that you aren't allowed to create a situation in which a chapter has no children.

These are not really direct solutions -- more pointers towards the kind of thing you can do... :)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Tim Green wrote:...a chapter with text without children is actually an error, by definition.
Oh, we could argue that one for hours! :wink:

In actuality, my text chapter does have children, it's just that all of them are "invisible" in one output and all are not invisible in another output, while the parent is not invisible in all outputs. (I use the quotes here because they are perfectly visible as popups, even though they do not appear in the online TOC).

The important thing is that I know the philosophy in use and can work around it. I've already discovered a relatively elegant solution to the specific situation that brought this all up. And you've provided several other possibilities for future situations. I'm just getting used to working with the concept of conditional text. Having a single source for multiple outputs is great - but challenging too. The suggestion I do plan to make involves using styles to indicate conditionality - I will add it to the wish list now.

Thanks again,
Dean
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Dean,
Dean Whitlock wrote:
Tim Green wrote:...a chapter with text without children is actually an error, by definition.
Oh, we could argue that one for hours! :wink:
Yes and no. None of the output formats know anything about build conditions or conditional text, all that happens before the source code for the compilers is generated. If a chapter in the TOC of an HTML Help project doesn't have visible children in the TOC it is by definition an error because in HTML Help the only thing that defines a chapter is having a child topic. If it doesn't have a child topic it's not a chapter.

This is something that has already been chewed through on the forum quite a lot for H&M3. In theory one would think that H&M could simply turn a chapter whose build conditions cause it not to have children into an ordinary top-level topic, but the programmers say that it's not that simple and that this effectively opens a whole other can of worms. I have to take their word for it... 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply