ClickHelp Documentation

Partial Update - TOC Update Algorithm


In this topic, we will provide you with information on the TOC merge algorithm during the Partial Update publishing mode.

How Does the Publication TOC Update Work?

ClickHelp uses topic IDs to match topics in your project to topics in the updated publication to figure out which topics already exist in the publication. The system performs the update based on two principles:

  1. The publication TOC is updated with as few changes as possible.
  2. Topics not involved in the publishing process (e.g. children or parents of the topics being updated) are not affected.

Basically, all topics that already exist in the publication are updated and if some topics are not there yet, they will be added to the publication if ClickHelp manages to find a proper location for them in the publication TOC. Topics are not deleted from publication during partial updates. If you need to delete some topics from a publication, consider either deleting them manually or using the full replacement publication mode. If ClickHelp cannot figure out where a topic should be added in the publication TOC hierarchy, the topic and its children will not be published (you will get warnings on that in the publication log).

Let's suppose you're publishing a topic having the "getting-started" ID. ClickHelp searches for a topic with the same ID in the updated publication. If such topic exists, its content and properties are updated. However, the position of the topic in the publication TOC or its visibility in the publication TOC are not changed, even if they are different in the publication and the project. This is done this way to follow the two principles mentioned above.

If there is no topic with the same ID in the publication, here is what happens:

  • ClickHelp checks the parent topic for the "getting-started" topic in the project.
  • If the parent topic exists in the publication, the "getting-started" topic will be added as its child.
  • If the parent topic does not exist but is going to be added during the current publishing action, the "getting started" topic will also be added. This means that you can publish entire branches of new topics this way, just make sure that the topmost published topics or, at least, their immediate parents have matching existing topics in the publication.
  • If the "getting-started" topic has no match in the publication, its parent has no match in the publication and its parent is not involved in the current publish operation, the topic and all its children will not be published, because the desired TOC location cannot be determined for it in this case.

Navigation Elements Handling

Your topics may have various navigation elements - See Also lists, Next/Previous/Top links, Breadcrumbs. When publishing such topics in the partial update mode, the navigation elements will be updated in the topics being published according to the target publication TOC. However, navigation elements in other topics (those you don't publish) will not be updated, according to the two principles stated above.

This may result in navigation inconsistency - the newly added topic will not be in the See Also list of its parent topic in the publication, if the parent topic was not published. Keep this in mind when using the partial update mode - you may need to update some additional topics even if you did not make changes to them, to make sure the navigation is consistent.

Cases on the TOC Merge Algorithm During Partial Updates

Here are some cases which you should pay attention to.

Case #1: Topics that do not exist in the target publication but need to be published, will be added to the target publication according to their current TOC position. 

You create a topic in a project:

And you'll see it in the same position in the publication TOC after partial update publishing:

Case #2: Newly created child topics will be added saving their TOC position.

Here is a topic without children in your project, and this topic was published in the past:

You decide to add child topics under it:

You select those child topics for publishing and publish them:

As a result, they will be added to the publication according to their position in the project TOC. This is what the target publication TOC will look like:

Case #3: Topics that are not selected for publishing operation will not be updated. This means that the content, headers, and footers of those topics will not be updated while the content, headers, and footers of topics you selected for publishing will be updated. If you make changes to the project Master Page, you'll need to use the Replace mode when publishing to make sure all your published topics have the new master page applied.

Case #4: If some topic was published previously, but now it's missing from the project (was deleted), its published version will remain in the publication. Topics are not deleted during the partial update publishing process.

So, here is a topic in our project:

And then we delete it:

If you publish the project in the partial update mode, it will not be deleted from your publication:

To remove a deleted topic from the publication you'll need to update your publication in the Replace mode to replace it entirely with the new TOC or delete a topic from the publication itself manually.

Case #5: If you publish a topic that already exists in the publication, the content will be updated. However, the topic position in the TOC will not be changed.

Here is a topic in a project:

We've moved it to a different place in the TOC and decided to update only this topic:

As a result, the content of the topic in the publication will be updated, but not the topic position in the publication TOC:

If you need to change the topic position in TOC, you can do it in two ways: drag-n-drop it in the publication manually or replace the existing publication by publishing the project in the Replace mode.

Case #6: Let's suppose you change the TOC node visibility for a topic in your project. When publishing this topic in the partial update mode, the TOC node visibility of the published topic will not change, because this may affect child topics which were not involved in the publishing operation. However, you can change this setting manually in the published topic, or use the Replace publishing mode.

Case #7: If you use the Partial Update mode to publish only Ready topics, keep in mind that the system will still process the Table of Contents structure from the top. If some topic is Ready, but its parent is Draft, the ready topic will not be published in this mode anyway. For example, the highlighted topics have the Ready status:

So they will not be published, because their parent is Draft:

To handle this, you need to change the parent status to Ready. Or you can use per-topic publishing - select the needed child topics using the Bulk Actions button and publish them. Read here how you can do this.

Case #8: A child topic will not be published if its parent topic is not in the publication, and is not going to be published this time.

For example, you decide to update a child topic of the parent called "Level 1":

However, the "Level 1" topic is not in the publication:

Because of this, the child topics cannot be published, until the "Level 1" topic is published or selected for the same publishing operation.