------------------------
 README (MozCache 1.1.1
------------------------

Welcome to Mozcache, a viewer and manager for cache files stored
by Mozilla, Netscape, Firefox, SeaMonkey, and with Cygwin also the
MS Internet Explorer.
This program is distributed under GNU-GPL 2 or later.

You can read informations about configuring, compiling  and installing
this package in the file 'INSTALL', about some informations about running
it right here.

Note: Mozilla means also Firefox, SeaMonkey and
      Netscape 6.1 (or higher version) browsers.


0. Important
------------

If your browser is running while launching MozCache, it is possible
that the database cannot be readed. Then you should close your browser
and try open the database again.
This mainly occurs with Mozilla browsers. If opening the database of
one of this browser type, and if it is used, a warning message will
inform you about this.


1. Introduction
---------------

Stefan Ondrejicka tested NScache with 4.0, 4.5, 4.7 Linux x86 versions
of Netscape Communicator (version 4 and 5 of cache index database format),
and also on DEC OSF 4.0F Alpha with Netscape Communicator 4.0.
He also tested Mozilla support with Mozilla M16.

I have tested MozCache with 4.7 Linux PPC and Macintosh versions of
Netscape Communicator (version 5 of cache index database format), and
1.7 Linux PPC and 1.73 Windows 98 versions of Mozilla, also Netscape 7.2
Windows 98 version (version 1.5 of cache index database format).
MozCache 1.0 is able to read the database version 1.6, tested with
Firefox 1.5.01 and SeaMonkey 1.0 (both Windows 98 versions).
The MS Internet Explorer was tested with Cygwin 1.5.15 and Windows 98/XP.
Then I have tested the older Netscape versions 4.8 and 6.01, 6.1, 6.2.3
(all of them Windows 98).
MozCache 1.0.3 is able to read the database version 1.8, tested with
Firefox 2.0 to 2.0.0.13, and SeaMonkey 1.1 to 1.1.9 (all Windows XP versions).
MozCache 1.1.1 is able to read the database version 1.11, tested with
Firefox 3.0.1 (Windows XP version).

Previous versions of MozCache were distributed under the name 'NScache',
which was written by Stefan Ondrejicka <ondrej@idata.sk>, you can take
a look at the following pages:

http://www.idata.sk/~ondrej/nscache/
http://nscache.sourceforge.net/

There seems no further development on this project, so I released updated
versions named 'MozCache'.


2. Launching
------------

You can start MozCache with some command line options:

 -v --version
   Display the program version and exit

 -h --help
   Display a help message and exit. Here you can see the browser
   types supported by your program.

 -f --db-file=FILE
   Load the cache index from this file. This is usually
   '~/.netscape/cache/index.db' ('fat.db', 'cache.db') or
   '~/.mozilla/user-name/somewhat-else/Cache/_CACHE_MAP_'.
   You can also write '~/.netscape/cache/'. In this case
   MozCache tries to find the database by itself.
   If you do not know the location for it, open the preference
   dialog of your browser, and look into 'Advanced->Cache'.

 -t --db-type
   Select the type of the database. Type help for the possible values.
   If you want to open the database for the MS Internet Explorer,
   type '-t ie', there is no need to specify a file. 

 -d --temp-dir=DIR
   If launching an application to view the content of a cache file,
   this will be first written to disk, by default into the '/tmp'
   directory, or the destination your TMPDIR environment variable
   points to.
   If you want another place, you can do e.g. '--temp-dir=/dev/shm'
   or '-d ~'. You must own write permission for this directory.
   Without permission the default directory will be used.

 -s --summary
   Write the number of entries and the total size to 'stdout' and exit.

 -c --content-types
   Write info about cache content types to 'stdout' and exit.

 -l --list
   Write a list (cache file name and URL) of each cache entry to
   'stdout' and exit.

 -m --multi-line
   Write a detailed list of each cache entry to 'stdout' and exit.

 -S --sort=[url|file|size|access|mime]
   Selects the type of sorting the list. Default is 'url'.
   Only usefull with '--list' or '--multi-line'

 -R --sort-reverse
   Sorts the list in reverse order.
   Only usefull only with '--list' or '--multi-line'

 -r --readonly
   Hides the menu entry for delete, so you cannot delete a cache file.
   To enable readwrite, you have to quit and start again (without -r).


3. Main Window
--------------

When starting MozCache without options writing to stdout, after a
short time the main window appears on the screen. On the top you can
see the menu bar, followed by a text field for the index file location,
an option menu for the browser type and a button for opening a cache
index file. The only way to open the database for the Internet Explorer
(besides the command line option '-t ie') is the option menu for the
browser type: simply select MSIE.

Opening a database using the text field is very easy, since it has
a shell-like filename completition. Typing '~/.moz [TAB]', this will
be expanded to '~/.mozilla/'. If there are several files starting
with this pattern, a popup window shows you all matching filenames.
Else you will read a message like 'match', 'no match found', or an
error like 'no permission' ...
When typing the filename is done, hit the Return key or select the
browser type from the option menu.

Below you can select between the tree or the sorted view.
In the tree view the cache files will be displayed in folders. You
can perform many actions on a single file, a domain folder or a
subfolder of the domain. First you have to select it, then choose the
type of action from the menu.

In the sorted view they will be displayed sorted by the type you can
select. It is possible sorting the files by URL, the size, the access
time and the MIME type. If you select the same type a second time, the
files will be sorted in reverse order, e.g. first the smallest file will
shown on top, the second time it will be the biggest one.

If MozCache was compiled with swapable columns, you can
  > reorder the columns by
     * GTK+-1.2: clicking on an arrow in the title bar
     * GTK+-2.x: clicking the right mouse button while over the title bar.
  > collapse or expand the selected folder by
     * GTK+-1.2: clicking on the minus or plus sign in the URL column
     * GTK+-2.x: clicking the right mouse button while over the URL column.
  > collapse or expand any folder by
     * both:     clicking the middle mouse button while over the desired folder
                 You can also use the left button while pressing the Shift key.


4. Menues
---------

Many of the menu items are also in a popup menu available. If you click
the right mouse button while over a list (or pressing Shift-F10), it will
be displayed (works in search dialogs, too).
Some items are only enabled if a file is selected.

4.1 File / Open cache index file ...
-----------------------------------
A fileselector dialog appears. Type a dot followed by TAB displays the
hidden files. Note: it is not possible to open an index file for the
MS Internet Explorer.

4.2 File / Properties ...
-------------------------
Some informations about the cache index file itself, where the file
entries are updated, and the content entries are the values when
opening the database (if you haven't deleted anything).
The time of modification is the time the browser has written cache
stuff to disk (not with MSIE), the access time is the time you have
last opened this database.

4.3 File / Save rc file
-----------------------
Stores your settings to disk, so you will get them at next start again.
If you don't save changes you made, they are (maybe) lost.

4.4 File / Quit
---------------
Finishes the program. If you have the option to save the rc file on exit
enabled, this will be done now, else see above.

4.5. View / Entry informations ...
----------------------------------
Displays many information about the cache file, e.g. name, URL, size etc.

4.6 View / Columns
------------------
A submenu where you can enable or disable the columns you want to
see or not. However, at least one column is visible.

4.7. View / View file with
--------------------------
A submenu where you can choose and launch the program for viewing the
selected file.

4.8. View / View URL with
-------------------------
A submenu where you can choose and launch the program for visiting the
selected URL.

4.9 View / Find ...
-------------------
A dialog for searching in the cache files. You have some options like the
MIME-type, case sensitive, catch whole word, regular expression and the
source of the files (all, selected and results). If there are results in
the list, you can display the popup menu and perform the same actions as
in the tree and sorted list.
You can search in files without MIME-type with the '*' type.
The pattern you are searching for will be converted to the character set
each file is using. If none is given, it will treated as 'ISO-8859-1'.
Files from the Internet Explorer don't have any information about the
character set, so the above may wrong.
It is possible that a character cannot be converted, in this case the
file will be skipped. GTK+-1.2 will need 'libiconv' for this.
Searching for none ASCII characters ignoring the case (the option 'case
sensitive' is unchecked) may fail if the character set of a file is
different from that one MozCache was started with.
To be safe you may search with 'regular expression' enabled, each non
ASCII character should be replaced with a dot (e.g. my name: 'F.rster').
However, HTML offers another way using special characters: 'F&ouml;rster'
and 'F&#246;rster' will be shown correct in your browser, but won't be
found with the example above (try this: 'F&.*;rster').
If your search was successful, the results will be shown in a list,
containing the URL, the found line, the cache file, and the line number.
Each line containing the search pattern will be displayed using the
correct font, if it is available. Else, all none ASCII characters will be
replaced with a question mark.
NOTE: if you have compiled MozCache using GTK+-2.0, MozCache may be suddenly
terminated. A message written to the console may look like
   Pango-ERROR **: file /instsoft/libxml/pango-1.8.1/pango/break.c:
   line 780 (pango_default_break): assertion failed:
   (IN_BREAK_TABLE (break_type)) aborting...
In this case you should compile either Pango with debug disabled, or
MozCache with '--enable-pango-locale'. See also INSTALL.

4.10 Edit / Save to file ...
----------------------------
Shows you a fileselector, which type depends on whether you have selected
a file or a folder. You can choose to save the file(s) as Hard Link. In
this case you will get not a real copy of the file. Modifying it will also
modify the cache file. If you don't like this, uncheck the button.
Saving Mozilla cache block files or MS Internet Explorer files, this option
is disabled. And: with Cygwin you will get always a real copy.
Saving a folder lets you additional choose the count of desination folder(s).
If the option Single Folder is checked, all files will be stored in only
one folder. This might lead to errors, if some files have the same name.
If unchecked, you will get all the subfolders.
At next you can choose whether to convert the URLs to local. If you do so,
you can open this pages in your browser and view it with all images. You
can select between converting none, all URLs of this domain, or only the
URLs pointing to files inside the cache.
Note: Windows does not like the following seven characters for file names,
which are 1) ?   2) :   3) *  4) |   5) <   6) >   and 7) "
MozCache will convert each of them to '!'.
Also note: with Cygwin the dialog don't like filenames which are too long,
using GTK-1 it will crash. So the maximum length is set to NAME_MAX / 2,
which may be 127 characters.

