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:

• If a matched link starts with "http://", it is ignored (because the resource is not local)
• A matched link starting with "file://" is perfectly legal. Doco will work out whether it's an output-document-relative or absolute path.
• If the link can possibly be part of an output of the source document (i.e. pointing at, or within an output of itself), then it is excluded from the match algorithm. This exclusion list includes:
• The source document itself (e.g. func_spec.txt)
• Any versioned copy of the source or output documents (e.g. func_spec_v<anyVersion>.txt or func_spec_v<anyVersion>.html)
• Printable versions of the output, if it was split into pages (e.g. func_spec_full.html or func_spec_v<anyVersion>_full.html)
• Any page of the output, if it was split (e.g. func_spec_10.html), including when these pages are versioned (e.g. func_spec_v1.0_10.html)