Help: Mod Comparison Report

Overview

The Mod Comparison Report is a component of the TNG Mod Manager. The Comparison Report compares a site's mods (most particularly the version number) to

  • The mods in a second site, and/or
  • The corresponding mod articles in the TNG Wiki.

The primary purpose of the Comparison Report is to see whether the TNG Wiki has new versions of mods on the user's site. The report can display much more information than that, but one report option does focus on mods that have a newer version on the Wiki.

To run the comparison report, the user must click on the "Compare" tab in the Mod Manager. The Compare tab brings up a "kickoff form" through which the user can specify report options. There are three "levels" of options that control the contents of the report, plus a fourth section that specifies options that controls the display (formatting and highlighting) of the report.

Default values for most of the options on the kickoff form are specified in the Mod Manager Options screen. The Mod Manager Options screen also provides an option that determines which level of options are open the first time that the user invokes the kickoff form in a web browser session.

Top

The Report

The report starts by displaying the search specifications (which are provided by the Kickoff form).

As the report program starts to read the cfg files on the local site, it display the site address, and then, when it has finished reading them, it reports the number of .cfg file it looked at, and the number of mods it accepted. If a second TNG site has been selected, the program repeats that process with the second site.

If the report program has been told to compare the mods to the Wiki (which is almost always the case), it says "Reading Wiki Articles..." and proceeds to list the name of each Wiki article as it is read either from the Wiki Server or the cache. Reading Wiki articles from the Wiki server can take more than 2 seconds each, so if the program is not using the local cache, it can take several minutes to read all of the Wiki articles.

When the report program finishes reading the Wiki articles, it erases the list of article names, and displays the results table.

The Results Table

