Hermes Manual
Click on the headings below for further details:
Overview
Hermes can be used to read RSS/RDF feeds, some Atom feeds, monitor website pages,
and raise alerts when one of
these sources produces text containing words or phrases of interest.
An RSS feed is essentially an xml web page that is regularly updated by the owner.
The content of the page is a list of news items. Standard RSS news items consist of
a title, description, link, publication date, and sometimes category information.
The Microsoft Feeds Manager (FM) that comes with Windows is able to read RSS feeds in
non-standard formats too, and when necessary an option can be set in Hermes
so that FM is used to load a feed.
Hermes' scrolling mechanism works by moving an item from the top of the list and then
placing it on the bottom. You'll see this happending if you move the scroll bar to the
bottom of the page.
Categories & Folders
Feeds, pages, alerts, and items, may include the names of categories they belong to.
The categories assigned to feeds are treated slightly differently to items as follows.
The category of a feed is treated as a folder and used for grouping feeds belonging to the same
category. The category assigned to the feed by the RSS provider is ignored in preference to
that given to it within Hermes when the feed is added. An item's category information is
treated as taxonic data and read from the feed itself. Both kinds of categories are managed
via the Cats tab. To distinguish between them, feed 'folder' categories are prefixed by
the '@' character.
Filter: When checked, items are filtered by category,
i.e. items pass if they belong to one of the enabled categories.
Note that category matching is not case-sensitive.
Show if new: If an item belongs to a category not in the list it will pass the filter.
Hide if none: If an item does not contain any category information it will not pass the filter.
[add category]: Pressing this button will add a new item category.
[add folder]: Pressing this button will add a new folder for feeds, pages and alerts.
Folder names are prefixed by an '@' character to distinguish them from item categories.
Note that the unprefixed name is also used as the default category for items without any
category information. For example, if an uncategorised item is read in from a feed belonging
to the folder "@Music", the item will be assigned to the "Music" category.
[rename]: Pressing this button will rename the selected category to the category
name given in the text input box. Note that specifying an existing folder name will
merge the selected folder with the specified one - changing its name in the process
too.
Category & folder options
[Left-hand checkbox]: Activates or deactivates the category/folder.
For folders, when disabled, all feeds, pages
and alerts belonging to this folder will be disabled too - overriding their individual
enable setting. When enabled, only those feeds, pages or alerts belonging to this
folder, that are individually enabled, will be enabled.
For items, depending on the "Filter" flag, when checked, only those that are members of this
category will pass the filter.
[X]: Removes the category/folder. Note that for folders, this will also remove all feeds, pages
and alerts belonging to the folder.
Text color: The default color for feeds belonging to this folder unless
overridden by individual feed, page or alert color setting. When unset, the default
color from the Display tab is used.
Include filter: When a filter is selected,
only items that match the filter will be shown.
Exclude filter: When a filter is selected,
only items that do not match the filter will be shown.
Filters are defined on the Cats page. Note that items not shown due to filtering can still be searched.
Feeds
Adding a new feed: On the Feeds tab a new RSS/Atom feed is set up by
pressing the "add feed" button and entering
a http url, such as:
http://mf.feeds.reuters.com/reuters/UKWorldNews,
http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml.
Pressing the "OK" button on the add feed page will then test that the feed works and create a new
feed entry, otherwise an error message is displayed. For non-standard feed formats
try using FeedsManager by ticking the relevant FM boxes. The feed may need to be
added to FM first. Remember to select a folder first - or create a new folder if necessary.
An 'access is denied' error is sometimes produced when the IE security level has disabled
data access across domains. To fix, navigate to the Miscellaneous section under the
IE security options tab: "Internet Options/Security/Custom Level.../Miscellaneous/".
Then enable "Access data sources across domains".
Restart sidebar for option change to take effect.
Date display format: When set, dates are displayed in this format, otherwise they are left in their original format.
See below for format specifiers, default is "HH:mm:ss E d NNN yyyy".
Flush cache: When checked, the item read status cache will be flushed before reloading
feed items when the new options are saved.
The cache is automatically saved and loaded during shutdown and startup.
Cross Compare: When checked, any duplicated items across the feeds are hidden.
[toggle]: This will toggle all the checkboxes of the same kind as the last
checkbox selected.
[FM import] & [FM export]: Pressing these buttons reads or writes
the feed list from Windows FeedsManager, which can be accessed via IE or Outlook.
Duplicate feeds are ignored. Folders for new folder names are created automatically
in a disabled state - so you'll need to enable them via the Cats tab before you can see them.
The feeds from the root FM folder are assigned to the folder '@Imported'.
Feed options
[Left-hand checkbox]: When checked, the feed items are displayed in the scroll window.
Apply rules: When checked, the common item rules are used to determine whether to
display items of the feed.
Show name: When checked, the feed name is displayed in the scroll window along
with the item title. Names are not displayed while in horizontal mode.
Use FM: When checked, the FeedsManager is used to fetch feed items. Note this
uses far more memory and currently results in a growing memory leak.
Compare content: When checked, items are tested for equality based on item title and
description, otherwise just their title is used.
Prune duplicates: Removes duplicate items from a feed.
Color: Overrides the folder color and the default color.
Interval: A feed is polled for new items every "update interval" minutes.
During feed updates, old items are removed if they do not appear in the new updates,
while an old item's read state is preserved if it does.
Top X: When set to a non-zero number, no more than that many items will be read
from the feed.
Date format: Most news items have a text field that specifies its publication date.
If the date can be converted into the required internal format it will be used to set the item's
true publication date, otherwise the time the item was loaded is used.
To determine if an item's date was converted correctly,
click on the item and inspect the date shown in the top right corner of the flyout
window. If this starts with a '?' it means the date couldn't be parsed. This will affect
how the expiration rules are applied to it.
When the item date format is non standard, you can specify it's
format using the syntax below:
Field | Full Form | Short Form |
Year | yyyy (4 digits) | yy (2 digits), y (2 or 4 digits) |
Month | MMM (name or abbr.) | MM (2 digits), M (1 or 2 digits) |
| NNN (abbr.) | |
Day of Month | dd (2 digits) | d (1 or 2 digits) |
Day of Week | EE (name) | E (abbr) |
Hour (1-12) | hh (2 digits) | h (1 or 2 digits) |
Hour (0-23) | HH (2 digits) | H (1 or 2 digits) |
Hour (0-11) | KK (2 digits) | K (1 or 2 digits) |
Hour (1-24) | kk (2 digits) | k (1 or 2 digits) |
Minute | mm (2 digits) | m (1 or 2 digits) |
Second | ss (2 digits) | s (1 or 2 digits) |
Fraction | f (up to 3 digits) | parses [.][1, 2 or 3 digits] |
AM/PM | a | |
Zone | z | postfix, parses [zone][[+|-]hh[:][mm]] |
Adjust | #[+|-]hh[:][mm] | postfix, offset added to time. |
Note the difference between MM and mm: Month=MM, not mm!
Examples:
"MMM d, y" matches: "January 01, 2000", "Dec 1, 1900", "Nov 20, 00".
"M/d/yy" matches: "01/20/00", "9/2/00".
"MMM dd, yyyy hh:mm:ssa" matches: "January 01, 2000 12:30:45AM".
"y-M-dTHH:m:sfz" matches "2011-09-06T00:01:35.123 GMT-07:00".
This is a good format to use for Atom feeds and some RDF/RSS feeds.
"y-M-dTHH:m:sfz#-02:00"
As above, but also subtracts 2 hours from final time.
"#-02:00"
Subtracts 2 hours from time using default format.
Units: Inputs requiring a time value in minutes can be post-fixed with an
alternate unit indicator: h=hours, d=days, w=weeks, m=months, y=years.
Filters
Feed items can be filtered based on their content. To achieve this an include and an exclude filter can
be specified on the Cats page for the folder that a feed belongs to. A filter is defined via a Javascript
regular expression on the Filters page. A common form of regular expression is
a list of words separated by 'pipe' characters, and surrounded by a pair of
forward slash characters, for example: "/The|quick|brown fox|/i". Notice the
trailing 'i' flag, which means ignore the case of the letters.
The quotes are not needed when entering expressions. This particular expression
will match any text that contains any one of these words: 'the', 'quick', or the
phrase 'brown fox', regardless of their case.
Options
Item rules
The following rules can be applied to an item when it is first loaded and subsequently
while it is scrolling.
New flag duration: New items are marked on the left by an RSS symbol.
This rule removes the symbol when the item has been scrolling for the specified
number of minutes. If zero, no mark is shown.
Keep duration: This rule removes the item when it has been scrolling
for longer than the specified number of minutes.
Age of item since pub date: This rule removes the item when it's publication
date age (i.e. the difference between the current time and pub date) exceeds the
specified number of minutes.
Read by date: This rule removes the item when
it's publication date falls before the read by date. When left blank the date/time used
is that at the point when the new options are saved. One of the valid date formats
is: MM-DD-YYYY HH:MM:SS ZZZ, where ZZZ is the optional zone, and HH is for a 24
hour clock.
Flags
Clicking item sets read by date to pub date. When checked, the read by date is set to
the item's publication date if it is more recent than the current read by date.
Clicking item removes new flag. That is, the item's RSS symbol is removed.
Hide item once read. After an item has been selected and read, it is removed.
Allow searching cache of read items. When set, after reading an item's details are kept
enabling both read and unread items to be searched in the Search flyout.
Otherwise, just the item's hash code is kept and used to track it's read status.
Sort scroll list by pub (load) date. Items from all feeds are displayed in
the scroll list by age (or load) order with the youngest first. Note: if the publication
date was not parsible then the load date is used.
Importing & exporting
The "import", "merge" and "export" buttons load or save all the settings to an xml file.
Note that importing clears out the old settings first, while merging overwrites
current feeds with the same id as an imported entry.
The "restore" button returns all settings to the default ones at installation time.
Display
Font
Family: Either select the font from the dropdown list, or type in the name of the
required font - which must be pre-installed to work.
Colors
Color values can be entered in the form of a standard color name, or via a hex hash value
(#RRGGBB), or via the color picker.
When scrolling vertically and the "Border" and "Background" color input boxes are left blank,
or set to "white" and "black" respectively, the scroll gadget will have the classic
theme, i.e. rounded corners. Otherwise it has a simplified theme, i.e. square corners.
To force the simplified theme in black and white, capitalize the color names: "Black",
"White".
Image
Specify the URL for a background image, or leave blank to use default. Image dimensions
should match those of the scroll window, such as 130w by 200h, otherwise there will be
a performance hit as the html rendering engine dynamically converts image size, e.g.
scrolling will become very slow.
Scroll window layout
Items are automatically scrolled by removing the top item and appending it to the
bottom of the item list. Use the scroll-bar to view other items in the feeds that
are currently not displayed. The item rules (see above) are applied prior to scrolling
the item.
Scroll horizontally: When checked, items are scrolled horizontally in the
form of a ticker-tape, otherwise they are scrolled vertically.
Hide hover / scroll bar: When checked, prevents the item title-url hover or scroll bar from appearing.
Auto click: The number of seconds to wait before automatically clicking on an item when hovering.
Set to zero to disable. WARNING: this functionality is currently a little temperamental!
Right to left: This is a first attempt at supporting languages with a
right to left reading direction.
When set, news item text is displayed right to left via the html 'dir="rtl"' property.
The direction of horizontal scrolling is then left to right too.
Note the width of the scroll bar is not set when horizontal scrolling and rtl.
Separate items with a line. A visual aid to separating items.
Scroll rate: The time between scroll increments. The default is 50 (milliseconds).
If zero, items are tested every minute without scrolling. Scrolling stops automatically
when the window is not full.
Height: The height of the scroll window in pixels.
Set to zero to return to standard sizes.
Width: The width of the scroll window in pixels.
Set to zero to return to standard sizes.
Mouse Buttons and Wheel
For the mouse wheel to function, the gadget must be selected, either by clicking on
the gadget or in the scrollbar area.
Left single-clicking: Clicking left mouse button over item produces a flyout
with further details.
Left double-clicking: Double-clicking (slowly!) goes directly to link.
Ctrl-key + Left-mouse: Holding a Ctrl-Key down, while then clicking left
mouse button, deletes the item.
Ctrl-key + Alt-left + Left-mouse: Deletes all items.
Ctrl-key + Alt-right + Left-mouse: Deletes feed items.
Shift-key + Left-mouse: Holding a Shift-Key down, while then clicking left
mouse button, removes the RSS symbol.
Shift-key + Alt-left + Left-mouse: Removes all RSS symbols.
Shift-key + Alt-right + Left-mouse: Removes feed RSS symbols.
Tip: once you have settled on your choice of feeds and options,
start by deleting all items, then the new items will stand out as they appear.
Searching & Keyword Highlighting
Pressing the magnifying-glass icon on the menu bar opens the keyword search page.
The current items, both read and unread, can be searched by entering
a comma separated list of keywords. This list of keywords can be saved and used
to mark matching items as they scroll. Searching with no keywords will return all
the current items. Note: searching is not case-sensitive.
The search can be narrowed by selecting a specific feed folder category or item
categories. Clicking the "sort" checkbox sorts the results by publication date.
Advanced Functions
The following functionality requires some knowledge of regular expressions as they are
used to detect phrases and other patterns in website content. So, if you
are unfamiliar with "Reg Exp's" please search on "javascript regular expressions"
for background information. Some basic examples are also included in the default
options.
Page Monitoring
Website pages can be monitored for changes in a similar manner to an RSS feed. The
Pages tab allows a new page feed to be set up. The strategy for monitoring a page
is to download the page at intervals, like an RSS feed. Then the page is examined
for changes using regular expressions, the hashcode of its content, or by examining
its header timestamp as an indication of its publication date. Based on this a report
is produced that acts as the description in a new news item about changes to the
page. The normal item rules are then applied during scrolling. Standard javascript
regular expressions (please consult web for syntax) can be used to examine a page's
content for specific changes. Using subexpressions it is possible to look for multiple
patterns on a page. Consequently, in some cases, when a page is examined a number
of matches may be found depending on the regular expression and page content. Three
kinds of news items can be generated:
success, when a desired match is found;
reject, when a match is found but it does not satisfy some further criteria;
fail, when no matches are found - possibly because the page couldn't be loaded.
For each kind of news item a title and description can be specified. These text
strings can contain special variables that are substituted for the specified match
subexpressions or a few inbuilt values such as the current Hermes version, see below
for their syntax. Finally, the criteria used to determine which kind of news item
to produce is encapsulated in a function - see
func below.
In most cases one of the inbuilt page checking functions can be used,
otherwise an anonymous javascript function must be supplied - which is either good or bad
depending on how technical you are.
Page options
Sort submatch index: When non-negative the matches are sorted alphabetically
based on the subexpression with the specified index. If the index is out of range
then zero is used.
Ignore: When checked, if no matches occur a news item will not be created,
otherwise a fail news item is created.
Positions: When checked, the character index of the match string in the page
are post-fixed to the match string returned by the substitution variables.
Timestamp: When checked, the page's header date is used as the publication date,
otherwise the date and time it was created is used.
pattern
This is a javascript compliant regular expression. Two forms are allowed:
regular expression A standard regular expression when no flags are
required.
/regular expression/flags The form when flags are required, such as
"g", "m" or "i".
The "test on url" and "test on text" buttons can be used to test the matches returned
by the pattern when applied to either the page located via the url, or the test
text that is entered in the input text box. The results, or any problems, are displayed in
the message box at the bottom of the dialog.
func
This specifies the javascript function that applies the criteria to determine the
kind of news item to create, i.e. success, reject, or fail. Either the name of an
inbuilt function can be given or an anonymous function. The inbuilt functions are:
HermesVersionPageCheck This tests the version number. Note, to work properly,
the page settings, e.g. pattern, must be as set in the example page that comes with
Hermes.
StandardPageCheck This simply tests if there were any matches, if so it generates
a success news item, otherwise a fail news item. Variable substitution is applied
prior to creating the item.
Anonymous functions The syntax for anonymous functions is:
"funcion(f,matches) { ... }",
but without the quotes.
Parameter
f is the feed object, which contains the success, reject, and fail
strings, e.g. successTitle, successDescription, etc., plus the content of the loaded
page.
Parameter
matches is an array of the results arrays returned by the javascript
RegExp exec method for each match found when the global flag is specified.
To learn more about the parameters you'll need to unzip the Hermes gadget file and inspect
"main.js" - apologies for not documenting these in this help page.
Variable substitution
The Hermes javascript function "ReplaceMatches(f,matches,str,
item, a)" returns the string formed by replacing variables in the string
str
by either a match value or inbuilt value depending on the variable name. The syntax
of the substitution variables is:
'$' {
match_index | '^' | '$' | '*' | '#' |
letter } [ '/'
subexpression_index
],
where
match_index is the index of the match to use, e.g. on a page, when
the global flag is specified, a number of matches may be found. The match index
refers to the order in which they were found, unless a non-negative sort submatch
index was specified, then the index refers to their alphabetical order. The
subexpression_index
is the index of the subexpression in the regular expression to use. So, "$0/1" would
refer to the second subexpression of the first match.
"$^" refers to the first match index, i.e. it's the same as giving a match index
of zero.
"$$" refers to the last match index.
"$*" selects all the matches.
"$#" returns the hashcode for the page. The hashcode value changes if the page content
changes and so is a quick way of checking for changes. It is used in the successDescription
string as a compact way of tracking page content changes - since a hash of the description is used
to track changes to a news item itself. Hence a change in the hashcode in the description results in
a change in the hashcode for the news item.
The
letter qualified variables are as follows:
"$c" the item categories. These are in the form of a lowercase list separated by "|".
"$d" the item description.
"$f" the feed folder category.
"$h" the item hash code.
"$l" the item link.
"$n" the feed name.
"$p" the item publication date.
"$t" the item title.
"$v" the version number of the gadget.
"$F" the alert folder category. (* see below)
"$N" the alert name. (* see below)
* When used as a pattern in an alert (see below), "$F" and "$N" can also be used in place of a
regular expression for matching the news item's feed folder and name with that of the alert.
For examples on how to use substitution variables and functions, see the pre-installed
page feeds.
Below is a listing of the function HermesVersionPageCheck, for further information
unzip the Hermes.gadget file and inspect the "main.js" file.
function HermesVersionPageCheck(f, matches) {
var title = null;
var description = null;
if (matches.length == 0) {
title = f.failTitle;
description = f.failDescription;
} else {
var ver = ReplaceMatches(f, matches, "$$/1", null, null);
if (ver > System.Gadget.version) {
title = f.successTitle;
description = f.successDescription;
} else {
title = f.rejectTitle;
description = f.rejectDescription;
}
}
title = ReplaceMatches(f, matches, title, null, null);
description = ReplaceMatches(f, matches, description, null, null);
return new MiniItem(title, description);
}
Alerts
Alerts can be generated when a particular news article occurs. For example, when
a news article mentions 'Microsoft' an email, sound, or flyout can be triggered.
When using alerts remember to enable the associated feed or page too!
pattern
The mechanism for setting up alerts is very similar to that for setting up a page
monitor (mentioned above). Regular expressions can be specified for matching on the
news item's, folder, categories, name, title, or description. A new alert item is generated
by calling a function that checks these regular expression patterns for a match
against the incoming news items. In most cases the standard function 'StandardAlertCheck'
can be used, see below for example code. This generates an alert item when a match
occurs for each pattern. Empty patterns are ignored.
success
The content of the alert item is determined by the title and description given under
the success tab. Note that variable substitution is applied to the strings prior
to generating the news item, as per page items.
func
This option specifies the function used to check for an alert event. In most cases
the
func value can be set to refer to the inbuilt function: StandardAlertCheck.
The code used in the standard alert checking function is as follows:
// Needs to be efficient since called frequently.
function StandardAlertCheck(a, f, item, idx) {
var p = null;
var t = null;
var ok = true;
var r0 = (a.reCategories == null) ? null : (t = a.reCategories.exec(item.categories), ok = (t != null), t);
if (ok) {
var r1 = (a.reTitle == null) ? null : (t = a.reTitle.exec(item.title), ok = (t != null), t);
if (ok) {
var r2 = (a.reDescription == null) ? null : (t = a.reDescription.exec(item.description), ok = (t != null), t);
if (ok) {
var r3 = (a.reLink == null) ? null : (t = a.reLink.exec(item.link), ok = (t != null), t);
if (ok) {
var matches = new Array(f.matchesFolder[idx], f.matchesName[idx], r0, r1, r2, r3);
var title = ReplaceMatches(f, matches, a.successTitle, item, a);
var description = ReplaceMatches(f, matches, a.successDescription, item, a);
p = new MiniItem(title, description);
ClearArray(matches);
}
}
}
}
return p;
}
Email
The email sending mechanism requires the ActiveX Object 'CDO.Message'. This comes
with most versions of Outlook and is usable even if you don't use Outlook as your
email client. It only needs to be installed, you don't have to set up any accounts
in Outlook.
When Outlook is the email client it may put the incoming Hermes emails in the junk folder,
so you may need to add the Hermes sender email address to Outlook's "Safe Senders" list.
Sound files
Alert sound notifications are produced by playing a sound from a wav format file.
The default file is 'C:\\Windows\\Media\\Windows Notify.wav'.
You will need to change this if your sound file is located in a different directory.
Running Multiple Instances
Current settings are stored in the gadget's file archive, so to run multiple instances
install multiple copies with a different name, such as Hermes1, Hermes2.
Performance
CPU usage is proportional to the number of active feeds and news items.
With about 10 active feeds and 50 active news items, CPU usage should be no more than one
or two percent - depending on the processor speed.
Flicker. On some machines flickering is noticeable during scrolling.
If anyone knows a way of eliminating this please let me know!
Tip: reducing the contrast via the Display tab helps.