SCDB 3 - Simple Comics Database Files

***** README FILE for Version 2.1 *****
I    Background
II   Technical Information
III  Installation - First Time
     A.  Linux
     B.  Windows
     C.  OS X
IV   Installation - Update Existing Install
V   Limitations
VI    To Do List
VII   Version History

== I - Background ==
I have a decent sized comics collection, about 3,000 or so, and wanted something besides a spreadsheet to keep them inventoried. I tried a few collection managers like GCStar, Datacrow and others but wasn't all that pleased. The main gripes I had were that they didn't focus on comics, had lots of features I didn't really need, required other packages like MySQL to be installed, were buggy, and/or all were fairly desktop centric. That's when I decided to write my own. 

When I set out to write what would eventually become SCDB 3, I listed out a few things that I wanted from it. Basically that it run on any desktop, didn't require anything special to work and only did the things I required it to do (add, edit, delete, print). I investigated several languages and toolkits for SCDB, but all would lead me to the same thing as the already established apps: something that would require extra packages to run and be desktop specific. Then I remembered XUL. I had played with it back in 2005, but wasn't too pleased with it then. It was a bit immature and the documentation for doing anything besides building the GUI was just shy of non-existent. I revisited XUL again and found that it had matured quite a bit and although documentation was still a bit slim, it was much better than what I had originally found. So I decided to give it a shot and the results have been satisfactory.

Going back to my list of requirements for XUL, I used it as a starting point for the writing process. The first iteration, SCDB, was a trial and error proof of concept approach. With version 0.9.1, I had gotten it stable enough but really didn't like the underlying structure.  So I rebuilt it using the knowledge I learned the first time around.  That got me comfortable enough with XUL and its associated technologies to give it a third rewrite.  That brings me to SCDB 3.  The biggest change is that SCDB 3 uses the Storage API to store data in a small SQLite database.  Using this approach for data storage fulfills the final requirement I had set out.  That SCDB be OS agnostic.

SCDB 3 is licensed under the GPL V2.  I'm putting it out here in the wild hoping that 1) anyone interested in XUL will find if helpful; 2) anyone needing a simple comics inventory program will find it useful; 3) anyone with spare time on their hands will port this over to another OS besides the big three of Linux, OS X and Windows; and 4) anyone who sees any major issues with it will let me know.

Enjoy!


== II - Technical Information ==
As stated in Section I, SCDB 3 is built using XUL.  In actuality, there are six components: XUL, XULRunner, Javascript, CSS, XPCOM and Storage.  This framework is the same as used by Firefox (up to version 41), Pale Moon, Thunderbird and other Mozilla-based applications.  Using this framework allows applications such as SCDB 3 to run on any OS that these applications run on with little change.

XUL is the markup language used to create the windows and dialogs.  Much like HTML, it provides a simple way to create rich applications that can be used as plug-ins in Firefox or as stand alone applications such as this one.

XULRunner is the runtime engine for XUL.  It handles all of the messy bits of displaying your application, interpreting Javascript, talking to XPCOM, etc.  Although XULRunner can be installed as a stand-alone package, I have included it is part of the download.  The chief reason for this decision was due to bugs introduced with new versions thanks to the accelerated release cycle.  XULRunner versions used by SCDB 3 for each platform are:
     Linux: 39.0
     Windows: 39.0
     OS X: 39.0

Javascript is...Javascript.  In the case of XUL-based applications/plug-ins, it's what does the dynamic stuff like open dialogs, put data into fields, etc.  It also gives you the ability to make calls to and from XPCOM.

XPCOM is the Common Object Model used by XUL applications to interface with the operating system.  XPCOM allows reading and writing of files, getting directory names, etc.  Without this piece, SCDB 3 would not be practical.

CSS is...CSS.  Just like HTML, XUL uses CSS to style the visual elements of an application.


== III - Installation - First Time ===
Installation is based on your specific OS.

I highly recommend you read through the Help pages within SCDB 3 to familiarize yourself with the application.

=== A.  Linux ==
1.  Download SCDB 3.
2.  Unzip SCDB 3 in the location of your choice.  This will be the location where it is executed.  /home/<username>/bin would be a good location.
3.  Run SCDB 3 using the included binary (scdb3).  You can do this by:
    - in your favorite file manager, navigating to the application root directory (I.E. - /home/<username>/bin/SCDB3) and double-clicking on the binary icon called scdb3.
    - opening a command terminal, changing to the application root directory and executing the binary (I.E. - ./scdb3)