4.11 Edit / Delete file ...
---------------------------
Removes a single file or a complete folder, but a dialog box will ask you
before. So you still have the chance to say no ...

4.12 Edit / Copy url to clipboard
---------------------------------
The URL of the selected file is copied into the clipboard. In e.g. an
editor you can insert it by clicking the middle mouse button.

4.13 Edit / Show entry informations
-----------------------------------
Display some informations in the status bar at the bottom.

4.14 Edit / read only permissions
---------------------------------
Makes the selected file or files inside a folder read only. MozCache
cannot delete them after, and your browser will not be able to modify
them. This works not with cache block files.

4.15 Edit / read/write permissions
----------------------------------
Makes the selected file or files inside a folder writable. MozCache
can delete them after, and your browser is able to modify them.
This works not with cache block files.

4.16 Options / Viewers setup ...
--------------------------------
In this dialog you can assign programs to the MIME type, e.g. 'less' to
HTML. The first program of a MIME type (most top) can be launched by a
double click with the left (file) or middle (URL) mouse button, else you
can use the menues described above. If your mouse don't have the middle
button, you can use the left while pressing the Shift key.
To get a line to the top, simply select and move it (keep the left mouse
button pressed).
You can open files without MIME-type by assigning a program to the '*' type.
If you assign a parameter which have a space in it, you can quote this
like <xterm -e bash -c 'gzip -cd %f | less'>,
or   <xterm -e bash -c 'gzip -cd \'%f\' | less'>
or   <xterm -e bash -c gzip\ -cd\ %f\ |\ less>.
If the file name or the URL is the last parameter, you don't need to
specify it: <xterm -e less %f> is the same like <xterm -e less>.
Here you will need it: <mozilla -remote openFile(%f)> or
<mozilla -remote openURL(%u)>.
You have to assign the MIME-type and at least one viewer, file or URL.
If you are ready filling in the parameters, click 'Append'. If you don't,
your work will be lost.
If you finished assigning, click OK. Don't forget to save the rc file ...