The results table has four sets of columns, each separated by a heavy border.
  1. General information about the mod
    • Mod name. If there are multiple versions of one mod, only the latest version is included in the report.
    • The .cfg filename.
    • The primary mod author. The author is determined as follows:
      1. First, the program looks for %author% tags in the .cfg file, and reports the author listed in the first %author% tag.
      2. If the .cfg file does not contain any %author% tags, the program looks at the Mod Author field in the sidebar of the mod's Wiki article. The program goes to some trouble to parse the contents of that field for the first author in case the field lists multiple authors.
      The author name is a hyperlink if it is hyperlinked in its source file, and the full list of authors is saved as pop-up text in the author column.
  2. Information about the Local mod; the .cfg file on the user's server, which is labeled as "Site 1"
    • Mod installation status (just like the Mod Manager's Mod List, except that color highlighting is optional).
    • Version number.
    • The "Site1 v Wiki" status - a comparison of the version recorded in the .cfg file and the mod version recorded in the Wiki article.
  3. Information about the Remote mod; the .cfg file on a second server, which is labeled ast "Site 2"
    • (Three columns corresponding the the three columns for Site 1).
    • The "Site2 v Site1" status, which is a comparison of the mod versions on site 1 and site 2.
  4. Information about the mod recorded in the Wiki article
    • Wiki status, which indicates whether a mod number was found in the, more than one Mod number was found, whether no valid mod number could be found, or whether the Wiki article is missing from the Wiki server.
    • Wiki version - the version number that is recorded in the "Download link" field in the Wiki article's sidebar. If more than one version number is found in that field, then
      1. The highest version number is displayed, and
      2. All of the version numbers in the the "Download link" field are strung together and can be viewed as a pop-up. A plus sign is placed at the end of the primary version number to indicate that there is more information in a pop-up.
    • Mod Update Date. This is not the update date of the mod article (which is basically meaningless), but rather is the Mod Update date, which is determined from
      1. The "Mod Updated" field in the Wiki article sidebar, or
      2. The highest date (irrespective of version number) found in the Revision History section of the Wiki article.
    • Wiki Article name, which is a hyperlink to the Wiki article.
    • of the Mod installation status (just like the Mod Manager's Mod List, except that color highlighting is optional).
    • When cached, represented as a date/time difference from "now" rather than as an absolute date/time. As discussed below, the Comparison Report does not necessarily read the Wiki article every time the report is run.(Reading all of the Wiki article is just too slow.) The Comparison Report keeps a cached copy on the user's web server, and can use the cached copy.

Other Report Details

  1. As noted above, if there are multiple copies of a mod on a TNG server, the report will only consider the .cfg file with the highest version number. If, for instance,
    1. Site 1 has the .cfg files for mod version 10.1.0.3 and for version 11.0.1.1, and
    2. Site 2 has just version 10.1.0.3
    The Comparison Report will not compare the two copies of version 10.1.0.3, but instead, will compare Site 1's version 11.0.1.1 to Site 2's version 10.1.0.3.
  2. The options that control the appearance of the Comparison Report are described in the "Kickoff Form" section below, but it is worthwhile to mention some aspects of those options here:
    • The highlighting of values within the status columns can be suppressed, but if it is enabled, then
      1. The installation status values are shaded exactly like the installation status values in the Mod Manager Mod List.
      2. The status values in the "Site1 v Wiki" and "Site2 v Wiki" columns are shaded with the same colors as the installation status column, but, of course, the values are different. The color do, however, have essentially the same relative meanings; viz:
        • Green (installed) is good,
        • Pink (unable to install) is "bad",
        • Orange (partially installed) is between good and bad, and
        • Whiteish (OK to install) is "normal".
      3. The Wiki status values are shaded in a similar way.
    • Depending on another display option that is labeled as "probably most useful for mod programmers", superscripts can be attached to
      1. The Author name, to indicate whether the author was defined in
        1. The Site 1 .cfg file,
        2. The Site 2 .cfg file, or
        1. The Wiki article
        and
      2. The Wiki Article name, to indicate with UC whether there is an Under Construction message in the Wiki article.
  3. When the Comparison Report is sorted by a column other than the mod name or the filename, horizontal bars are placed in the results table between values of the sort key. (It isn't useful to separate values of the mod name or the filename, since each mod name or filename value can be associated with only one mod.)
  4. Assume for the moment that
    • A second TNG site is included in the report,
    • Copies of a mod exist on both sites, and
    • The two copies are sufficiently different that the mod on one site is accepted by the search criteria and the mod on the other site is not.
    In such a case, only one of the two copies of the mod is included in the report. The blank space left in the report columns for the other site will likely imply that the mod does not exist on that other site. But the truth is that the mod just didn't match the search criteria. There is no easy way for the report program to know the difference between rejecting a mod and a missing mod, but perhaps that problem can be rectified in a future version.
Top

The 'My Mods' Report

Ron Krzmarzick created a version of the Mod Comparison Report that is specifically intended to be run remotely. That is, when it is installed on your site (as part of the Mod Manager Compare mod), you can link to it from, for example, a "See My Mods" link in a TNG Wiki page.

The program is named rrmodcompare_mymods.php. It

  1. Accepts some query-string parameters, but doesn't depend on a kickoff form.
  2. Compares non-private mods on your site with the Wiki versions,
  3. Omits several columns that are in the full Mod Manager Comparison Report, and
  4. Uses cache method 3, which does not update the cache.
Top

The Kickoff Form

The "Kickoff Form" is the form that you use to select report options and launch a Mod Comparison Report. The kickoff form is explained in some detail in the Mod Comparison Report TNG Wiki article

Top

The Mod Manager Options

For the most part, the "Mod Comparison Report" options section of the Mod Manager Options provides default values for the Mod Comparison Report kickoff Form. As with other TNG programs, the default options take effect only the first time you run a Mod Comparison Report. After that (until you close all copies of the web browser), the kickoff form's default values will be based on the options you chose for your most recent report.

See the Mod Manager Options section of the Mod Comparison Report TNG Wiki article.

Top

Caching of TNG Wiki Content

The Mod Comparison Report saves a cache of Wiki article data on your TNG server so that, when the report is run again, it doesn't have to undergo the slow process of reading each Wiki Article, and so that it does not drag down the TNG Wiki server performance. Unfortunately, there is no way to determine whether the relevant data in the Wiki article has been updated without reading the Wiki article, which would spoil the point of caching.

Consequently, the kickoff form specifies a cache age limit. If the cached data - for a specific Wiki article - is older than that age, the Wiki article will be re-read and its cache will be refreshed.

If you know (or think) that certain Wiki articles have been updated, you can refresh the cache for those specific articles if you:

  1. Search for those specific mods by name (or name substring), and
  2. Specify a small expiration time (say, 20 minutes, 10 days, 6 weeks - whatever is appropriate).

Once you have run a report showing those specific mods, you can, if you wish, then run another report without the name specification, and using only the cache, so that you see those mods and others in one report that runs quickly, because it does not have to read Wiki articles.