path: root/system/pucrunch/pucrunch.1

.\" Man page generated from reStructuredText.
.
.TH PUCRUNCH 1 "2017-09-06" "20081122" "SlackBuilds.org"
.SH NAME
pucrunch \- compressor optimized for low-resource decompression
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" RST source for pucrunch(1) man page. Convert with:
.
.\" rst2man.py pucrunch.rst > pucrunch.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.\" converting from pod:
.
.\" s/B<\([^>]*\)>/**\1**/g
.
.\" s/I<\([^>]*\)>/*\1*/g
.
.SH SYNOPSIS
.sp
pucrunch [\fI\-options\fP] [\fIinfile]\fP [\fIoutfile\fP]]
.SH DESCRIPTION
.sp
Pucrunch is a Hybrid LZ77 and RLE compressor, uses an Elias Gamma Code
for lengths, mixture of Gamma Code and linear for LZ77 offset, and
ranked RLE bytes indexed by the same Gamma Code. Uses no extra memory
in decompression.
.sp
Input files can be arbitrary data (with \fI\-d\fP option) or executables for
Commodore 64, VIC\-20, C16, or Plus/4. Output is either a self\-extracting
compressed Commodore executable, or a compressed data file suitable for
extracting via \fIpucrunch \-u\fP or the included decompressor routines. See
/usr/doc/pucrunch\-20081122/examples/*.asm for 6502, 6809, and Z80
assembly code implementations of the decompressor.
.sp
Note: Because pucrunch contains both RLE and LZ77 and they are
specifically designed to work together, DO NOT RLE\-pack your files
first, because it will decrease the overall compression ratio.
.SH OPTIONS
.sp
Pucrunch expects any number of options and up to two filenames. If you
only give one filename, the compressed file is written to the stardard
output. If you leave out both filenames, the input is in addition
read from the standard input. Options needing no value can be grouped
together. All values can be given in decimal (no prefix), octal (prefix
0), or hexadecimal (prefix $ or 0x). [\fINote\fP: escape the \fI$\fP with quotes
or a backslash, to avoid your shell treating it as a metacharacter]
.sp
Example: pucrunch demo.prg demo.pck \-m6 \-fs \-p2 \-x0xc010
.INDENT 0.0
.TP
.B \fB\-c<machine>\fP
Selects the machine. Possible values are 128 (C128), 64 (C64),
20 (VIC20), 16 (C16/Plus4), 0 (standalone). The default is 64, i.e.
Commodore 64.
.sp
If you use \-c0, a file without the embedded decompression code
is produced. This can be decompressed with a standalone routine
and of course with pucrunch itself. Options marked with [\fISFX\fP]
have no effect if \-c0 is used.
.sp
The 128\-mode is not fully developed yet. Currently it overwrites
memory locations $f7\-$f9 (Text mode lockout, Scrolling, and Bell
settings) without restoring them later.
.TP
.B \fB\-a\fP
[\fISFX\fP] Avoids video matrix if possible. Only affects VIC20 mode.
.TP
.B \fB\-d\fP
[\fISFX\fP] Indicates that the file does not have a load address. A load
address can be specified with \-l option. The default load
address if none is specified is 0x258.
.TP
.B \fB\-l<addr>\fP
[\fISFX\fP] Overrides the file load address or sets it for data files.
.TP
.B \fB\-x<addr>\fP
[\fISFX\fP] Sets the execution address or overrides automatically detected
execution address. Pucrunch checks whether a SYS\-line is present
and tries to decode the address. Plain decimal addresses and
addresses in parenthesis are read correctly, otherwise you need
to override any incorrect value with this option.
.TP
.B \fB\-e<val>\fP
Fixes the number of escape bits used. You don\(aqt usually need or
want to use this option.
.TP
.B \fB\-r<val>\fP
Sets the LZ77 search range. By specifying 0 you get only RLE.
You don\(aqt usually need or want to use this option.
.TP
.B \fB+f\fP
Disables 2MHz mode for C128 and 2X mode in C16/+4.
.TP
.B \fB\-fbasic\fP
[\fISFX\fP] Selects the decompressor for basic programs. This version
performs the RUN function and enters the basic interpreter
automatically. Currently only C64 and VIC20 are supported.
.TP
.B \fB\-ffast\fP
[\fISFX\fP] Selects the faster, but longer decompressor version, if such
version is available for the selected machine and selected
options. Without this option the medium\-speed and medium\-size
decompressor is used.
.TP
.B \fB\-fshort\fP
[\fISFX\fP] Selects the shorter, but slower decompressor version, if such
version is available for the selected machine and selected
options. Without this option the medium\-speed and medium\-size
decompressor is used.
.TP
.B \fB\-flist\fP
List all available decompressors (the \fI\-f\fP options above), for all
supported machines. The list may contain more decompressors than are
shown above (the extras might be experimental, use at your own risk).
.TP
.B \fB\-fdelta\fP
Allows delta matching. In this mode only the waveforms in the
data matter, any offset is allowed and added in the
decompression. Note that the decompressor becomes 22 bytes
longer if delta matching is used and the short decompressor
can\(aqt be used (24 bytes more). This means that delta matching
must get more than 46 bytes of total gain to get any net
savings. So, always compare the result size to a version
compressed without \-fdelta.
.sp
Also, the compression time increases because delta matching is
more complicated. The increase is not 256\-fold though, somewhere
around 6\-7 times is more typical. So, use this option with care
and do not be surprised if it doesn\(aqt help on your files.
.TP
.B \fB\-n\fP
Disables RLE and LZ77 length optimization. You don\(aqt usually
need or want to use this option.
.TP
.B \fB\-s\fP
Display full statistics instead of a compression summary.
.TP
.B \fB\-p<bits>\fP
Fixes the number of extra LZ77 position bits used for the low
part. If pucrunch tells you to to use this option, see if the
new setting gives better compression.
.TP
.B \fB\-m<bits>\fP
Sets the maximum length value. The value should be 5, 6, or 7.
The lengths are 64, 128 and 256, respectively. If pucrunch tells
you to to use this option, see if the new setting gives better
compression. The default value is 7.
.TP
.B \fB\-i<0|1>\fP
Defines the interrupt enable state to be used after
decompression. Value 0 disables interrupts, other values enable
interrupts. The default is to enable interrupts after
decompression.
.TP
.B \fB\-g<byte>\fP
Defines the memory configuration to be used after decompression.
Only used for C64 mode (\-c64). The default value is $37.
.TP
.B \fB\-u\fP
Unpacks/decompresses a file instead of compressing it. The file
to decompress must have a decompression header compatible with
one of the decompression headers in the current version.
.TP
.B \fB\-h\fP
Print built\-in help and exit.
.UNINDENT
.SH COPYRIGHT
.sp
As of 21.12.2005 Pucrunch is under GNU LGPL. See:
.INDENT 0.0
.INDENT 3.5
\fI\%http://creativecommons.org/licenses/LGPL/2.1/\fP
\fI\%http://www.gnu.org/copyleft/lesser.html\fP
.UNINDENT
.UNINDENT
.SH AUTHORS
.sp
pucrunch was written by Pasi Ojala <\fI\%a1bert@iki.fi\fP>.
.sp
This man page consist of excerpts from the author\(aqs documentation. It
was written for the SlackBuilds.org project by B. Watson, and is licensed
under the same terms as the original docs.
.SH SEE ALSO
.sp
exomizer(1)
.sp
The pucrunch homepage: \fI\%http://a1bert.kapsi.fi/Dev/pucrunch/\fP
.sp
The full documentation and sample decompressor code:
.INDENT 0.0
.INDENT 3.5
/usr/doc/pucrunch\-20081122/
.UNINDENT
.UNINDENT
.\" Generated by docutils manpage writer.
.