4.17 Options / Keyboard ...
---------------------------
Lets you assign shortcuts to the menu. Select a line and press the key you
like (don't forget the CNTRL key). You can type in a new value in the same
manner, and remove this with a BACKSPACE.
If you finished your work, click OK. Don't forget to save the rc file ...

4.18 Options / Convert filenames to lowercase
---------------------------------------------
If you want all filenames displayed in lowercase, check this and reload
your database.

4.19 Options / Readonly
-----------------------
After checking this the delete menu will be always disabled.

4.20 Options / Decode files
----------------------------
Encoded files will be decoded, when saving, viewing or searching in files.
A Hard Link for such files is not possible, if this option is enabled.
If MozCache was compiled with the 'zlib', the formats compress, deflate and
gzip were supported, Additional, with the 'bzlib', the format bz2 is supported.
If the 'zlib' was not compiled in, MozCache tries to launch the applications
'compress', 'gzip', and 'bzip2' directly, the deflate format cannot be decoded.

4.21 Window titles in UTF-8
---------------------------
After checking this the window titles will be displayed in UTF-8, else
in the character set used when launching MozCache.

4.22 Options / Save rc on exit
------------------------------
If you close a session, the rc file will be stored. If you don't like this,
because all the settings are done, and there is no reason to save them all
the time, you can uncheck this option. Now you have to save the rc file the
last time - described above - to make this setting permanent.


5. Translations
---------------

If there is not a translation in your language available, but you would like
to have it, just make it at your own.
Change into the 'po' directory and type 'cp mozcache.pot mylang.po'.
Open 'mylang.po' with an editor of your choice and fill the 'msgstr' lines
with your translation. Put in the header your name, character set and remove
the fuzzy line. Save this file and open the Makefile. Look for MOFILES, POFILES
and POXFILES. Insert 'mylang.mo', 'mylang.po' and 'mylang.pox'. Save your work
and type 'make'. If there are no errors, get back and type 'make install-strip'.

If you are changing messages in any source files, you can type 'make mozcache.pot',
and then 'make pox'. Now you have to modify all the pox files with the new
translations, then type 'make mv', followed by a 'make', which will update
all mo files.

----------------------------------------------------------------------------

I hope that you will like this program. Have a lot of fun ...
Harald

Harald Frster <harald_foerster@users.sourceforge.net>

/* EOF */
