PSPComic version 0.9.6 Beta
A Comic Book Reader for the PSP!
Copyright (C) 2007 Jeffrey P. (AKA Archaemic) & Christophe Rudyj (AKA Kip)
========================================
Table of Contents
I.	Usage
     a. Installing
     b. Adding comic books
     c. Controls
	1. Comic book (normal mode)
	2. Comic book (zoom box mode)
	3. Menu
     d. Menu options
II.	Compiling from source
III.	Notes
IV.	Frequently Asked Questions
V.	History
VI.	Legal
VII.	Credits
========================================
I.	Usage
========================================
     a. Installing
----------------------------------------

To install this program, you must have either firmware 1.50, any custom
firmware, or any other firmware that can emulate firmware 1.50 through DevHook
(such as 2.71 running Homebew Enabler (HEN)). To install this program, place the
folders pspcomic and pspcomic% in the MS_ROOT/PSP/GAME folder if you are running
or emulating firmware 1.50 or if you have your version of OE set to 1.50 kernel
mode, or in the MS_ROOT/PSP/GAME150 folder otherwise.

To run the program, go to the Game option in the top menu of the Cross Media Bar
(XMB), sroll down to the Memory Stick option, and select PSPComic from the menu
It should now run.

----------------------------------------
     b. Adding comic books
----------------------------------------

The process of adding comic books to the memory card is quite simple. Just put
the comics in the folder "comics" at the root of the memory stick. As of version
0.9 beta, subdirectoriesare not supported and will be ignored by the program.
The file must also not have a name longer than 200 characters, or else it will
also be ingnored by the program, due to the limitations of the UnRAR library.

----------------------------------------
     c. Controls
----------------------------------------
	1. Comic book (normal mode)
----------------------------------------

D-Pad:	  Pan
Triangle: Zoom in (hold to enable zoom box mode)
Cross:	  Zoom out
Circle:	  Rotate clockwise
Square:	  Rotate counterclockwise
Select:	  Fit page to width/full size
Start:	  Open menu
Left shoulder:	Previous page
Right shoulder:	Next page

----------------------------------------
	2. Comic book (zoom box mode)
----------------------------------------

D-Pad:	  Move zoom box
Triangle: Exit zoom box mode
Cross:	  Exit zoom box mode
Circle:	  Shrink zoom box
Square:	  Enlarge zoom box
Select:	  No action
Start:	  Open menu
Left shoulder:	Previous page and exit zoom box mode
Right shoulder:	Next page and exit zoom box mode

----------------------------------------
	3. Menu
----------------------------------------

D-Pad:	  Scroll
Triangle: Go back
Cross:	  Select
Circle:	  No action
Square:	  No action
Select:	  No action
Start:	  Close menu
Left shoulder:	Scroll up skipping some options
Right shoulder:	Scroll down skipping some options

----------------------------------------
     d. Menu options
----------------------------------------

- Open comic book...
	Open a menu to select which comic book to switch to
- Close comic book
	Close the current comic book and return to the top menu
- Next comic book
	Open the next comic book in the list
- Previous comic book
	Open the previous comic book in the list
- Jump to page...
	Select a page to which to jump
- Load bookmark
	Jumps to the page currently set as the bookmark for the current comic
	book.
- Set to bookmark
	Set the currently open page as the bookmark for the current comic book.
	Each comic book can currently only have one bookmark.
- More bookmark operations...
	Further operations that can be done on bookmarks
  - Delete bookmark for this comic book
	Delete the bookmark for this comic book
  - Delete all bookmarks
	Delete the bookmarks for all comic books
  - Purge bookmarks
	Delete the bookmarks for comic books that are no longer on the memory
	stick
