
@@MODULE(head.txt)@@

This files describes the main tool 'wit'.


@@MODULE(content.txt)@@


*******************************************************************************
*******                    Overview about this document               *********
*******************************************************************************

Contents:

    Output of 'wit --help'
    @file
    Commands in detail
    Processing --source and --recurse
    Processing ISO files
    Processing ID6 parameters
    Processing exclude options
    Processing title db
    Processing split options
    Processing size options
    Selecting files with --files=rules
    Some options in detail
    Hidden options (for testing)
    Some options in detail
    Environment variables
    Signals


*******************************************************************************
*******                      Output of 'wit --help'                   *********
*******************************************************************************
@@EXEC(./wit --width 80 --help)@@


*******************************************************************************
*******                             @file                               *******
*******************************************************************************

If a parameter beginns with '@' the text behind that '@' is a filename.
Each line of the file is taken as a parameter (not option, not command).
Each line may terminate with LF or CR+LF. Handling of '@' is *not* recurse.

The special filename '-' means: read from standard input (stdin).


*******************************************************************************
*******                        Commands in detail                       *******
*******************************************************************************

The tool 'wit' processes the --source and the --recurse options to built an
internal ISO database (any ISO formats like WDF and FST included). Most of the
follwing commands works with the files of this ISO database (like 'wwt' do it
with a WBFS). The options --source and --recurse atre described in the section
"Processing --source and --recurse" in detail.

Command abbreviations are allowed as long as they are unique. The commands
are listed in alphabetic order:


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 CONVERT)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 COPY)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 CREATE)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 DIFF)@@
~ [2do] copy to homepage

 The command DIFF compares all given sources agains a destination (directory).
 If the option --dest is not set the last parameter is used as destination.
 If exact one source file is given the destination can be a file name. If two
 or more source files given the destination must be a directory. Option --DEST
 is like --dest, but the directory path is created automaticaly.

 Each source is candidate for comparing. Non ISO files are ignored with a warning.
 The option --ignore suppresses this warning.

 If option --long is set, the first failed position is printed. If option --long
 is set two or more times all falied positions are printed, but only the first
 position of each ISO block. The size of an ISO block is 0x8000 = 32768 bytes.

 In file mode (--files=) the rules are changed. The ISO images are compared on
 file level. System areas like disc and aprtiton headers are also served as
 files. Only files that matches the defined filters will be compared. In --quiet
 mode the comparing is done silently. Otherwise all non equal or missing files
 are reported.


 DESTINATION FILENAME

@@MODULE(output-filename.txt)@@


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    DIFFER              : At least one file pair differ.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.
    WRITE ERROR         : error while writing a file.
    CANT OPEN           : Can't open file.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 DUMP)@@
~ [2do] copy to homepage

 DUMP will dumps the data structure of all ISO files. If the option --long is
 set an additional memory map for each partition is printed. If the option
 --long is set twice or more an additional memory map for the whole ISO file
 is printed at the end. Failures (overlapped areas) are marked with '!'. If
 the option --long is set three times or more a total memory is appended at
 the end of the dump.

 If the option --files= is set than a file list is included into the dump.
 The rules define which files are listet. To list all files use "--files=+".
 The section "Selecting files with --files=rules" dicuss more details.
 The options --psel= and --raw are only used to make a pre selection of
 the partitions for the file list.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while read a file given by option --part.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 EDIT)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 ERROR)@@
~ [2do] copy to homepage

 The command ERROR translate an exit code to a text message. Without parameters
 print all error names and error messages. With a given 'error_code' the error
 message that belongs the number is printed to stdout and the program exits
 with exit status is 0 (success). If the error_code is unknown or invalid the
 error message is '?' and the program exits with exit status is 1 (failure).

 Without 'error_code' a list of all error codes is printed. The output
 contains three columns separated with colons. The format is:

    error code ':' error name ':' error messages

 If the option --sections is set, then the layout is completly changed to a
 sections base output. This output is machine readable. The output looks like:

	[error-CODE]
	code=ERROR_NUMBER
	name=ERROR_NAME
	text=ERROR_TEXT


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.
    SEMANTIC ERROR : unkown error_code given.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 EXCLUDE)@@
