Document file names

As you might have already noticed, HelpSetMaker uses rather unintuitive filenames. Actually, the name of a STML file (and therefore the resulting HTML/Helpset files) is the hexadecimal representation of a 32 bit integer number.

HelpSetMaker hides file names almost completely from the user. They are only shown in the document tree as long as no :title has been set to a document. After that, the filename is always hidden and only used internally.

From the intern point of view, the filename is, however, the important identifier for each document. An important assumption within HelpSetMaker is that each document has a unique filename.

Earlier versions of HelpSetMaker before 0.9.4 tried to archieve this goal by using an incrementing counter for the document filenames, so that they are named docXX with XX being an always-incrementing number. This approach, however, had the severe shortcoming that it did not work when multiple co-workers edited a document simultaneously.

The current name-finding scheme fixes this weakness. There is, however, an extremely small probability that two documents happen to have the same name. To prevent this, each new name is checked against all other, already given filenames. So, the race condition is further constrained to cases where independent co-workers add new files to their respective working copies. The probability would only be of any practical impact if a noteworthy part of mankind edited your document simultaneously. Chances are good, however, that in this case this would not be your most important problem...

Thumbnail filenames

From version 0.9.4 onward, thumbnail filenames are also created by the “hexadecimal representation of a 32 bit integer”-scheme. This replaced the former algorithm which took name hashes as number source.