SabreTools/README.1ST

************************************************
*     SabreTools - DAT management software     *
* https://github.com/mnadareski/wizzardDesktop *
************************************************

Table of Contents
-----------------
1.0		Introduction and History
2.0		Included Programs
	2.1		Headerer
	2.2		RombaSharp
	2.3		SabreTools
	2.4		SimpleSort
	2.5		TGZConvert
3.0		Contributors
4.0		Licensing

** Section 1.0 - Introduction and History

Hello and welcome to the latest release of SabreTools! We are happy that you
chose to use our software for your DAT management needs. But what exactly is
SabreTools? How did it get started? Why is it named so weirdly? Why should we
care? Well, the first two can be answered, though the last one is up to you.

SabreTools has its roots in an internal tool developed by RomShepherd member
The Wizard of DATz (WoD). The aim of the PHP-based program was to collate data
frommultiple sources and create new DAT files for custom sources as well as
DAT files that have duplicate data removed. WoD maintained this software and
used it to create near-monthly releases for quite a while.

Around the middle-end of 2015, WoD announced that they would be taking a break
from the process of creating and releasing new files. A couple of months went
by with no information. Finally, WoD finally told the community that they would
no longer be able to maintain either the project or the software involved,
releasing the source code of the internal project in the process. During that time,
RomShepherd member darksabre76 picked it up to see how the program even worked.

After updating the code to the newest version of PHP and trying to figure out
what each page did, he announced that it was going to be easier to do a complete
rewrite while maintaining functionality. He was given a lot of support and got
started with the aim to keep the code completely open source so that anyone can
help. It took a lot of work and help from fellow user emuLOAD, but the code
finally started to shape up in the form of WoD Redux. This project is still
active and can be found at https://github.com/mnadareski/wizzardRedux.

After about a month of work on this, and continued support from the community,
a relatively new user to the site, now known as @tractivo, sent him a message
and asked if a desktop port of some of the core features was possible. It was
difficult for most people to run the PHP code locally, so it made sense. With
the aim for people to use the web version primarlily, the desktop version,
originally called DATabase, was written. Pretty soon, this got even more support
and soon became the main focus. For a while, code parity between the C# and PHP
versions was attempted, but it became apparent that the desktop version was going
to be the better option.

Development accelerated, soon leaving the PHP version in the dust. Once the basics
were implemented, more features were requested, including better merging and DAT
management. Spurred on by an increasing number of community members, DATabase
accrued a lot of features and helper programs. The accuracy of the program also
increased, soon matching or surpassing existing options in functionality. At some
point during this development, some of the smaller tools got wrapped into DATabase,
slowly getting further from just a desktop port of WoD Redux.

With these changes, some external prodding, and a little bit of ego, darksabre76
decided to recristen the set of programs to SabreTools. This freed the program
from being just about DAT management and allowed it to be more of a Swiss Army
Knife of DAT tools. Development has been on and off since then, and is still
constantly evolving to this day (assuming that at this very moment development is
still active).

** Section 2.0 - Included Programs

Below are a list of the programs that are included in the current SabreTools
release. Each of them have a brief description of the tool along with in-depth
desciptions of all flags.

** Section 2.1 - Headerer

Headerer is a small program that is meant as an intermediary between header skipper
files (which, a bit apart from their name, do not just show how to skip copier headers)
and rom managers that do not use them.

The following systems have headers that this program can work with:
	- Atari 7800
	- Atari Lynx
	- Commodore PSID Music
	- NEC PC-Engine / TurboGrafx 16
	- Nintendo Famicom / Nintendo Entertainment System
	- Nintendo Famicom Disk System
	- Nintendo Super Famicom / Super Nintendo Entertainment System
	- Nintendo Super Famicom / Super Nintendo Entertainment System SPC Music

Usage:
	Headerer.exe [options] [filename|dirname]

Options:
	-e		Enable detect and remove mode
		This mode allows the user to detect, store, and remove copier headers from a file
		or folder of files. The headers are backed up and collated by the hash of the un-
		headered file. Files are then output without the detected copier header alongside
		the originals with the suffix .new. No input files are altered in the process.
		
	-r		Restore headers to file(s)
		This mode uses stored copier headers and reapplies them to files if they match the
		included hash. More than one header can be applied to a file, so they will be out-
		put to new files, suffixed with .newX, where X is a number. No input files are
		altered in the process.

** Section 2.2 - RombaSharp

THIS IS AN EXPERIMENTAL PROGRAM TO REPLACE ROMBA IN C#. THIS ISN'T WRITTEN YET.

** Section 2.3 - SabreTools

** Section 2.4 - SimpleSort

