Build information is not synchronised in the Topics (*.xml) files

[Lina Castro]

We need assistance to resolve the following issue:

When working with synchronisation using TortoiseSVN, if a topic is created with a build assigned, this build information is not synchronised in the Topics (*.xml) files when colleagues synchronise. As a result, when publishing and we want to exclude topics associated with this build, they do not appear in the structure. However, if we perform a search for the topic, it is still published, and even a search using a similar name returns the topic, usually at the end of the results.
We are now using GitHub Desktop, but the issue persists.

How can we resolve this situation?

[Tim Green]

Hi Lina,

The build options for topics are stored in two places, since each topic has two build options: One for the TOC entry (which is in a separate list) and one for the topic file. The TOC entry build options are stored in the TOC file, in the \Maps subfolder. The topic file build options are stored in the .hmxp file, in the topic files section at the end of the file.

If you're not seeing the build option changes after synchronizing, then either the synch was not complete, or there is some damage in the TOC file or HMXP file where the data is stored.

One possibility is that at least one of your team members is storing their local copy in a OneDrive folder. Doing this spells disaster for your entire project. The only way to recover from this is to delete the entire current git repository, because it should now be considered to be corrupted or at least badly tainted. Then copy (NOT move!!!) a complete clean copy of the current project to a location outside of OneDrive, make sure everything in it is OK, and use that to create a fresh, clean repository. Then every team member needs to delete their old tainted copy and pull a new working copy from the new repository in a location outside of OneDrive.

[Lina Castro]

Hi Tim,

I've confirmed with my colleagues, and none of us has the repository in a OneDrive folder.
There must be another reason why the build isn´t appearing in the TOC file after synchronisation.

[Tim Green]

I've confirmed with my colleagues, and none of us has the repository in a OneDrive folder.
There must be another reason why the build isn´t appearing in the TOC file after synchronisation.

OK, thanks for the confirmation. This can only be a git or local cache problem, not a HM problem. Or you have some additional application that is interfering with the folder contents wherever this is happening. Help+Manual can only trigger git to do its work. It has no control at all over how that work is done.

[Lina Castro]

Hi Tim,

Thank you very much for your prompt response.

We are experiencing this issue with TortoiseSVN and are considering using GitHub Desktop to resolve it, but the problem persists. In your opinion, which application would you recommend we use to overcome this issue?

Another point: since the pandemic, we have been working via VDIs. Could this way of working cause any issues when using H&M?

Best regards,
Lina

[Tim Green]

We are experiencing this issue with TortoiseSVN and are considering using GitHub Desktop to resolve it, but the problem persists. In your opinion, which application would you recommend we use to overcome this issue?

First you need to figure out why your sync is failing. We can't do that for you remotely, and the whole SVN system (SubVersion server, Tortoise client) is also not our product, we just start it. You would need to consult with someone experienced with SubVersion.

Note, however, that SubVersion is now increasingly deprecated. Fewer and fewer vendors support it -- Collabnet has completely exited the SVN space, for example. Git has become pretty much the standard, and it is extremely powerful and very reliable. If you have the choice, it should always be the first choice.

Another point: since the pandemic, we have been working via VDIs. Could this way of working cause any issues when using H&M?

It is quite possible that doing that has something to do with your SVN issues. The whole point of using version control is that it makes it possible for you to NOT work online or remotely. Every author's local working copy should always be on their own local computer. You then only need to go online to synchronize with the master copy.

Remote access to a working copy can always cause errors. Also, you should never ever allow multiple users to access the same working copy. They are single-use and every user should have their own local working copy for their own exclusive use. If multiple users are remoting in to a single working copy that could easily be the cause of your issue, because they will be constantly overwriting each other's changes.

[Lina Castro]

Hello Tim,
Thank you once again for your prompt response.

Yes, we are currently testing the use of GitHub Desktop with the aim of replacing our current synchronisation tool. However, we are encountering an issue: when new topics are created, the build is lost in the TOC file during the first synchronisation by other colleagues.

Do you have any suggestions on how we might overcome this problem?

We always work on a local copy, although this local copy is stored on a VDI.

Best regards,
Lina

[Tim Green]

So you're having exactly the same problem as with your SVN repository. That shows that the problem is neither with the version control system nor with HM, but is something inherent in your own configuration, or your procedures.

although this local copy is stored on a VDI.

That is not a local copy so you should move to real local copies, on each user's own hard disk.

These settings are stored in the main HMXP file and the TOC file (NOT in the topic files), so what is happening here is either that a new version with the new build options set is being overwritten by another user's version that doesn't have it, or the files weren't saved yet when you synchronized. One potential reason for this, perhaps even the most likely, is that your VDI system has something equivalent to a proxy or cache or some other mechanism that delays actual writing of the changes. This is yet another reason you should never ever put your version control working copies anywhere except on each user's own local hard drive.

As a general principle, you also need to follow these guidelines when working with version control:

• Always synchronize directly before working and directly afterwards
• If you're not synchronizing within Help+Manual, always make sure you save before synchronizing. (HM will refuse to sync without saving.)
• Always check with other team members to make sure that you're not both working on the same things at the same time.
• Announce any TOC or settings changes like build options, sync immediately and get everyone else to sync directly after. This is important, because unlike with topics, everyone is always working on the same HMXP and TOC file at the same time — there is only one of each.
• Never stop work without synchronizing immediately.
• Never delay synchronizing. That, along with not synchronizing before you start work, is the most common cause of "overlap conflicts": User A has made a change on Monday but hasn't synchronized it. User B changes the same item on Tuesday and synchronizes it. User A tries to synchronize on Wednesday, but her change predates user B's Tuesday change, resulting in a conflict.

