Stamp Scoping

Introduction

Applying individual stamps to each and every document is a tedious chore, so we've developed the concept of the "scope" of a stamp. "Scope" is a user-specifiable rule that describes exactly which pages are covered by an individual stamp. The default rule says that one stamp covers one page, but the rule can be customized on a stamp-by-stamp basis. You can easily construct a rule so that one stamp covers a large number of files.

You specify the scope of a stamp through keyword parameters in the stamp's HTML anchor. All files or pages reachable by hyperlinks from the stamped page are considered within the scope of the stamp, so long as they satisfy the constraints specified by the keywords. Entering values for the keywords allows you to describe how many files -- and which ones -- are covered by the scope of any particular stamp.

Anchor Keywords

Definitions of the keywords appear below. Examples of their use are given in the next section.

URL_PATTERN=/<pattern>/

This defines a text pattern which the URLs of hyperlinked files must match in order to be considered within the scope of the stamp. The pattern may be either a literal text string (requiring an exact character-for-character match on some part of the URL) or a Perl regular expression , depending on the status of the REGULAR flag described below. The default for URL_PATTERN is // (the empty expression), which matches no additional pages.

REGULAR=<1 or 0>

If the REGULAR flag is set to 1, the text string in URL_PATTERN is interpreted as a Perl regular expression. Otherwise, the text pattern is interpreted as a literal text string which must match some part of the URL character-for-character. The default is 0, a literal string.

MAX_FILESIZE=<number>

Files over <number> kilobytes in size will be excluded from the scope of the stamp. The default is 100 kilobytes.

MAX_DEPTH=<number>

Files at a minimum distance greater than <number> links away from the stamped page will be excluded from the scope of the stamp. The default is 10 links.

MAX_FILES=<number>

At most <number> files will be considered in the scope of the stamp. Pages are counted in depth-first order beginning with the stamped page, and proceeding in hyperlinked order as those links are encounted in a top-to-bottom scan of subsequent pages. Files that fail the other constraint tests (url pattern, size, depth) are not counted against the total. The default is 100 pages.

Examples

You could make a rule that says, "I want this stamp to cover my home page and all of my other (reachable) pages not greater than 100K in length in directories x, y and z." Or you could say, "I want this stamp to cover all the GIF files linked to this page". Specifying such a rule is much easier than putting stamps on individual pages. It also allows you to stamp files (especially binary files, like sound and image files) that would otherwise be impossible to stamp (because you can only insert an actual stamp into an HTML file, not a binary file). With stamp scoping, you can set up an HTML file containing the actual stamp, then define the "scope" so that the stamp covers the binary files.