- Configuration...
	Open the menu of configurable options
  - Toggle resize method
	Switch method with with to resize the page. Options are nearest neighbor
	(default) which is blockier but faster, and simple resample, which is
	slower and blurrier, but often makes text slightly easier to read.
	Please note that the page you're currently on is not reprocessed, and
	the change doesn't take effect until you zoom, rotate or change the
	page.
  - Adjust clock frequency
	Change the frequency of the clock. If it is higher, panning will be
	smoother and page operations such as resizing and rotating will be
	faster, however, more battery will be consumed. The default clock
	frequency of the PSP is 222 MHz. Speeds under this are not recommended
	because the program will slow down immensely, but will save battery.
  - Adjust pan rate
	Change the rate at which comic books pan using the D-Pad. Units are
	pixels	per pan increment (about 50 times per second, ideally; much less
	in practice). The default is 20.
  - Turn on/off zoom level persistence
	Toggle whether or not the zoom level is retained between pages. The
	default is off.
  - Turn on/off rotation persistence
	Toggle whether or not the rotation level is retained between pages. The
	default is off.
  - Adjust menu scroll skip rate
	Change the number of items skipped in the menu when using L and R. The
	default is 5.
  - Turn on/off manga mode
	Toggle whether the comic starts on the left or the right side when
	changing zoom or rotation levels. The default is off.
  - (Do not) jump to bookmark upon loading comic book
	Toggles whether the program should automatically jump to the bookmark
	set in the current comic book (if applicable) upon loading a comic book.
  - Turn on/off full view mode
	Toggles whether a comic book should be displayed in 1:1 zoom upon
	loading	the comic book as well as having the primary action upon
	pressing select be to go to full view
  - Set zoom box width
	Set the width of the zoom box. The default is 150 pixels.
  - Set zoom box height
	Set the height of the zoom box. The default is 200 pixels.
  - Turn on/off precaching
	Toggles whether or not the program should load the following page in the
	archive before you actually go to that page. This function may still be
	somewhat buggy and leak-prone, so be careful. The default is off.
  - Save configuration
	Save the current configuration.
  - Load configuration
	Load the configuraion currently on the memory stick.
- About
	Display the about screen.
- Quit
	Close the program
- Reload menu
	Reload list of books (for if your comics folder changes)
- < Go back
	Close the menu or return to a higher menu

========================================
IV.	Compiling from source
========================================

The source code can be compiled if you have zlib, SDL and SDL_image installed
for the PSPSDK by going to the main folder of the source code, which should be
"src", and typing the following commands (excluding the $):

$ cd rar
$ make -f Makefile.psp
$ cp libpspunrar.a ..
$ cd ../tinyxml
$ make -f Makefile.psp
$ cp libtinyxml.a ..
$ cd ..
$ make -f Makefile.psp
$ cp *.png pspcomic

Inside of the Makefile, two defines can be set, although neither one should be.
The defines are -DUSE_GFX and -DEXPERIMENTAL. -DUSE_GFX enables SDL_gfx support,
which is buggy and does not work on the PSP. -DEXPERIMENTAL enables direct pspgu
rendering which is not complete, slow and buggy. Both of these are disabled by
default and are only left in in the case that the support may be improved in the
future.

The source code may be compiled for Windows (and quite probably some POSIX
systems) using the Makefile.windows makefiles for Windows. The Makefile in the
main directory is for compiling the main program and the minizip library
segments, and the Makefile in the rar directory is for compiling UnRAR as a
library. This library must be then placed in the main directory for
Makefile.window to detect it. The main Makefile should be processed by MinGW
using mingw32-make or MSYS, and the UnRAR Makefile must be processed by MSYS.
Processing these files with Cygwin may work, but is untested. The non-PSP
version of the program is only for testing the software, and is not fully
functional. The menus do no display on the screen, and are instead outputted to
the file stdout.txt. You also need to obtain the DLLs (or SOs if you are on a
*nix system) and place them in the main folder. Alternatively, if the DLLs or
SOs are installed in global locations, the program can also be run; however,
this is not recommended, so as to avoid DLL Hell.

In versions prior to v0.9.8 Beta, Unix compatibility was broken such that the
directory it would look for comics in would be ./C:/comics/. It now looks in
~/comics/.

In version v0.9.8 Beta, the Windows build is unstable and slightly buggy, and
the Unix and other operating system builds are still untested. The PSP build
should be stable, however.

========================================
III.	Notes
========================================

- Archaemic's PSP Development blog, Arc/PSP can be found at
  http://archaemic.awardspace.com/psp/. This blog will always be updated with
  news and information about upcoming versions of PSPComic as well as a download
  link for the latest version.
- Please send all bug reports to the email address archaemic.spam at gmail.com.
  If this program crashes with a blue screen, please send the contents of the
  bottom line of the error message (i.e. psp-addr2line etc.), including the one
  letter below the last line, to the email address mentioned above.