[Lina Castro]

Hi Tim,

Thank you very much for all the recommendations.

We rarely encounter synchronisation conflicts; our issue is that when a topic with a build is created, during the first synchronisation performed by a colleague, the topic appears without the build in the TOC.
We will try to set up a working environment where everyone has their own local copy on the hard drive, to confirm whether this resolves the issue.

Kind regards,
Lina

[Lina Castro]

Hi Tim,
With the help of our IT department, we installed H&M on our PCs and tested creating a topic with a build. The same issue occurs — when another user synchronises the project, the topic loses its build in the TOC.
From that point on, whenever anyone synchronises (even the user who originally created the topic with the build), the topic remains without a build in the TOC.
As a consequence, when we want to exclude topics with this build in a publication, this topic is always included, which causes us problems.
We can therefore conclude that the issue is not related to working on a network drive or on a local PC; there must be another cause.
We really need assistance in resolving this issue.

Kind regards,
Lina Castro

[Tim Green]

Hi Lina,

I understand your frustration, but this cannot be a problem with Help+Manual itself. Something is going wrong with your version control system, or your system configuration (outside of Help+Manual) that is interfering with your version control system.

First you need to know where the build settings that are getting reset are stored. The build settings for topics set in the TOC are stored in two locations: In the TOC file (stored in the \Maps subfolder) for the TOC entry itself, and in the .hmxp project file for the topic file that the TOC entry references. What is happening when you synchronize is that older versions of these files are overwriting the new versions. This, in turn, means that the version control system can only see those older versions.

The question is, why. This can't be Help+Manual, because it has nothing to do with the version control operation. It only starts it, that is all. One possibility is that you have a proxy server set up with a delay in its updating cycle, so that the version control system is always getting older versions of the files from the repository than those that have just been synchronized by users in other locations.

[Lina Castro]

Hi Tim,

Thank you very much for your reply. However, our working environment is always the same, and this problem only occurs when creating a topic.
When we find topics without a build in the Topics (*.xml) files area and change the build setting in the topic — by deselecting and then reselecting the build — the topic then appears with a build in the Topics (*.xml) files area as well. From that point on, once we synchronise, we all have the topic with a build in both areas.

Sorry to insist, but it does seem strange that, if this were an issue with our working environment, it would only occur when creating topics.

Kind regards,

Lina

[Tim Green]

Thank you very much for your reply. However, our working environment is always the same, and this problem only occurs when creating a topic.
When we find topics without a build in the Topics (*.xml) files area and change the build setting in the topic — by deselecting and then reselecting the build — the topic then appears with a build in the Topics (*.xml) files area as well. From that point on, once we synchronise, we all have the topic with a build in both areas.

This is new information and puts a very different light on the situation. It's really very difficult to provide meaningful assistance if you only provide partial information about your issue.

You need to know how the build system works for topics. Every topic actually has two build settings: One for the TOC entry, which is just an element in a list of links pointing to the topic files; and one on the actual topic file itself. When you set a build option in the TOC, it automatically also sets the option for the corresponding topic file. When you set one on the topic file it does NOT set one in the TOC. That is normal and by design.

[Lina Castro]

Hi Tim,
I apologise if I haven’t been clear. I’ll explain our issue again, this time sending images to illustrate it more effectively.

1.png

2.png

3.png

I hope I have now managed to explain the situation more clearly, and once again, I apologise for not having been clear in my previous explanations.

Resolving this issue is very important for us.

Kind regards,
Lina

[Tim Green]

Hi Lina,

Thanks for the detailed descriptions. Unfortunately, your screenshots are such low resolution that even when I save and expand them it is impossible to see the names of the topics or the builds, so the "changes" you describe are just blobs that cannot be distinguished from the blobs that they were before the the changes.

However, I can only repeat that we are not the people you need to ask about this. This is NOT a Help+Manual issue. It is an issue with your version control system. We cannot help you with this, because it has nothing to do with Help+Manual. If you can close your project after creating the topic with it s build options and then open it again and still see the build options, then you can be 100% certain that Help+Manual is working correctly. The problem is with the version control system and how it is working or configured, and that is not something we can help you with.

I can only provide you with the background information on where the data is that is not getting synchronized. So, again: The build options for the topic files are saved in the .hmxp file. Here is a simple example, in which just one file has a build option (if you edit the .hmxp file in a code editor you will find this section down at the end of the file):

Code: Select all

<project-files>
    <file href="Topics/*.xml" build="ALL" filetype="topic">
      <file-mod href="HM_QuickStart_Explorer.xml" build="CHM,HTML,PDF"/>
    </file>

There, all the topic files without build options are defined by the *.xml in the main <file> tag. Files with build options are specified with <file-mod> tags inside the main <file> tag pair. In this case, the file HM_QuicksStart_Explorer.xml is only included in CHM, WebHelp and PDF.

What is happening with your synchronization is that the HMXP file containing this information is not being merged correctly with the other copies. WHY this is happening is something that can only be discovered by an expert for your version control system with local access to your entire configuration.