~ [2do] copy to homepage

 The command 'EXCLUDE' builts the exclude data base and prints the result to
 stdout. The handling of the additional files works like the --exclude option.
 The section "Processing exclude options" explains the options in detail.


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 EXTRACT)@@
~ [2do] copy to homepage

 ** no documentation yet **


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.
    WRITE ERROR         : error while writing a file.
    CANT CREATE         : Can't create output file.

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

COMMAND:
    FDIFF | FCMP ...

 'FDIFF' is a synonym for 'DIFF --files +'.
 See command 'DIFF' for options and details.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 FILELIST)@@
~ [2do] copy to homepage

 The filename of each file in the internal file list is printed as one line.
 If no source is given, the current working directory is used as source.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 FILES)@@
~ [2do] copy to homepage

 ** no documentation yet **


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.

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

COMMANDS:
    FILES-L   | FL    [source]...
    FILES-LL  | FLL   [source]...

 'FILES-L'   is a synonym for 'FILES --long'.
 'FILES-LL'  is a synonym for 'FILES --long --long'.
 See command 'FILES' for options and details.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 FILETYPE)@@
~ [2do] copy to homepage

 The command 'FILETYPE' prints for each file in the internal file database
 (build by the options --source and --recurse) one status line like:
    FILETYPE ID6 SIZE_MIB REGION filename
 Column 'ID6' is only printed if option --long is set. For non ISO images
 the ID6 is '-'. Columns 'SIZE_MIB' and 'REGION' are only printed if option
 --long is set at least two times.

 If neither --source nor --recurse is used and no other source is defined then
 the default directory is searched for ISO files.

 'SIZE_MIB' is the calculatet size of a scrubbed ISO image. For this all used
 sectors of a ISO image are counted. The usage depends of the options --psel
 and --raw.

 Filetypes are:
    NO-FILE  : No file found
    DIR      : Not a file but a directory
    WBFS     : A WBFS
    WBFS/    : A WBFS used like directory with id6 or index or pos
    WDF+WBFS : A WBFS shrinked with WDF (this make no sense expect transporting)
    ISO      : A ISO image.
    WDF+ISO  : A ISO image shrinked with WDF.
    WDF      : Any other WDF file (not WBFS or ISO)
    WIA      : A ISO image packed with WIA.
    GCZ      : Dolphins GameCup-Zip images.
    OTHER    : Any other file


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 HELP)@@
~ [2do] copy to homepage

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 ID6)@@
~ [2do] copy to homepage

 The command 'ID' lists the ID6 of all discs in the internal ISO database, one
 ID per row. The internal ISO database is build under control of the options
 --source, --recurse, --include, --include-path, --exclude and --exclude-path.
 See section "Processing --source and --recurse" for details.

 If neither --source nor --recurse is used and no other source is defined then
 the default directory is searched for ISO files.

 If --uniqe is set each game disc with same ID6, name, size and region is only
 printed once. To determine doube entries the list is sorted by ID.

 The output sort order can be set by the --sort option. Sort=none means, that
 the ID will be shown in order of the WBFS partition. The default sort order
 is 'ID'.


 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 ISOSIZE)@@
