Fixed typo

[TortoiseGit.git] / doc / images / DeflOpt.txt

DeflOpt 2.07 of 05-Sep-2007\r
Copyright (C) 2003-2007 by Ben Jos Walbeehm\r
\r
\r
Some additional information regarding DeflOpt. I chose to put this in a text\r
file, because I did not want to make the built-in help multiple pages long.\r
\r
First of all, for those who wish to contact me through e-mail: I get well over\r
100 spam e-mails every day and because of that my own SpamKill program uses\r
VERY aggressive settings. To circumvent that, make sure to put "DeflOpt" in\r
the subject line when sending me an e-mail. The address is:\r
walbeehm AT walbeehm DOT com.\r
\r
\r
(From the built-in help)\r
\r
***                 DeflOpt V2.07                 ***\r
***       Built on Wed Sep  5 18:56:30 2007       ***\r
***  Copyright (C) 2003-2007 by Ben Jos Walbeehm  ***\r
\r
\r
Description:\r
  DeflOpt tries to reduce the size of GZIP (extensions .gz and .tgz), PNG, and\r
  ZIP files. Regardless of which programs/settings were used to create them,\r
  DeflOpt will usually be able to reduce these files by at least a few bytes.\r
\r
Parameters:\r
  [options] <filespec> [<filespec> [<filespec> ...]]\r
\r
Available options:\r
  /a: Scans all files that match the specifications to determine whether they\r
      are in a supported format (GZIP, PNG, ZIP), regardless of extensions.\r
  /b: Replaces files also when no bytes, but more than zero bits were saved.\r
  /d: Preserves the date and time of files it rewrites.\r
  /c: Comments in GZIP and ZIP files are kept. By default, these are removed.\r
  /f: Forces every file to be rewritten, even when no bits/bytes were saved.\r
  /k: Keeps all chunks/structures within files, even the mostly useless ones.\r
  /r: Recursively go through all subdirectories.\r
  /s: Silent mode. Nothing is displayed except in case of errors.\r
  /v: Verbose output.\r
\r
Notes (for more detailed information, see DeflOpt.txt):\r
- Options may be specified using both slashes ("/") and dashes ("-").\r
- Wildcards * and ? are allowed, including in directory names.\r
- For directories, all GZIP, PNG, and ZIP files in those directories are\r
  processed.\r
- If <filespec> has no extension, .gz, .tgz, .png, and .zip are used, unless\r
  the /a option is specified -- in that case, DeflOpt will scan every file to\r
  determine the format and process every file accordingly.\r
- DeflOpt will NOT process GZIP, PNG, and ZIP files WITHIN (G)ZIP files.\r
- By default, DeflOpt rewrites a file only when it can reduce the number of\r
  bytes of that file. It is possible that DeflOpt makes the deflated data\r
  one or more bits shorter but that this does not make the size in bytes less.\r
  Use the /b option to have DeflOpt rewrite files also when it can only\r
  save one or more bits but no actual bytes.\r
\r
Examples:\r
  DeflOpt /r *.zip abc*.png\r
  DeflOpt -K "C:\Documents and Settings\Ben Jos\My Documents\My Pictures"\r
  DeflOpt ..\..\stuff -b/c/k /FrS\r
  DeflOpt /adr C:\Prog* /f\r
