Software:Comica

From Blockipedia
Jump to: navigation, search

Template:SoftwareDetails

Overview

Comica is a comic downloader and viewer that utilises a custom-built framework for the parsing and downloading of comics from websites. The framework uses an open XML format that allows anyone to add support for additional comics.

There is full support for comic archiving and browsing. If archiving is enabled (within the Settings window), Comica will archive any downloaded comics; these comics can then be browsed as required via the navigation buttons located in the top-right of the main application window.

The original version of Comica was merely a testing harness used for creating the framework that powered the main web-comic download and parsing functionality; version 0.90 Alpha has since had its interface completely rewritten to be more user-friendly and will continue to be improved upon in future updates.

Requirements

Comica requires the Microsoft .NET 4.5 Framework which can be downloaded from the Microsoft site. If you're using .NET 4.0 (not recommended; please upgrade to 4.5), ensure that you are using the Full version instead of the cut-down Client version. Using the Client version of the framework will prevent Comica from being able to perform comic update checks; you will be notified if this is the case.

Comica has been primarily designed for the Windows range of operating systems. While versions of Comica prior to v1.20 have been tested and work on both Linux and MacOS, the same cannot be said for v1.20 and above due to Mono not correctly working with .NET 4.5 applications.

Name Change

Upon the v1.10 release (on 1st February, 2011), the name of the application was changed from Comical to Comica. This is due to there already being an (abandoned) application with the same name.

Usage

To be written.

Virtual Comics

To be written.

Keyboard & Mouse Shortcuts

Listed below are the non-obvious keyboard shortcuts. Please note that the Settings window can be used to change some of these shortcuts; these are the defaults. Comic mouse navigation shortcuts requires the mouse cursor to be physically within the comics list; this will be changed in a future update.

  • F1: View the application's ReadMe.txt file directly within Comica.
  • F2: Renames the currently selected comic.
  • F3: Opens the current comic's containing archive folder, if available.
  • F5: Reloads all comic definitions.
  • F6: Check all comics for updates.
  • Return: Downloads the latest version of the currently selected comic.
  • Space, MouseMiddle: Selects the next new comic within the comics list.
  • Escape: Minimises the main window. If ShowTrayIcon is enabled, Comica is also hidden. Also exists full-screen mode.
  • CursorLeft, BrowserBack, OemOpenBrackets, MouseBack: Goes back a comic in the current comic archive. Hold Shift to go to the first comic.
  • CursorRight, BrowserForward, OemCloseBrackets, MouseForward: Goes forward a comic in the current comic archive. Hold Shift to go to the last comic.
  • Shift+Left: Goes to the first comic within the current comic archive.
  • Shift+Right: Goes to the last comic within the current comic archive.

Double-clicking on an empty area of the current comic image will clear the comic display. Double-clicking a virtual comic will open its containing folder.

Command Line Parameters

Comica supports a number of command-line parameters that can be passed into the application when it starts.

Supported Parameters

  • -minimise, -minimize
Starts the main Comica window minimised, or hidden to the system-tray if ShowTrayIcon is enabled. This is typically used when Comica is set to start-up with the system so it doesn't get in the way.
  • -hidesplash
When Comica starts, it shows a small banner that indicates its loading progress; if you would prefer not to see the banner, passing in this parameter will hide it.
  • -hidesysmenu [Comica v1.20+, Windows only]
Almost all windows/forms within Windows have a system menu which can be reached by either clicking on a window's titlebar icon or by pressing the ALT key and then the Space key. Comica inserts new items into the menu that allows you to change the priority of the application, transparency of the main window, and whether the main window should always be placed above other windows.
If you would prefer to disable this feature, passing in this parameter will instruct Comica not to modify its window's system menu in any way.
  • -delay=X [Comica v1.20+]
Delays the start-up of Comica by X seconds. For example, specifying -delay=5 will delay Comica from loading any data (settings, comics) or setting itself up for five seconds. This is useful if you're running from a slow storage device as it reduces disk trashing.
  • -nostartupupdatechecks [Comica v1.20+]
Depending on your settings, Comica can perform a check when it starts to determine if there is an update to itself, its comics database, or any comic strips. If you would like to override these checks and disable them for any specific reason, passing in this parameter will do that.
  • -nomutex [Comica v1.20 Alpha 2+]