~ [2do] copy to homepage

 The command 'ISOSIZE' prints for each file in the internal file database
 (build by the options --source and --recurse) one status line like:

    ISO_BLOCKS  SIZE_IN_MIB  WBFS_FILESIZE  SIZE_IN_500G_WBFS  filename

 The size is calculated for a scrubbed ISO image. For this all used sectors
 of a ISO image are counted. The usage depends of the options --psel and --raw.

 ISO_BLOCKS
    The number of used ISO blocks. Each ISO block has a size of 32K.

 SIZE_IN_MIB
    The number of used ISO blocks in MiB. It's a rounded value ISO_BLOCKS.
    Column SIZE_IN_MIB is only shown if the option --long is set.

 WBFS_FILESIZE
    The total size of a wbfs file that contains only 1 disc. The calculation
    is made under the assumption that the WBFS blocks size is 2 MiB. Column
    WBFS_FILESIZE is only shown if the option --long is set at least twice.

 SIZE_IN_500G_WBFS
    The size of a ISO image as part of a WBFS with about 500g total space.
    The calculation is made under the assumption that the WBFS blocks size
    is 8 MiB. Column SIZE_IN_500G_WBFS is only shown if the option --long
    is set at least twice.

 If neither --source nor --recurse is used and no other source is defined then
 the default directory is searched for ISO files.

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 LIST)@@
~ [2do] copy to homepage

 The command 'LIST' lists infos of all discs in the internal ISO database.
 The internal ISO database is build under control of the options --source,
 --recurse, --include, --include-path, --exclude and --exclude-path.
 See section "Processing --source and --recurse" for details.

 Without --long the ID and the name are printed. With option --long the ID,
 size, region and the name are printed.  The option --no-header suppress the
 output of header and footer.

 Printing of timestamps is enabled by the options --time, --itime, --mtime
 --ctime, --atime or when --long is set at least twice. --time=off disables
 time printing. All time options (not --long) supersede the previous options.
 The option --time take a comma separated list of the following keywords:

    OFF    : Disable time printing. All other option enable time printing.
    ON     : Enable time printing.

    SINGLE : Print only a single column (last time specified.
    MULTI  : Print columns for all specified times. (default)

    I      : Use itime (insertion time) for processing.
    M      : Use mtime (last modicifaction time) for processing. (default)
    C      : Use ctime (last staus change time) for processing.
    A      : Use atime (last access time) for processing.

    NONE   : Disable all 4 times above
    ALL    : Enable all 4 times above
    
    DATE   : Print time in format 'YYYY-MM-DD'. (default)
    TIME   : Print time in format 'YYYY-MM-DD HH:MM'.
    MIN    : Alternative keyword for 'TIME'.
    SEC    : Print time in format 'YYYY-MM-DD HH:MM:SS'.

    *DATE  : Short cut for '*,DATE'. '*' is one of 'I', 'M', 'C' or 'A'.
    *TIME  : Short cut for '*,TIME'. '*' is one of 'I', 'M', 'C' or 'A'.
    *MIN   : Alternative keywords for '*TIME'.
    *SEC   : Short cut for '*,SEC'.  '*' is one of 'I', 'M', 'C' or 'A'.

 If the option --long is given three or more times a second line with the
 number of partitions, the file type ('ISO', 'WDF', ...) and the file path is
 printed. If the option --long is given three times the real path is printed.

 If the option --sections is set, then the layout is completly changed to a
 sections base output. This output is machine readable. The output looks like:

	[section_name-index]
	parameter=value
	parameter=value
	...

 If available the name of the title database is used. use the option -T0 to
 disable database titles.

 If --unique is set each game disc identified by ID6 is only printet once.
 The sort order can be set by the --sort option. Sort=none means, that the ID
 will be shown in order of scanning. The default sort order is 'TITLE'.

 If neither --source nor --recurse is used and no other source is defined then
 the default directory is searched for ISO files.

 Usual ERROR/EXIT CODES:

    0 == OK             : all done without errors.
    SYNTAX ERROR        : at least one syntax error in command line found.
    READ ERROR          : error while reading a file.

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

COMMANDS:
    LIST-L   | LL    [source]...
    LIST-LL  | LLL   [source]...
    LIST-LLL | LLLL  [source]...

 'LIST-L'   is a synonym for 'LIST --long'.
 'LIST-LL'  is a synonym for 'LIST --long --long'.
 'LIST-LLL' is a synonym for 'LIST --long --long --long'.
 See command 'LIST' for options and details.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 MIX)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 MOVE)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 RENAME)@@
