wfx_Versions .list Format Tutorial
Andrew Berg
August 28, 2007
Note: while the .list format was made for the Total Commander plugin Versions, this tutorial focuses on the Firefox extension wfx_Versions, and some information may not apply to Versions.
I. Overview
The list is made of entries for each program separated by the end-of-line (EOL) character (each line has one entry). The EOL must be CR+LF (Windows) for releases prior to 0.14. 0.14 and newer support CR and LF EOLs. For more on the EOL character, see the Notes[1]. Each entry consists of 6 sections, each separated by a pipe character (|). The first section is for the name of the program. The second is for the URL to search. The third is where to begin searching for the string immediately preceding the version string. The fourth is the string that immediately precedes the version string. The fifth is the string immediately following the version string. The sixth (optional) is the version string to compare to. There is a giant list of entries you can add to your .list at http://seayough.home.ro/wfx_Versions/, aptly named giant.list. There are other lists out there that can be found with a web search. But what if the lists you've found don't contain a program you want to monitor? Well, that's the point of this tutorial. It will show you how to make your own entries for your favorite programs.
II. In-depth Section Outline
A. Name
Simply the name of the program.
B. URL
The URL of the webpage to search. This page will be scanned for the version string. wfx_Versions supports any protocol (e.g. http://, https://, ftp://) that Firefox supports.
C. "Start scan here" string
The contents of the next section will be searched for after this string. This is useful because the string preceding the version string may be present elsewhere, and the incorrect information would be found.
D. Before the version string
Immediately after this string, the following string will be collected as the newest version.
E. After the version string
Once this string is found, the collection stops.
F. Current version
If specified, this string will be compared to the collected string. If they match, the version is considered the same. If they do not match, or if the version is not specified, they are considered different, and the collected string is shown (the sting is always shown when using the test function).
In wfx_Version's edit utility, each section is labeled. The actual entry in the .list text file looks like this:
Name|URL|Scan starts here|Before version string|After version string|Current version
III. Making your own entries
Now that you have the format, you're just about ready to make your own entry. First you'll need an editor. Notepad works, but you can use your favorite text editor as well. Of course, wfx_Versions has a way of adding, removing, and editing entries on its own. Use whichever method is the most comfortable for you.
Find the webpage you want to scan. Now that you have the name, URL, and version number (you can see it on the page), you're half-way there.
The closer to the top of the page the version is, the better. It's also good if there is a organized listing of versions. It's very good if the latest version is before the older versions, or is in its own section/element. Since wfx_Versions scans the HTML, you'll have to as well. Don't worry if you don't know HTML; the language is simple enough that you should be able to find what you want.
Open your browser if you haven't already and go to the URL. Now look at the page source. Search for the version string. If it is found more than once, try to use the first one. Look for something unique not far before the version. If that particular string only appears once or has no other appearances before this section, you can use it for section C. Now select a string immediately preceding the version (include the program name if it is here). This could be as short as a tag (or even part of one). If this string only appears once after the scan string, you can use it. If not, select more until it is unique. Firefox's find feature works while viewing source, so you can use it to check for duplicates of a string.
Now select the character after the version. You can use more than that if you want for aesthetic reasons, but it isn't absolutely necessary. Now you're all done. To double-check your work, test it (run the scan, and if the correct version is returned, your entry is correct). If you don't get the correct string or if you get an error, recheck each section to make sure everything is correct.
IV. Example
In case you didn't quite understand, I've included this walkthrough using the extension's AMO page as an example.
The name is "wfx_Versions", the URL is https://addons.mozilla.org/en-US/firefox/addon/3830, and the version is listed on the page. "<div class="addon-feature-titleby">" looks like a good place to scan since it is unique, close to the version string, and defines where the extension title starts (which immediately precedes the version string). "wfx_Versions <span>" is good for the string that precedes the version string. Including "wfx_Versions" makes it a bit more organized, but it isn't absolutely necessary. "</span>" is good for the string following the version. "<" is sufficient, but using the whole tag provides a little organization. All done!
Be careful not to use the pipe character in any section, since wfx_Versions uses it to separate sections. However, wfx_Versions supports |, which can be used in an HTML page to show the pipe character without actually using it (which would mess up the scan).
Your entry should look like this:
wfx_Versions|https://addons.mozilla.org/en-US/firefox/addon/3830|<div class="addon-feature-titleby">|wfx_Versions <span>|</span>|
There is no single correct entry; as long as wfx_Versions can find the version you want, the entry is correct.
V. Notes
1. The end-of-line or EOL is what tells a program when a new line starts. Windows uses two characters for this - a carriage return (CR) followed by a line feed (LF). Unix and Unix-based systems use only a line feed, and Mac systems use only a carriage return. If a program doesn't support a particular EOL, it will fail to recognize a new line.
VI. Legal
Copyright 2007 Andrew Berg.
You may distribute this document freely, however, you may not modify it or charge a fee for it (you may charge for the exact cost of the disrtibution medium).
Special Thanks to Menet for an initial conversion to HTML, aNDreas Bolotă for making such a wonderful extension, and to anyone who reviewed my drafts and provided feedback.
The PGP signature for this document is available at http://www.digital-signal.net/bahamut/wfx_Versions_tutorial.html.sig