SimpleSort is a WIP program that is meant as a command-line tool to quickly rebuild and
verify files based on a supplied DAT file. The eventual aim for this program is to have
a full rom management tool without a GUI, though this may not happen for a while.

Usage:
	SimpleSort.exe [options] [filename|dirname] ...

Options:
	-?, -h, --help		Show the built-in help text
		Built-in to most of the programs is a basic help text
	
	-dat=				Name of the DAT to be used for the various options
		This DAT file is required for everything that SimpleSort currently does, so not
		supplying one will result in an error. Depending on the additional flags that are
		supplied, the DAT will be used differently, as described below. By default, the
		DAT is used to check which files need to be rebuilt.
		
	-out=				Set the name of the output directory
		This sets an output folder to be used by various parts of the program. As with the
		DAT file, this input is used differently based on the flags that are supplied. By
		default, the output folder is used as the target to rebuild files to.
		
	-t=, --temp=		Set the name of the temporary directory
		Optionally, a temp folder can be supplied in the case the default temp directory
		(inside the running folder) is not preferred. This is used for any operations that
		require an archive to be extracted.
		
	-qs, --quick		Enable quick scanning of archives
		For all archives, if this flag is enabled, it will only use the header information
		to get the archive entries' file information. The upside to this is that it is much
		quicker than extracting all files to the temp folder. On the downside, it can only
		get the CRC and size from most archive formats, leading to possible issues.
		
	-v, --verify		Enable verification of output directory
		This overrides the default rebuilding and only requires the DAT and the output folder.
		Here, the DAT is used to verify the output directory directly and then output a
		simple FixDAT. This can be misleading, currently, because it only checks for exact
		matches.
		
	-tgz				Enable Torrent GZ output
		Instead of outputting the files to ZIP archives, files will be rebuilt to TorrentGZ
		(TGZ) files. This format is based on the GZip archive format, but with custom header
		information and a file name replaced by the SHA-1 of the file inside. This is
		primarily used by external tool Romba (https://github.com/uwedeportivo/romba), but
		may be used more widely in the future.
		
		-r, --romba			Enable Romba depot directory output
			As an extension of the parent flag, this outputs the TGZ files into directories
			based on the structure used by Romba. This uses nested folders using the first
			4 bytes of the SHA-1, 1 byte for each layer of the directory name. It also
			includes two auxilary files, .romba_size and .romba_size.backup, that have the
			compressed size of the folder inside for use with Romba.
			
	-do, --directory	Enable outputting files uncompressed
		Instead of outputting the files to ZIP archives, files will be rebuilt to named
		subdirectories within the output folder. This is useful for when the DAT does not
		already have the flag specified.
		
	-7z={0}				Set scanning level for 7z archives
	-gz={2}				Set scanning level for GZip archives
	-rar={2}			Set scanning level for RAR archives
	-zip={0}			Set scanning level for ZIP archives
		For each of the major archive types recognized by the libraries used by this
		program, scan the archive in one of the following ways:
			0	Hash both archive and its contents
			1	Only hash contents of the archive
			2	Only hash archive itself (treat like a regular file)
			
	-ud, --update-dat	Output updated DAT (rebuild only)
		Once the files that were able to rebuilt are taken care of, a DAT of the files
		that could not be matched will be output to the program directory.

** Section 2.5 - TGZConvert

TGZConvert placeholder text

Usage:
	TGZTest.exe [options] [filename|dirname] ...

Options:

	-7z={0}				Set scanning level for 7z archives
	-gz={2}				Set scanning level for GZip archives
	-rar={2}			Set scanning level for RAR archives
	-zip={0}			Set scanning level for ZIP archives
		For each of the major archive types recognized by the libraries used by this
		program, scan the archive in one of the following ways:
			0	Hash both archive and its contents
			1	Only hash contents of the archive
			2	Only hash archive itself (treat like a regular file)

** Section 3.0 - Contributors

Programmer / Lead:	Matt Nadareski (darksabre76)
Additional code:	emuLOAD, @tractivo
Testing:			emuLOAD, @tractivo, Kludge, Obiwantje, edc
Suggestions:		edc, AcidX, Amiga12, EliUmniCk
Based on work by:	The Wizard of DATz

We welcome any contributors for coding, suggestions, optimizations, critisism,
heckling, abject anger, praise, and/or apathy.

** Section 4.0 - Licensing

This program uses, in part or in whole, code, libraries, and/or applications
from the 7-zip project (www.7-zip.org). 7-zip is licenced under the GNU LGPL.
All other external code is marked as such within the source and correctly
attributed to the site and/or person(s) that originally wrote the code. All
code written by project members is licensed under GPL v3. See LICENSE for
more details.