Specifying this option allows more than one instance of Comica to be run at a time. This is not recommended as multiple instances will interfere with each other in regards to their configuration files and data may be lost. At a technical level, the mutex is still created (so other versions of Comica know it's running) but Comica will not immediately exit as normal if it already exists.
  • -nopgo [Comica v1.20 Alpha 2+]
Comica uses a runtime version of Profile Guided Optimisation that is built into the .NET 4.5.1 framework to increase start-up speed by up to 60% on systems with more than one CPU core. Specify this option to disable this feature and prevent Comica from writing a small .pgo file to its settings directory.
  • -nopique [Comica v1.20 Alpha 2+]
Prevents Comica from enabling its error handling code and an uncaught error will completely bring down the application. There is no specific reason to use this option.
  • -basicui [Comica v1.20 Alpha 2+]
Prevents Comica from using visual styles and improved font rendering within its interface. This affects the main application and not any modules. There is no specific reason to use this option.
  • -portable [Comica v1.20 Alpha 2+]
Enables portable mode. All settings are saved into a directory called Settings within the directory that the Comica.exe application file resides. Not much testing has been done on this feature.
  • -staticlang [Comica v1.20+]
If Comica detects that you are using a US language operating system, it will convert UK language spellings to their US equivalents (eg. Favourite to Favorite). If you would prefer to use Comica in the language it was originally written in and you're using the US language, passing this parameter will disable any conversions.

Example

  • Comica.exe -delay=15 -hidesplash
Instructs Comica to delay its start-up by fifteen (15) seconds and to hide its splash banner.

Using Comica in Linux

Please note that this section will be expanded upon in a future update.

Get p7zip and extract it to Comica\Tools. Comica will now be able to utilise database updates.

Known Issues

  • v0.90 Alpha of the software was shipped with an invalid Comics database. Please press F7 and update the comics database as prompted.
  • Random crash when minimised to the system tray over a long period of time. Fixed in v0.99 Beta.
  • Marking a comic as a favourite doesn't always work. Partially fixed in v1.01.
  • Marking a comic as a favourite doesn't work if it has been update checked in v1.01. Fixed in v1.02.
  • Comic database updating doesn't work in v1.02. Fixed in v1.03.
  • Browsing through a comic's archive while downloading a comic confuses Comica's navigation. Fixed in v1.04.
  • Selecting Import Images from the Files menu while a comic's archive directory doesn't exist causes a crash. Fixed in v1.05.
  • Importing an image without a comic archive being selected causes a crash. Fixed in v1.20.
  • Infinite download loop during Download Comics Marked As New if any new comics are broken. Fixed in v1.20 Alpha 2.
  • The keyboard cannot be used to scroll around the current comic. This is a technical limitation that as yet cannot be overcome.
  • A crash when checking for comic updates in v1.08 if the latest .NET 4.5 framework isn't installed. Download it [here].
  • Crash when loading/saving settings. This is due to a Windows system which has a TEMP directory that Comica and/or the .NET Framework does not have write permissions to. Ensure the user-group Comica is a part of has the required permissions and that a tool such as IIS Lockdown hasn't been overly aggressive in its locking down of the system.
  • A scrollbar appears at the bottom of the comics listing in Linux (Gnome).
  • Some comics don't work despite correct reg-ex. Please upgrade to Comica v1.20 or higher.

V1.20 Alpha 1 & 2

  • All included plugins are incomplete to some degree.
  • Comic image gets cut-off when zooming with the ImageController plugin.
  • Delete Selected Plugin(s) within the PluginManager doesn't do anything.
  • Up/Down cursor keys don't work when focus isn't in comics list; not technically a bug, but it's somewhat of an inconvenience. v1.20 Alpha 2 provides ViewPreviousComic and ViewNextComic shortcut actions to help with this.
  • Very little logging in regards to plugins.
  • Inconsistent interface states (eg. buttons being enabled when no comic selected).
  • Works in every-day usage despite little targeted testing.

Definitions

Comica uses XML files to define comics, and each comic is described using a Definition entry. The Definition entry allows the description of various fields, the most important being LatestComicUrl and ComicImage. All fields are explained below.

The core of each comic definition is the ComicImage property as it tells Comica how to find a comic's image using a Regular Expression. Click the link for further information on RegEx.

Supported Attributes

  • Name
The human-readable name for the comic; generally the comic's official name. Must be HTML entity-encoded. eg. & becomes & amp; (minus the first space), otherwise there will be a loading error.
  • PublisherUrl
The website that publishes the comic.
  • LatestComicUrl
The location that contains the actual image of the latest edition of the comic. This can either be a path or a file. If this value is empty, it will automatically be populated with the value from PublisherUrl; this is a space-saving measure as both PublisherUrl and LatestComicUrl are the same in most cases.
  • Rating
The audience rating of the comic. The value should be written exactly as-is with its initial capitalised. Since v1.20, this can be any string value.
  • Genre
The genre of the comic the definition describes. Since v1.20, this can be any string value. If the Genre attribute is missing, then the default value of Miscellaneous will be assumed.
  • Description [Comica v1.20+]
The description of the comic, typically the original blurb on its site by its author.
  • Language [Comica v1.11+]
The primary language of the comic. This is the English-version name of the language.
  • Notes
Any notes for the definition. These notes are from the author of the definition (and not the comic itself), and typically includes information as such "This is an experimental definition; please note that it may break in the future".
  • VersionMode [Comica v1.04+]
Comica has two methods available for checking if a comic has been updated. They are as follows.
  • FileName
This is the original version checking mode, and also the least reliable. Comica uses just the filename part of the comic strip image to determine if it has already been downloaded or if there is a new version available.
  • Full (default)
This is the improved, and recommended checking mode. It uses the entire path, in addition to the filename, of the comic strip image to determine if it has already been downloaded or if there is a new version available.
  • AltText
If the comic typically has alt or title text (containing the punch line for a joke, for example), then specifying Alt will extract that text from the Alt HTML attribute, whereas specifying Title will extract the text from the Title attribute. Title is the most common one.
  • None (default)
No attempt is made to extract the alt-text from the comic strip image.
  • Alt
The alt-text is extracted from the ALT HTML attribute of the comic strip image.
  • Title
The alt-text is extracted from the TITLE HTML attribute of the comic strip image. Comic strip images typically use this method of specifying their alt-text.
  • RedirectUrl
To be written.
  • RedirectUrlIndex
To be written. 0 - (n-1).
  • ComicImage
This is the Regular Expression that is used to find the image of the comic on the LatestComicUrl page.
  • IgnoreImages [Comica v1.00+]
A list separated with semi-colons (;) containing image filenames that should be ignored if encountered when parsing the web-page for the current comic. This is a sub-string search, so "tes" will be matched within "tes.png" and "testimage.png". Example: "rbprev.jpg;rbnext" will ignore any image filenames containing rbprev.jpg or rbnext.
  • UseCookies [Comica v1.20+]
Instructs Comica that it should store any cookies that the comic's site creates. While somewhat rare, a comic site may require the user goes through an acceptance page before being allowed access to a comic; a cookie may be used to provide this mechanism.
  • Data
For internal use only.
Field Explanation
GoUpPath This is an integer specifying how far up the path to travel, stripping away everything before it. Useful for removing filenames from URLs. Example: Specifying a value of 1 will cause http://www.bootblock.co.uk/home/test.php to become http://www.bootblock.co.uk/home/ Requires Comica v1.00 or above
StripStrings To be written. Requires Comica v1.02 or above
PreviousComicUrl To be written. Requires Comica v1.08 or above
PreviousRedirectUrl To be written. Requires Comica v1.08 or above
PreviousRedirectUrlIndex To be written. 0 - (n-1). Requires Comica v1.08 or above
NextComicUrl To be written. Requires Comica v1.08 or above
NextRedirectComicUrl To be written. Requires Comica v1.08 or above
NextRedirectComicUrlIndex To be written. 0 - (n-1). Requires Comica v1.08 or above

Location of Definition Files

Comica stores all of its data in a directory called Comical (Comica used to be known as Comical; the directory name hasn't been changed for compatibility reasons) within the local user's application data directory. You can get to the directory by typing %APPDATA%\Comical into Windows Explorer.

Alternatively, you can use the About window in the Help menu; click on the Open Comica's Settings Directory link at the bottom of that window.

Custom Definitions

If you would like to add your own definitions to Comica, you will need to add them to a file called ComicsUser.xml. Navigate to the Comical data directory (as specified above) and make a copy of the Comics.xml file, naming the new copy ComicsUser.xml. Open it in a plain-text editor such as Notepad, and replace the contents within the <Definitions></Definition> section with your own definitions.

Definition Example

Below is an example of a definition for downloading the Dueling Analogs comic. Please note that this definition is entirely on a single line.

<Definition Name="Dueling Analogs" PublisherUrl="http://www.duelinganalogs.com/" Rating="Everyone" LatestComicUrl="http://www.duelinganalogs.com/" ComicImage="\d{4}\-\.(jpg|png|gif)$" />

Writing a Definition

This section is a stub and will be expanded upon in due course.

End URLs that end in path or domain with a slash / character.

Include AltText attribute if the comic has alt-text that contributes more than just the comic strip's name or date of publication.

Ensure the comic isn't already included and it works before submitting.

How Comica Works

Below details the various processes Comica goes through to perform its comic downloading function.

Downloading the Latest Comic Strip

Comica downloads the page listed at LatestComicUrl.

If RedirectUrl is empty, it will grab a list of all available URLs from the downloaded page. RedirectUrlIndex will determine which URL entry in the list will be used for the next step. First and 0 will select the first URL in the list, Last will select the last, and any other number will select that respective URL within the list.

If the returned page is determined to be an image, that image is then returned as the strip for the comic.

If the returned page is not an image, a list of all images within that page is obtained.

Comica goes through each image within the list and attempts to match any with ComicImage. If a match is found and the ComicImageIndex value isn't present, the image match is returned as the strip for the comic. If the ComicImageIndex value is present, it is added to a list of images.

If one or more image matches were made, ComicImageIndex will determine which image entry in the list of images will be returned as the strip for the comic. First and 0 will select the first image in the list, Last will select the last, and any other number will select that respective image within the list.

If any of the above hasn't returned an image at this point, Comica flags an error.

Downloading the Previous Comic Strip

...