- The zoom box does not currently work on images that are smaller than the
  dimensions of the zoom box. This will be fixed in a later version.
- The background is customizable. Simply replace the file background.png in the
  game's folder with another image (preferably 480x272, although it doesn't need
  to be), and it will be loaded as the background for the menu.
- Large pages, when made full size, may cause the PSP to run out of memory if
  attempting to rotate, or sometimes if just loaded. Make sure not to use very
  high resolution comic books with this program. If memory runs out, the page
  will "freeze", meaning it will no longer be able to be operated on, but you
  can still change pages in the comic book.
- If your file or folder is not shown in the file list, that means that the file
  is either of the wrong type, of that the filename is too long (over 250 bytes,
  including the name of the folder).
- DO NOT ATTEMPT PUT THE PSP INTO STANDBY MODE WHILE A PAGE IS LOADING! THIS MAY
  CAUSE THE PSP TO CRASH.
- This program is statically linked to SDL_image, which in turn is statically
  linked to Independant JPEG Group's (IJG) implementation for reading JPEGs.
- This program is statically linked to zlib and minizip.
- The version of UnRAR distributed with this source code is slightly modified so
  as to work with the PSP. It is not the original source code, although it may
  be able to be compiled in an identical manner to the original source code and
  would likely be able to be used in the stead of the original source code.
- This program, when run, will create two files, stdout.txt and stderr.txt.
  These files are not used by the program, and are created by SDL, with which
  this program is statically linked. These files may be removed at any time, but
  removal of these files is not recommended, as they will be recreated when the
  program is run next.

========================================
IV.	Frequently Asked Questions
========================================

Q. When I try to load up some pages in a comic book, I get a notice saying
   "SDL_image: JPEG loading error". What does this mean and can I fix it?
A. This usually means that the PSP ran out of memory when trying to load the
   JPEG in the comic book archive. This cannot be fixed. Try using a lower
   resolution version of the same comic book.

========================================
V.	History
========================================

v0.9 Beta (2007-04-16)
- Initial release

v0.9.5 Beta (2007-04-27)
- [Feature] Subdirectory support added
- [Feature] Added optional zoom level or rotation persistence between pages
- [Feature] Adjustable pan rate
- [Feature] Select button now switches between fit to width and full size
- [Feature] Ability to save/load configuration
- [Bugfix] Resample algorithms now work as selected, and no more garbling for 8-
  bit images
- [Bugfix] Next/previous comic book menu option now works even if comics on the
  memory stick are changed while menu is open
- [Bugfix] Fixed crash bug when resizing a full-sized page to fit to width
- And many more minor changes...

v0.9.6 Beta (2007-04-29)
- [Feature] L and R now scroll more than one item at a time in the menu
- [Bugfix] Crash when comics folder is absent has been fixed
- [Bugfix] When going to a higher menu from a menu that has been scrolled
  through, the menu should now appear correctly
- And some other minor changes...

v0.9.7 Beta (2007-05-05)
- [Feature] Configuration file is now XML
- [Feature] New manga mode, which makes comics start from the right instead of
  from the left
- [Feature] Menu now shows current state of togglable items
- [Feature] New battery meter shows remaining battery percentage in the menu. If
  the text is red, the battery is low. If it is yellow, the power is plugged in.
- [Feature] The clock frequency menu now allows any value between 20 MHz and 333
  MHz to be selected
- [Feature] Bookmarks have been added. For more information, please see the menu
  options section
- [Feature] 8-bit images now support resampling
- [Bugfix] Fixed scrolling bug, which made the program stop scrolling after
  some time with the D-Pad
- [Bugfix] Removing an open RAR or CBR file while the program is using that file
  will no longer cause a crash when the page is changed
- Sped up resampling
- And many more minor changes...

v0.9.7 Beta 2 (2007-05-05)
- [Bugfix] Fixed a bug where all bookmarks got deleted while adding a new
  bookmark

v0.9.8 Beta (2007-06-28)
- [Feature] Menu now shows name and current page of opened comic book
- [Feature] When zooming, the image is centered on the same place, instead of
  resetting to one of the corners
- [Feature] Added full view mode
- [Feature] Added option to load bookmark upon loading comic book
- [Feature] Alpha-transparent PNGs now display properly
- [Feature] The comics folder is now created if it is not initially present
- [Feature] Jump to page menu now shows the names of the pages
- [Feature] Really glitchy precaching. Use at your own risk! It must be enabled
  manually by editing the config.xml file
