| < Batch processing | The STML command language > |
Until version 0.9.3, HelpSetMaker did not support collaborative work on a project in an appropriate way. While newer versions do not have any built-in parts for collaborative work, either, file structures and file contents have changed in a way that coordination of multiple co-workers though CVS, git or a similar versioning system is not obstructed any more.
Until version 1.2.0, problems could arise from the image data caching when working collaboratively as hsm.xml could contain conflicting changes which were not resolved automatically. This problem has been solved by moving the problematic information into the user-specific configuration file.
Generally, HelpSetMaker directory hierarchies can be controlled through versioning management systems like git, Subversion, or even CVS. Setup the system like this:
Define the main directory (the one containing hsm.xml) as project base.
Include the src/ subdirectory into the versioning management.
Include all subdirectories containing image libraries into the versioning management.
Exclude all other subdirectories from versioning management. This includes also the thumbnails/ subdirectory.
Generally, you will have to care manually that all files are included into the version management. If you forget about checking files in or out, you might get into trouble. Especially, the hsm.xml file and all the *.stml files within src/ must be in a consistent state! Note that e.g. CVS does not add new files automatically to the version control. You have to issue a cvs add on them manually.
With git, you should use the included GUI program to commit all changes in one chunk.
HelpSetMaker manages two sets of configuration settings: Document-wise and user-wise configuration:
Document-wise settings is everything which must be shared between multiple co-workers. Beside the *.stml files, this is the document tree configuration, the image library settings, and the labels.
User-wise settings are specific for one worker and should not be shared between co-workers. This is the basic configuration of the project's engine (show rendered/HTML output, render automatically etc.), image data cache and thumbnails, and the cursor positions in the project's documents.
All the document-wise settings are stored in the project's main hsm.xml file. It is mandatory to be managed by the version control system.
The user-wise settings are held in files below the presets/ directory of the project. Each user has a file with his own name in that directory. These files can be put under version control or not, it is up to the project manager to decide this. As these files are only changed by their respective owner, version control should never become confused about changes in them.
If you have multiple co-workers which have the same (user) name but work on different computers, you will not be able to put their respective settings files into the version management system.
HelpSetMaker does not force you to have all the images for a project below the project base. If you want to share the project among several authors, it could be sensible, however, to have all images within the project.
For image libraries which are located below the project base, HelpSetMaker stores relative path names automatically. Therefore, links to images in such libraries are always resolved correctly, regardless of the absolute location of the project.
If co-workers created new images and checked them in, the local image library management might be unaware of these pictures after a project synchronization. You should rescan for new images in such a case.
As HelpSetMaker has no idea about version management, it cannot solve any conflicts occuring during merging, either. There are two potential conflict sources:
Merging the hsm.xml may fail. You have to edit it manually in an editor before opening the project in HelpSetMaker. Merge problems with this file should be handleable easily as it has been designed with version merging in mind.
The single *.stml files could also have merge problems. As they are simple text files, you can edit them as you like.
If the files with the user-wise configuration settings have merge conflicts, you can either try to fix them or simply remove the complete file. The settings in these files can be recreated rather easily.
Generally, the configuration file scheme should allow mostly conflict-free work for all tasks but bigger changes to the project's document tree structure. If such redesigns of the whole project are scheduled, work should be serialized: All co-workers check their changes in, one “mastermind” checks out, does the changes, checks in again, and the complete team checks out again. Everyone else should only do changes to the individual documents of the project, not to the document structure.
| < Batch processing | The STML command language > |