\r
(End of From the built-in help)\r
\r
\r
As its name implies (DeflOpt -- Deflate Optimisation), DeflOpt will not try to\r
optimise files that use a type of compression different from LZ77 ("Deflate").\r
It will also not process files compressed with the "Deflate64" type. Unlike\r
the 1.XX versions of DeflOpt, versions 2.XX and above will not exit with an\r
error message, but simply copy the compressed data of the types it does not\r
"understand".\r
\r
\r
As the examples show, options are case-insensitive and do not have to be\r
separated by spaces, nor does the slash ("/") or dash ("-") even have to be\r
repeated. For instance: "/b /c /f", "/b/c/f", and "/bcf" all mean the same.\r
\r
\r
Regarding /a: By default, DeflOpt will only process files that have one of\r
the extensions .gz, .png, .tgz, and .zip, and will assume that those files\r
are valid. So if a ZIP file has the extension .png, DeflOpt will most likely\r
fail with an error message. However, if /a is specified, then DeflOpt will\r
scan all files that match the specifications to see if they are in any of\r
the supported formats (GZIP, PNG, ZIP). This of course makes DeflOpt slower,\r
but also smarter. Since there are many other extensions that are really just\r
GZIP, PNG, or ZIP files, using /a will process those files too. In addition,\r
if a file has the wrong extension (for instance a ZIP file that has the\r
extension .png), then DeflOpt will still treat it correctly.\r
\r
\r
Regarding /b: Bit gain vs. byte gain: In a zip file, technically it is\r
possible to gain one bit per file for 8 files and save a total of 8 BYTEs.\r
At the same time, it is possible to save 7 bits per file for 8 files, but not\r
save a single byte.\r
\r
\r
Regarding /f: The resulting file will never be larger than the input file.\r
However, the resulting file may be slightly different, because DeflOpt always\r
does certain things to make sure that certain fields do not have invalid\r
values (CRCs, for instance).\r
\r
\r
Regarding /k: Several structures within files are optional. By default,\r
DeflOpt does not keep structures that are optional or mostly useless.\r
What is optional or mostly useless depends on the file type:\r
- For GZIP files: By default, only the original filename (if any) is kept\r
  (yes, I know it is optional, but it is "important enough to be kept"). The\r
  extra-text, comment, and 16-bit-CRC fields are only kept if /k is specified.\r
  Note that the comment is also kept if /c is specified.\r
- For PNG files: By default, only IDAT, IEND, IHDR, PLTE, and tRNS chunks are\r
  kept. Specify /k to keep all other chunk types as well. If /k is specified,\r
  then DeflOpt will try to improve deflated data in iCCP, iTXt, and zTXt\r
  chunks as well. Note that when a PNG file contains multiple IDAT chunks,\r
  these will always be combined into one because there is absolutely no need\r
  to divide the compressed data over multiple IDAT chunks.\r
- For ZIP files: By default, no optional fields are kept, so unless /k is\r
  specified, the optional fields zip-comment, file-comment, digital-signature,\r
  central-extra-field, and local-extra-field are not kept. Note that both\r
  types of comment fields will still be kept if /c is specified. Note that\r
  stored directory names within ZIP files as well as "Data Descriptors" will\r
  ALWAYS be removed, REGARDLESS of whether /k is specified or not. Both are\r
  ALWAYS redundant: The first because those directory names are also part of\r
  the filenames and every unzip program these days will create the necessary\r
  directories. The second because DeflOpt will store the necessary information\r
  directly in the local and central directory entries inside the ZIP file.\r
  "Data Descriptors" are only useful when the actual uncompressed size,\r
  compressed size, and 32-bit CRC are not yet known while compressing data;\r
  in other words, while piping/streaming data.\r
\r
\r
Regarding /s and /v: These two options are mutually exclusive. If both are\r
specified, then the one specified last will count.\r
\r
\r
Regarding wildcards:\r
Wildcards * and ? are allowed in directory names as well. However, unless /r\r
("recursive") is specified, wildcards will not match subdirectories of the\r
directory that has the wildcards. So the file C:\TEMP\EXAMPLE\test.zip will\r
only be processed by "C:\TEM*\*.zip" in case /r is specified. If /r is not\r
specified, then it will only look for anything matching *.zip in the C:\TEMP\r
directory and (if any) other directories that have a name starting with\r
"C:\TEM", but not subdirectories of those directories. Because of the very\r
powerful wildcards, DeflOpt will ONLY look at files that have one of the\r
extensions .gz, .png, .tgz, and .zip, UNLESS /a is specified. So if there is\r
a file called "c:\temp.txt", running "DeflOpt c:\temp.txt" will NOT process\r
that file. Note, however, that if there were a "c:\temp.txt" DIRECTORY, then\r
DeflOpt would look at all .gz, .png, .tgz and .zip files in that directory.\r
If all the .gz and .tgz files in the current directory should be processed,\r
but not the .png and .zip files, then use something like "DeflOpt *.gz *.tgz".\r
\r
Since wildcards can be used for both directories and files, this means that\r
the "*" in "DeflOpt C:\TEST\*" will match both files and directories. Some\r
examples of this:\r
\r
"DeflOpt C:\TEST\*"\r
  This will process all the files in the C:\TEST directory as well as all the\r
  files in any of its subdirectories (but not THEIR subdirectories unless /r\r
  is specified). So the file C:\TEST\EXAMPLE\test.zip would be processed.\r
