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. 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 (yet you will get warnings on that in the publication log). 

	Important
The system doesn't change topics' positions and doesn't delete topics from publications during partial updates. If you need to move topics or delete them, consider moving/deleting them manually or using the Full Replace publication mode.

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 and 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 just to make sure the navigation is consistent even if you did not make changes to them.

Cases on the TOC Merge Algorithm During Partial Updates

Here are some cases to 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 Full Replace mode when publishing to make sure all your published topics have the new master page applied.

Case #4: Topics deleted from the project will remain in the publication

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 with the Full Replace mode to replace it entirely with the new TOC or delete a topic from the publication itself manually.

Case #5: The Partial Update mode updates the content of the topic that already exists in the publication but not its position in the TOC

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 Full Replace mode.

Case #6: The Partial Update mode doesn't affect the TOC node visibility of the published topic

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 that were not involved in the publishing operation. However, you can change this setting manually in the published topic or use the Full Replace publishing mode.

Case #7: Updating topics that have the Ready status

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. Alternatively, 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:

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

Back
to top