Wrong topics included when publishing

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Wrong topics included when publishing

Unread post by John-Robert Loflie »

Hi,

I have a project with one TOC and around 1500 topics. A few of these topics (16) have been assigned a specific build value (RELEASENOTES).

When publishing the project in WebHelp, selecting only the RELEASENOTES build, the system properly creates the HTML output with the 16 topics mentioned above, but looking at the output directory, some other topics are also copied. These topics (40) have some other builds attached but do not have the RELEASENOTES build.

These extra topics are not included in the TOC, obviously, but they are indexed and they can be displayed by searching for the proper terms.

I have no idea why these topics are included, while some other very similar topics present at the same level in the TOC are not copied. I did not find any relevant difference that could explain the behavior.

I am using H&M 7.1.0, and publishing the project from the command line produces the same output:

Code: Select all

%hmpath% Repository\Repository.hmxp /HTM="Build\ReleaseNotes\%version%\index.html" /L="DocumentationReleaseNotesBuild.log" "/v=..\build_variables.txt" /I=RELEASENOTES
So far I have found the following workarounds, but none of them is really clean:
- Create a second TOC with only the desired topics. I then have to specify both /I=RELEASENOTES /TOC="SecondTOC" to get the proper result, as only the first one gives the problem mentioned above, and only the second one still produces a lot of topics.
- Delete the other topic files from the disk prior to starting the publish task.

Any idea?

Thank you.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Wrong topics included when publishing

Unread post by Tim Green »

Hi John-Robert,

By default, all topics are assigned the build option All Builds. if you want to only include specific topics with a specific build you must assign specific builds to ALL your topics, including the ones you want to exclude. Then you can turn off the build options for the ones you want to exclude and on for the ones you want to include. Otherwise all the topics "without" build options will be included, because they have the All Builds option and will always be exported.
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.
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Re: Wrong topics included when publishing

Unread post by John-Robert Loflie »

Hi Tim,

I have found what happens, thanks to your hint.

Builds are mentioned in two files:
- The main project ("Repository.hmxp"), for each <file> node and each <file-mod>node
- The (only) TOC ("table_of_contents.xml"), for each <topicref> node.

While the TOC was fine regarding builds (it contained no empty or "ALL" builds, and all topics are properly listed), the project file did reference topics in sub-directories in the following form (70+ matches):

Code: Select all

<file href="Topics/APP-CALC/*.xml" build="" filetype="topic">
  <file-mod href="APP-Calculator-abstract.xml" build="TRADINGHTML"/>
  <file-mod href="APP-Calc-Usage.xml" build="TRADINGHTML"/>
  <file-mod href="APP-Calc-Configure.xml" build="TRADINGHTML"/>
  <file-mod href="APP-CALC-Limitations.xml" build="TRADINGHTML"/>
</file>
As well as entries referencing an "ALL" build (50+ matches):

Code: Select all

<file href="Topics/APP-Intercom/*.xml" build="ALL" filetype="topic">
  <file-mod href="IntercomUsage.xml" build="TRADINGHTML"/>
  <file-mod href="IntercomConfigure.xml" build="TRADINGHTML"/>
  <file-mod href="IntercomLimitations.xml" build="TRADINGHTML"/>
</file>
As you can see in the above examples, the file-mod entries were fine, but the file entries, referencing directories, had empty build values. By fixing both (using TRADINGHTML), the published result is free from any extra topic.

My questions are then:
1. What are those file-mod entries, that we have never added intentionally, that look redundant with the entries in the TOC?
2. How can we ensure that the file entries (which, IFAIK, represent sub-directories and are needed to have H&M look for the topics) always have non-empty builds? H&M does not display the uilds associated to these entries in Project Files / Topic Files.

Thank you.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Wrong topics included when publishing

Unread post by Tim Green »

Hi John-Robert,

Please don't start manipulating the source code like that, unless you have actually been writing your own topics and projects as source code directly using the XML schema guide. You can easily create conditions that the program isn't expecting, which can lead to all kinds of strange errors. If you are not getting the kind of output you are expecting you absolutely do not need to manipulate the source code. Also, I don't know what TRADINGHTML is, but it sounds like an HTML editor, which you should NOT use for editing XML, which is a completely different language, even though it may look similar superficially. It is much better to use either a normal code editor, like Notepad++ or SublimeText, or a real XML editor.
Builds are mentioned in two files:
HM has its own way of telling itself how builds are defined, please don't try to second-guess it and edit its source. Yes, TOC entries and topic files have separate build options. Normally, they will be set together if you have only been manipulating them via the TOC, but you can also change them separately. To do that, you just need to go down to Project Files > Topic Files in the Project Explorer and you can set the build options for the topic files separately from the TOC entries there. The same applies to the build options for files in the Baggage Files section.

The methods for storing which topic and baggage files have which build options internally in the XML is specific and has developed gradually as Help+Manual has developed. It is much better to set the options via Help+Manual's own interface. Then you can be sure that they are stored correctly and will not result in other errors.
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.
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Re: Wrong topics included when publishing

Unread post by John-Robert Loflie »

Hi Tim,

The only manipulation outside of H&M editor is my attempt to change the build value of those entries. To be clear, TRADINGHTML is just one of our custom build values, nothing to do with any external editor. I haven't messed with the XML structure.

The thing is when I change these entries (the ones with "*.xml"), the publish result is fine. I would like to edit those properties directly from H&M, but the interface only allows me to change the build value for topics, i.e. file-mod entries, not for the file entries, as it is shown in the screenshot below:

https://1drv.ms/u/s!AhhRrRvpA2mNheVc7oI17NwKlBQv4w