On first run, a default backup directory will be created by SCDB 3.  This will be /home/<username>/Documents/SCDB3-Backup  This is where backup copies of the database will be stored.  If this is not where you want to store backups, create a directory where you want to backup the database then change the default backup directory via the Configuration tab under File --> Preferences.  You can change this location at any time. 

=== B. Window ===
1.  Download SCDB 3.
2.  Unzip SCDB 3 in the location of your choice.  This will be the location where it is executed.  C:\Users\<username> is preferred and C:\Program Files are a couple of good locations.
3.  In the SCDB 3 root directory, double-click on scdb3.exe.

On first run, a default backup directory will be created by SCDB 3.  This will be /home/<username>/Documents/SCDB3-Backup  This is where backup copies of the database will be stored.  If this is not where you want to store backups, create a directory where you want to backup the database then change the default backup directory via the Configuration tab under File --> Preferences.  You can change this location at any time. 

=== C. OS X ===
1. Download SCDB 3.
2. Unzip SCDB 3 in the location of your choice.  This will give you a directory called SCDB3.app.
3. Move SCDB3.app to your /Applications folder.  An icon should appear in your Launcher.
4. Run SCDB3  by clicking on the icon in Launcher.

On first run, a default backup directory will be created by SCDB 3.  This will be /home/<username>/Documents/SCDB3-Backup  This is where backup copies of the database will be stored.  If this is not where you want to store backups, create a directory where you want to backup the database then change the default backup directory via the Configuration tab under File --> Preferences.  You can change this location at any time. 


=== IV - Installation - Update Existing Install ===

***** You must do the database update in steps 0 through 8 before updating SCDB3 itself.

0.  Backup your current database twice.  Once to the standard location (SCDB3-Backup) and once to somewhere outside of the SCDB3 application structure (i.e. - your desktop, etc).
1.  Download and unzip the SCDB3Update utility.
2.  In the SCDB3U directory, run the following based on your OS:
     -  Windows: scdb3u.exe
     -  Linux: scdb3u
     -  OS X: scdb3u
3.  Select File --> Select Database from the menu.
4.  Navigate to the database that has not been updated and select it.
    NOTE: Databases are named scdb3.sqlite (for active databases) or <backup name>.scdb3backup (for backup databases).  Leave one current backup as not updated, just in case the update fails and you have to fall back to the previous version.
5.  Acknowledge the Begin Update dialog.  You have the option of performing the update (OK) or cancelling out of it (Cancel).
6.  Upon clicking OK, the update will be performed.  Progress will appear in the log window.
7.  Once the update is complete, repeat steps 2 through 5 for other databases.
8.  When all databases are updated, select File --> Exit.
9.  Move the SCDB3 directory to a backup (i.e. - rename SCDB3 to SCDB3.previous).
10.  Run the install of SCDB3 steps for your OS as listed in section III above.
11.  Restore your database per the SCDB3 Help instructions.


== V - Limitations ==
There are no known limitations with using SCDB3.


== VI - To Do List ==
- Ability to delete multiple titles
- Code cleanup
- Due to Mozilla's dumb-ass move away from XUL/XPCOM, move this over to the using Pale Moon's implementation.


== VII - Version History ==
0.1 - 0.7
 - Complete rewrite of SCDB II 0.2.3

1.0
 - Initial production release.

1.1
 - Corrected display of stray label in data entry form.
 - Fixed issue where selecting Publisher would not refresh listing until a letter or All was selected.

1.2
 - Corrected issue where deleting only or all issues in title would not empty the list forcing closing and reopening of the issue listing.
 - Added scrolling to keep selected row in view for title list.
 - Corrected issue with notes not showing up in issue listing window.
 - Corrected issue with HTML export.
 - Tweaked formatting of backup file names.
 - Tweaked title deletion confirmation prompt to size correctly on Windows.

2.0
 - Added wish list feature (available under Tools).
 - Added help for wish list feature.
 - Added ability to select, create and delete database files.  Allows for keeping separate inventories.
 - Added grading definitions in data entry form; select the grade then click on the "i" to see the definition.
 - Fixed backup date; month was off by one.

2.1
 - Fixed links in the About screen.
 - Fixed typos in the grading definitions.
 - Modified how grading definitions are displayed (hover over the selected grade instead of a separate click).