~ [2do] copy to homepage

 This command 'RENAME' may change the ID6 and/or the title of discs. The
 alternative command 'SETTITLE' modifies only titles. The advantage of
 'SETTITLE' is, that it can modify all titles with 1 sub command.

 The syntax of a sub command is: id6=[new_id6][,new_title]
    'id6' is the ID of the disc to change.
    The optional 'new_id6' is the new ID of the disc.
    The optional 'new_title' is the new title of the disc.

@@MODULE(set-title.txt)@@

 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 SETTITLE)@@
~ [2do] copy to homepage

 This command 'SETTITLE' may change the title of discs. The alternative
 command 'RENAME' can also change the ID of discs.

 The syntax of a sub command is: id6=new_title
    'id6' is the ID of the disc to change. If using '+' all discs are changed.
    The 'new_title' is the new title of the disc.

@@MODULE(set-title.txt)@@


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 TITLES)@@
~ [2do] copy to homepage

 The command 'TITLES' builts the title data base and prints the result to
 stdout. The handling of the additional files works like the --title option.
 The section "Processing title db" explains the options in detail.


 Usual ERROR/EXIT CODES:

    0 == OK        : all done.
    SYNTAX ERROR   : at least one syntax error in command line found.


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 VERIFY)@@


-------------------------------------------------------------------------------
@@EXEC(./wit help --width 80 VERSION)@@
~ [2do] copy to homepage

 The command VERSION prints out the program version to standard out (stdout)
 and exit with status 0 (OK).

 The ouput line looks like:
@@EXEC(./wit version | sed 's/^/    /')@@

 With option --sections the output is printed in a machine readable format:
@@EXEC(./wit --sections version | sed 's/^/    /')@@


 Usual ERROR/EXIT CODES:

    0 == OK : all done without errors.


*******************************************************************************
*******               Processing --source and --recurse                 *******
*******************************************************************************

The tool 'wit' processes the --source and the --recurse options to built an
internal ISO database (ISO, WDF, WIA, FST and more ISO files included). All
operations are then done with the files of this ISO database (like 'wwt' do it
with a WBFS).

 Options:
    -s --source  path
    -r --recurse path
       --rdepth  depth

Both options work similar and both option can be used multiple times. If 'path'
is a non existing file an error message is printed. If 'path' is an plain file,
it is opened and analyzed. If that files is an ISO file in any supported format
than it is added to the internal ISO database.

The options --source and --recurse differ only if 'path' is an directory.
Option --source searches that directory but not subdirectories for ISO files.
Option --recurse searches that directory and all subdirectories (recurse, max
depth is set by --rlevel, default=10) for ISO files. Subdirectories beginning
with a dot ('.') are ignored.

The implementation is optimized so that a directory is only searched once.
The option --recurse is processed before option --source.


@@MODULE(proc-iso.txt)@@


@@MODULE(proc-id6.txt)@@


@@MODULE(proc-exclude.txt)@@


@@MODULE(proc-titles.txt)@@


@@MODULE(proc-split.txt)@@


@@MODULE(proc-size.txt)@@


*******************************************************************************
*******                      Some options in detail                     *******
*******************************************************************************

@@MODULE(opt-sort.txt)@@


*******************************************************************************
*******                   Hidden options (for testing)                  *******
*******************************************************************************

There are some hidden options implemented for testing:

 --io value

    wit and the other tools can handle files via open() (file mode) and via
    fopen() (stream mode). The option --io=value allows to control the method.
    Bit #0 is for opening WBFS and Bit #1 is for openening ISO images.
    ('ISO' includes ISO in all supported formats)

    --io=0 : WBFS=open()  ISO=open()  **default**
    --io=1 : WBFS=fopen() ISO=open()
    --io=2 : WBFS=open()  ISO=fopen()
    --io=3 : WBFS=fopen() ISO=fopen()


*******************************************************************************
*******                      Environment variables                      *******
*******************************************************************************

The user can define environment variables as additional way to submit options
to the tool. All options are accepted and used as default. 

See https://wit.wiimm.de/info/environ.html for details.


@@MODULE(signals.txt)@@


*******************************************************************************
*******                              END                                *******
*******************************************************************************
