Hi all,
I hope I've put this in the appropriate forum, so do feel free to move it if it fits in better on another one.
This is a somewhat general question soliciting advice on structuring a help project. Our software has two personalities, one for each type of client (sales house or agency). Thus I have created two Custom Builds ready for use. The content for each personality is 95% identical but there are a handful of dialogs and windows which have slightly different buttons/menus/appearances etc.
My question is, do you think it better to have:
1) For each applicable topic, have two sections, each of which is surrounded with Condtional Text directing it to the relevant build, or
2) Two separate topics to contain the information and use the Builds which include this topic: checkboxes in the Topic Options tab to control the output. I would want to use identical topic names in the TOC and manually select sensible names for the Topic IDs.
Any additional file size would not be an issue. I'm just trying to think down the road which method will be better to use when it comes to making amendments.
All comments or suggestions are most appreciated and welcomed.
Eric
Conditional Text or Separate Topics?
Moderators: Alexander Halser, Tim Green
- Tim Green
- Site Admin
- Posts: 23186
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Hi Eric,
How you do this really depends on how much common text you have in the two topics involved. If they share a lot of text it will generally be more practical to use one topic and conditional text. If they are very different it is generally easier to split it up into two topics.
If you use two separate topics you should consider using embedded topics for the text that is the same in both versions. This will enable you to avoid having two different copies of the identical text. When creating the "source topics" for your embedded topics always remember to disable all the "Builds which include this topics" options in the source topic's Topic Options -- otherwise a copy of it will be included invisibly in HTML Help and can be found by the user with Search.
See the help for more details on working with embedded topics.
How you do this really depends on how much common text you have in the two topics involved. If they share a lot of text it will generally be more practical to use one topic and conditional text. If they are very different it is generally easier to split it up into two topics.
If you use two separate topics you should consider using embedded topics for the text that is the same in both versions. This will enable you to avoid having two different copies of the identical text. When creating the "source topics" for your embedded topics always remember to disable all the "Builds which include this topics" options in the source topic's Topic Options -- otherwise a copy of it will be included invisibly in HTML Help and can be found by the user with Search.
See the help for more details on working with embedded topics.
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
- Martin Wynne
- Posts: 2656
- Joined: Mon May 12, 2003 3:21 pm
- Location: West of the Severn, UK
Hi Tim,
Martin.
Isn't it always better to use an Invisible Topic for such embedded topic chunks? Is it still then necessary to de-select the All Builds option?Tim Green wrote:When creating the "source topics" for your embedded topics always remember to disable all the "Builds which include this topics" options in the source topic's Topic Options -- otherwise a copy of it will be included invisibly in HTML Help and can be found by the user with Search.
Martin.
- Tim Green
- Site Admin
- Posts: 23186
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Martin,
Yes, that's a standard part of using embedded topics, as described in the help. The only time you would embed a topic from the TOC would be if you also want to have it accessibel directly at one point in the TOC -- there's nothing at all wrong with that, if that's what you needIsn't it always better to use an Invisible Topic for such embedded topic chunks?
Yes, absolutely, always. As explained in the help, the invisible topics are only needed to "source" the embedded text at compile time -- H&M just reads a copy. If you don't exclude them they will be included as invisible topics and can be found with Search, which can be confusing the for the user and inflates the size of your file a little (just by the size of the text).Is it still then necessary to de-select the All Builds option?
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
- Martin Wynne
- Posts: 2656
- Joined: Mon May 12, 2003 3:21 pm
- Location: West of the Severn, UK
Hi Tim,
I also have several dummy invisible topics used as scratchpads, work-in-progress notes, etc.
I had previously assumed that invisible topics go into the output as separate topics only if they are explicitly linked to. I can go and de-select All Builds if it's necessary, but it doesn't appear to be so.
Martin.
This surprises me. I have been using embedded invisible topics a lot. I have not de-selected All Builds on them, but the invisible topics are not being separately compiled to the output and don't show up in the search. That's for Browser-based Help. Is CHM Help different, and if so, why?If you don't exclude them they will be included as invisible topics and can be found with Search
I also have several dummy invisible topics used as scratchpads, work-in-progress notes, etc.
I had previously assumed that invisible topics go into the output as separate topics only if they are explicitly linked to. I can go and de-select All Builds if it's necessary, but it doesn't appear to be so.
Martin.
- Tim Green
- Site Admin
- Posts: 23186
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Martin,
Hmmm... Thanks for noting this. This seems to have been changed since I wrote the help. I just tested it with CHM and the source topics in invisibles are no longer included unless there is an active link to them. I'm going to have to check this with Alex and possibly update the help...
Hmmm... Thanks for noting this. This seems to have been changed since I wrote the help. I just tested it with CHM and the source topics in invisibles are no longer included unless there is an active link to them. I'm going to have to check this with Alex and possibly update the help...
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
- Tim Green
- Site Admin
- Posts: 23186
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Martin,
Update: Nothing has changed. What is happening is that the topic is defined as a popup. If you are using JavaScript popups it is exported to the popup .JS file, so it is there but not accessible unless you link to it. The same thing happens in CHMs with JavaScript popups -- it's there, but it's only effect is to inflate the size of the CHM, it can't be found with search.
However, if you use normal plain-text popups in CHMs the invisible topics can be found with search unless you explicitly turn off their build options, because then they will be exported both to the .TXT popup file and as normal topics.
The same thing happens if you define your invisible topics as anything other than Popup -- the topics will be exported to your output as normal files unless you turn off all their build options.
Update: Nothing has changed. What is happening is that the topic is defined as a popup. If you are using JavaScript popups it is exported to the popup .JS file, so it is there but not accessible unless you link to it. The same thing happens in CHMs with JavaScript popups -- it's there, but it's only effect is to inflate the size of the CHM, it can't be found with search.
However, if you use normal plain-text popups in CHMs the invisible topics can be found with search unless you explicitly turn off their build options, because then they will be exported both to the .TXT popup file and as normal topics.
The same thing happens if you define your invisible topics as anything other than Popup -- the topics will be exported to your output as normal files unless you turn off all their build options.
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.