How could I change this value from H&M?
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Wrong topics included when publishing

Unread post by Tim Green »

Hi John-Robert,
I would like to edit those properties directly from H&M, but the interface only allows me to change the build value for topics, i.e. file-mod entries, not for the file entries, as it is shown in the screenshot below:
This is absolutely possible. The problem there is just that you have selected the folder and not the files. You can't do a multiple set via the folder, that's why the Include in Builds context menu is grayed out. Instead, select the files directly. You can select multiple files with SHIFT+CLICK and CTRL+CLICK. Then you can set their build options on the files as well.

This also gives a clue to what your original problem may actually be: It is possible that you have been trying to set the build options for all the topics in a chapter by selecting only the chapter node. That won't work on HTML-based output formats, although it will for PDF and DOCX. The reason is that in HTML, it is quite possible for a topic to be present without having a TOC entry -- it can always be displayed with a hyperlink, and via search and the keyword index. In PDF and DOCX that's not possible, because they are single documents and anything not in the TOC cannot exist in the document -- it has nowhere to go. When you exclude a chapter node in HTML, all the sub-topic entries get excluded, because they no longer have anywhere to go in the TOC. However, the topic files are not excluded, because actually you didn't apply any build options to their TOC entries either. You just took away their place to go in the TOC.

So to summarize: When excluding an entire chapter, you need to select ALL the topics in the chapter to apply the include options to them. Otherwise only the main chapter topic will be entirely excluded. The TOC sub-entries will be excluded because their chapter entry is gone, but their files will still be included because the build options of the files couldn't be changed.

https://helpandmanual.com/help/index.ht ... builds.htm
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.
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Re: Wrong topics included when publishing

Unread post by John-Robert Loflie »

Hi Tim,

Thank you for taking the time to give me this constructive answer. I now have a better view of how topic include works in H&M.

Each of my topics in the TOC have an include in build value set.

I have just created an empty project with two Topic sub-directories and I cannot reproduce the issue. I have then stripped my project from anything useless and left only a few topics. I am sending you the zipped project in PM.

If you could have a look at it, here are the steps to reproduce the issue:
1. Unzip Repository.zip
2. Open Repository.hmxp
3. Click Publish
4. Select the WebHelp format and the path of your choice (I use Repository\Build\ReleaseNotes\index.html)
5. Under Include options, only select RELEASENOTES
6. Press Publish Now!

Observed result: Once the publishing process is done, the output directory contains cbim-usage.htm. From the result web page, searching for "cbim" returns a Usage result that leads to cbim-usage.htm.
Expected result: Once the publishing process is done, the output directory should not contain cbim-usage.htm. From the result web page, searching for "cbim" should return no result.

Do you have an idea why this happens and what action must be taken to prevent this?

Thank you.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Wrong topics included when publishing

Unread post by Tim Green »

Hi John-Robert,

Thanks for the project. What is happening is what I described: The topic in question (and some other topics) is only excluded in the TOC, so only its TOC entry is excluded. If you navigate down to Project Files > Topic Files and look at the include options of the topic file you will find that it is still set to the default of All Builds, and so it is being exported. :)
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.
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Re: Wrong topics included when publishing

Unread post by John-Robert Loflie »

I got it. I didn't realize that I had to assign the build value, in the Topic Files section, to every topic I do not want to have included in the published data.

The documentation scared me with these sentences:
Important: Setting topic file include options does not automatically set the corresponding include options for any linked TOC entries. You should always work directly in the TOC for topics that have TOC entries unless you have a specific reason for wanting to set the options for the topic files only.
If a topic file has no TOC entry (for example for popup topics or topics displayed in external windows) you must set include options directly for the topic file, in Topic Files in the Project Files section of the Project Explorer.

This is generally the only time when you should set include options for topic files directly. In all other cases you should set the options in the TOC unless you have a specific reason for wanting different options for the TOC entry and the associated topic file.
I was assuming that I was in the general case and I didn't have to play with the build values there, but I may have been wrong because the publish operation that I perform now is outputting only 15 files out of 1500. I will thus ensure that every topic among these has a proper build value set.

Thanks you for your help.

Btw, I will have a look at the issues you pointed in my project as well.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Wrong topics included when publishing

Unread post by Tim Green »

Hi John-Robert,
I was assuming that I was in the general case and I didn't have to play with the build values there, but I may have been wrong because the publish operation that I perform now is outputting only 15 files out of 1500. I will thus ensure that every topic among these has a proper build value set.
Normally, you should only need to set the include options in the TOC for topics that have TOC entries. That will automatically set the options for both the TOC entry and the corresponding topic file. If you then go to the Topic Files you can change the include options there and they will then be different for the file. However, if you then go back and change the options for the TOC entry again it will also change the topic file setting as well.

Changing the TOC entry's build options always also changes the build options for the corresponding topic file. Changing the topic file's build options never makes any changes to the build options to the corresponding TOC entry. To reset both to the same setting, you can either adjust the topic file settings manually, or just change the TOC entry setting. For example, if the TOC entry is set to NONE and the topic file entry is set to ALL, changing the TOC entry to ALL and then back to NONE will also reset the topic file's entry to NONE.
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.
John-Robert Loflie
Posts: 7
Joined: Fri Oct 12, 2018 10:18 am

Re: Wrong topics included when publishing

Unread post by John-Robert Loflie »

That's a precious piece of information. I now have a clear picture on how it works and how to use it the way it was designed to. I will review the topics list and ensure everything is properly set.

H&M is a great software, by the way.

Thank you.
Post Reply