- [Feature] Zoom box. Hold Triangle to activate a box that shows a zoomed in
  region of the page. Very slow currently
- [Feature] Holding a button for several seconds now cancels the action before
  it is taken
- [Feature] Battery meter now refreshes every couple dozen seconds instead of
  just when a different option is selected
- [Bugfix] Fixed several bugs relating to zooming
- Sped up resampling
- The menu no longer shows the open comic book in the background. This is to
  save memory.
- Scrolling menus no longer flicker
- Some other stuff I forgot
- And many more minor changes...

v0.9.8 Beta 2 (2007-06-30)
- [Feature] Precaching works better and was thus added to the menu
- [Bugfix] The menu no longer lingers in the background after closing the menu
  for a small image
- [Bugfix] Loading bookmark upon loading the comic book now actually works
- [Bugfix] Huge memory leak in precaching patched

========================================
VI.	Legal
========================================

This program is copyrighted (C) by Jeffrey P. and Christophe Rudyj. Portions of
this program are licensed under the terms of the GNU General Public License
(GPL), and other portions under the terms of both the UnRAR license and the GPL,
as specified later in this section. The source code distribution of this program
includes three libraries, a portion of the minizip library, which is licensed
under the terms of the zlib license, a modified version of the UnRAR
library, which is licensed under the terms of the UnRAR license, and the TinyXML
library with modified Makefiles, which is also licensed under the zlib license.
For the GPL, please read the file license.txt. For the UnRAR license, please
read the file src/rar/license.txt. For the zlib license, please refer to
http://www.zlib.net/zlib_license.html.

The files in the main folder and the src folder are licensed under the GPL
exclusively, including the images, which are counted as source code, and
excluding the file rar.hpp and the file rar.cpp. The files in the src/rar folder
and the files rar.cpp and rar.hpp in the main folder are licensed under the
UnRAR license exclusively. The files in the src/zip folder are a portion of the
minizip library by Gilles Vollant and are licensed under the zlib license
exclusively. The files in the src/tinyxml folder are the TinyXML library, with
modified Makefiles, which are licensed under the zlib license. In addition, as a
special exception, Jeffrey P. gives permission to link the code of this program
with the UnRAR, minizip and TinyXML libraries and the files rar.cpp and rar.hpp
(or with modified versions of UnRAR, minizip, TinyXML, rar.cpp and rar.hpp that
use the same license as UnRAR, minizip, TinyXML rar.cpp and rar.hpp,
respectively), and distribute linked combinations including the five. You must
obey the GNU General Public License in all respects for all of the code used
other than UnRAR, minizip, TinyXML, rar.cpp and rar.hpp. If you modify the
program, you may extend this exception to your version of the file, but you are
not obligated to do so. If you do not wish to do so, delete this exception
statement from your version.

This means that the user is free to redistribute and/or modify the program
under the terms of the GPL, so long as the user freely provides any
modifications to the source code and uses this same license upon redistribution
and does not use the source code to create an implementation of the RAR
compression algorithm.

THIS PROGRAM, AS IT IS FREE SOFTWARE, IS NOT COVERED BY A WARRANTY TO THE EXTENT
PERMITTED BY LAW. IT IS PROVIDED IN AN 'AS-IS' CONDITION, AND THE PSPCOMIC
PROJECT IS NOT RESPONSIBLE FOR ANY DAMAGES OR DATA LOSS THAT MAY OCCUR, HOWEVER
UNLIKELY IT IS FOR ANY DAMAGES OR DATA LOSS TO OCCUR.

========================================
VII.	Credits
========================================

All of the programming and the PSPComic icons were done by Jeffrey P. Main
background, ideas and encouragement were graciously provided by Christophe
Rudyj. Testing was done by Jeffrey P., Christophe Rudyj and "Chirishman". Some
help was obtained from the Comical project (http://comical.sourceforge.net/) in
the writing of the RAR reading code. Comical is a good free software comic book
reader for Windows, Mac or Linux (and possibly other POSIX operating systems) if
you are looking for a program with which to view comic books on the computer.
The font used in the graphics is Komica, which can be found at
http://www.dafont.com/komika-poster.font