\r
"DeflOpt C:\TEST" (or "DeflOpt C:\TEST\.")\r
  This will process only the files in the C:\TEST directory.\r
\r
"DeflOpt C:\TEST\*\"\r
  This will process only the files in any of the subdirectories of the C:\TEST\r
  directory (but not THEIR subdirectories unless /r is specified).\r
\r
"DeflOpt *"\r
  This will process all the files in the current directory as well as all the\r
  files in any of its subdirectories (but not THEIR subdirectories unless /r\r
  is specified).\r
\r
"DeflOpt ." (or "DeflOpt .\")\r
  This will process only the files in the current directory.\r
\r
"DeflOpt *\"\r
  This will process only the files in any of the subdirectories of the current\r
  directory (but not THEIR subdirectories unless /r is specified).\r
\r
By default, DeflOpt will only look at the extension to decide what kind of file\r
it is dealing with, so if, for example, a GZIP file has the extension .zip, then\r
DeflOpt will mostly likely exit with an error message. However, in case /a is\r
specified, then DeflOpt will scan every file matching the specifications to see\r
if they are in a supported format and process the ones that are.\r
\r
\r
Short history:\r
\r
The first version of DeflOpt (V1.00) dates back to 04-Apr-2003. In short\r
succession, many more versions followed until V1.16, which was created on\r
22-Apr-2003. V1.16 was the first public version, although it was not publicly\r
released until 27-Jun-2003. \r
\r
After that, development slowed down: V1.17 was created on 07-Sep-2003, V1.18\r
on 15-Dec-2003, and V1.19 on 23-Feb-2004. I stopped development on DeflOpt\r
very soon after having created V1.19, and that was part of the reason that\r
V1.19 was not actually released publicly until more than 2 years afterwards.\r
\r
V2.00 of 10-Jul-2006:\r
- Added GZIP (.gz and .tgz) and PNG support, in addition to ZIP support.\r
- Even better optimisation. V2.00 gets a few more extra bytes out of a\r
  deflated file than V1.19 did, both because of better optimisation and\r
  because of additional removals of optional/useless structures.\r
- No more exiting with an error message on unsupported ZIP compression methods\r
  (like Implode, Shrink, Reduce, Deflate64, etc.). Unsupported methods are\r
  simply copied without any attempt at optimisation.\r
- More flexible wildcard matching, allowing wildcards to not just be part of\r
  the actual filenames, but also of directory names.\r
- More options/switches.\r
- By default, all "optional" and "mostly useless" structures/chunks are thrown\r
  away now, but /k can be specified to keep everything.\r
- Stored directory names within ZIP files as well as "Data Descriptors" are\r
  always removed.\r
- The /n option ("do not actually write any files") is gone.\r
\r
V2.01 of 15-Jul-2006:\r
- Fixed the occasional "Compressed size is larger than it was!?!?!?" error.\r
- Fixed a problem with stored blocks.\r
- Added the /s option ("silent mode").\r
\r
V2.02 of 17-Jul-2006:\r
- Significantly faster (2-6 times or more, depending on the input).\r
\r
V2.03 of 16-Nov-2006:\r
- Fixed a very rare Access Violation.\r
- Fixed a problem with zip files containing data descriptors.\r
\r
V2.04 of 20-Nov-2006:\r
- Safer handling of zip files containing data descriptors.\r
- Fixed a problem with zero-length files that have a compression method\r
  differing from "stored".\r
\r
V2.05 of 10-Mar-2007:\r
- Fixed a problem of temporary files not always being deleted.\r
\r
V2.06 of 28-Apr-2007:\r
- In very rare cases, DeflOpt would stop parsing compressed data before\r
  encountering the "End Of Block" marker. Fixed.\r
\r
V2.07 of 05-Sep-2007:\r
- Added the /a option ("scan all files").\r
- Added the /d option ("preserve date and time").\r