Power Feature: Snapshotting

Snapshotting is analagous to petrifying the state of related assets, so that items linked to by your document are effectively frozen in time. This means that if you are including (say) a diagram which you know may change (but your document is pertinent only to what that diagram looks like right now) then you can take a snapshot (copy) and your links will be re-pointed automatically.

Doco does this with the following directive:

 // snapshot <pattern> "<codeName>" //

..where <pattern> is a regular expression pattern, and <codeName> is any identifier of your choosing ("alpha", "moses", "2004-10-10" etc.).

An example would be:

 // snapshot .*\\.gif "Jan-2004" //

The above directive would snapshot all GIF images with a codename of "Jan-2004".

The <pattern> will partially match against links to other documents, images etc (in fact anything that can be linked to with an HREF). "Partial" matching means that if the linked asset contains the pattern then it's considered a match (rather than requiring an exact match, which would be laborious to enumerate).

The <codeName> is useful as it allows different documents (possibly authored by different people) to share the same frozen assets. Say you and a colleague are working on different technical documentation but you both include a diagram (and that diagram is subject to change, which your documents do not want to reflect). In that case, both of you can agree a codename to use for a certain state of that asset (e.g. "draft", "1.0", "alpha" or some made up funky-sounding name).

There is some behaviour of the snapshotting algorithm that is worth knowing about: