@DATABASE English.guide

*************************************************************************

@NODE MAIN "MirrorCopy V1.0 © 1998-99 Jan Hendrik Schulz"

                               @{b}MirrorCopy@{ub}
                      @{b}© 1998-99 Jan Hendrik Schulz@{ub}
                         @{b}Version 1.0 (3.3.1999)@{ub}


	@{" Introduction       " LINK INTRO}      What is it? And Why?

	@{" Requirements       " LINK NEEDS}      Required hard- and software
	@{" Legal              " LINK LEGAL}      Please read this!

	@{" Installation       " LINK INSTALL}      How to install @{b}MirrorCopy@{ub}?
	@{" Usage              " LINK USAGE}      And how to use it?

	@{" Known Bugs         " LINK BUGS}
	@{" History            " LINK HISTORY}      What's new since the last version?
	@{" Future             " LINK FUTURE}      What is planed for the future?

	@{" Author             " LINK AUTHOR}      How to contact the author?
	@{" Thanks to          " LINK THANKS}

@ENDNODE

**********************************************************************

@NODE INTRO "Introduction"
@{u}Introduction@{uu}

@{b}MirrorCopy@{ub} is a shell filecopy command, which is able to create and
update an @{i}exact @{ui}copy (mirror) of all the files and subdirectories¹
(including there contents) located in a source directory. @{"I" LINK AUTHOR} use it to
maintain a mirror copy of my system partition on a bootable ZIP disk.
That way I not only have a backup of my system partition, I can even
boot directly off this backup (if I need to) and have all the tools etc
available I'm used to.

The main features of @{b}MirrorCopy@{ub} are:

  · The destination directory will contain exactly the same files
    and subdirectories¹ as the source directory - and nothing more!

  · The attributes (date, comment and protection flags) of the
    files and subdirectories² in the destination directory are set
    exactly to the same values as in the source directory.

  · @{b}MirrorCopy@{ub} takes care of what the destination directory allready
    contains:
    - only those files are copied, that need to be copied.
    - only those subdirectories are created, that need to be created¹
    - only those files and subdirectories¹ are removed from the
      destination directory, that need to be removed.
    This is very usefull if you don't want to @{i}create @{ui}a mirror copy,
    but if you want to @{i}update @{ui}an allready existing mirror copy.

  · @{b}MirrorCopy@{ub} can keep deleted or overwritten files in special
    'deleted-/old-files' directories (see @{"usage" LINK USAGE})

  · The contents of the source directory is not changed in any way!
    Not even the protection flags (like the archive flag) are changed.


The result of a programm call like:

  @{i}MirrorCopy source:dir/path/ dest:dir/path/ ALL @{ui}

is about² the same as if you would execute the following two commands:

  @{i}Delete dest:dir/path/#? ALL FORCE @{ui}
  @{i}Copy source:dir/path/#? dest:dir/path/ ALL CLONE @{ui}

But using @{b}MirrorCopy@{ub} is faster, especialy if the contents of the source
and the destination directories are allready nearly the same.

OK, but how does @{b}MirrorCopy@{ub} exactly work? @{b}MirrorCopy@{ub} compares the two
directories and:

  · copies a file found in the source directory into the destination
    directory, if in the destination directory:
    - no file with the same name exists yet.
    - a file with the same name exists, but with different date and/or
      different size³. (The old file is overwritten or moved to the
      @{"OLDDIR" LINK USAGE 30} directory.)
    - no file, but a directory with the same name exists. (The directory
      and everything it contains is deleted or moved to the @{"DELDIR" LINK USAGE 30}.)

  · creates a subdirectory, found in the source directory, inside the
    destination directory, if no subdirectory with that name exists in
    the destination directory yet¹. If a @{i}file @{ui}with that name exists in
    the destination directory it is deleted or moved to the @{"DELDIR" LINK USAGE 30}.)

  · removes files and subdirectories¹ from the destination directory,
    that do not exist (anymore) in the source directory. The files and
    subdirectories (including there contents) are deleted or moved to
    the @{"DELDIR" LINK USAGE 30}.

  · sets the attributes of files and subdirectories¹ in the destination
    directory to the same values as in the source directory if needed.

__________________________________________________________________________

1) The subdirectories are ignored, if the @{"ALL" LINK USAGE} keyword isn't used.

2) The standard Copy command (even if used with the CLONE keyword) @{i}doesn't @{ui}
   set the attributes of subdirectories correctly, but @{b}MirrorCopy@{ub} @{i}does @{ui}!

3) To determine if two files with the same name are identical, the
   sizes and the dates of the files are compared. If both files do
   have the same size and the same date (and of course the same name)
   it is @{b}very@{ub} likely that they are identical. That is, of course, not
   100% sure, but under normal conditions it is allways true. The
   only way to know it for sure would be, to compare the contents of
   the files, but than it would be faster to simply copy all files.

@ENDNODE

**********************************************************************

@NODE NEEDS "Requirements"
@{u}Requirements@{uu}

There are no special requirements. (At least not that I know...)

@ENDNODE

**********************************************************************

@NODE LEGAL "Legal"
@{u}Legal@{uu}

      This version of @{b}MirrorCopy@{ub} is freeware. Redistributing of
      @{b}MirrorCopy@{ub} is only allowed, if all files are included and
    unchanged. It's not allowed to make any profit in any way by
     redistributing @{b}MirrorCopy@{ub}. Including @{b}MirrorCopy@{ub} on CD-ROMs
    is allowed as long as the CD-ROM costs not more than 15 EUR
      or 20 US$. Before including @{b}MirrorCopy@{ub} on coverdisks you
            have to ask @{"me" LINK AUTHOR} to get a written permission.

        @{b}MirrorCopy is © copyright 1998-99 Jan Hendrik Schulz@{ub}

      @{b}MirrorCopy@{ub} is provided as-is, without warranty of any kind.
       You are using @{b}MirrorCopy@{ub} on your own risk. I'm in no way
    responsible for any damage or data loose, which may result in
     any way, directly or indirectly out of the usage of, or the
                  impossibility to use @{b}MirrorCopy@{ub}.

@ENDNODE

**********************************************************************

@NODE INSTALL "Installation"
@{u}Installation@{uu}

The installation is very simple. Just copy the program to an appropriate
place (e.g. 'C:')

And it wouldn't be wrong to keep this guide somewhere where you can
find it if you'll need it.

@ENDNODE

**********************************************************************

@NODE USAGE "Usage"
@{u}Usage@{uu}

@{b}MirrorCopy@{ub} must be run from a shell. The following shell arguments
are available:

@{b}FROM@{ub}/A
	The source directory with the files you want to make a mirror
	copy of. You have to give a directory here, not the name of a
	single file and not a pattern.

	The contents of this directory is not changed in any way.

@{b}TO@{ub}/A
	The destination directory where the mirror copy should be created
	in.

	The contents of this directory will be changed like explained in
	the @{"introduction" LINK INTRO}.

@{b}ALL@{ub}/S
	Without this keyword, @{b}MirrorCopy@{ub} will ignore subdirectories and
	will copy/delete only files found directly inside the FROM/TO
	directory.

@{b}BUF@{ub}/K/N
	With BUF you can change the size of the memory buffer used for
	coping. A larger buffer might increase the copy speed. The size
	is set in KBytes and the default size is 64 KBytes (BUF=64).

@{b}DELDIR@{ub}/K
	If you want to keep the files and directories, @{b}MirrorCopy@{ub} would
	usualy delete from the TO directory, you can use this keyword
	to specify a directory where @{b}MirrorCopy@{ub} should move those files
	and directories to instead.

	@{b}MirrorCopy@{ub} will create the necessary subdirectories inside this
	directory to keep the files with the same (relative) path inside
	this directory as they were relative to the TO directory.

	Currently this directory must be on the same volume as the TO
	directory, because for speed reasons @{b}MirrorCopy@{ub} moves the files
	and directories to the new location by renaming them - and it's
	not possible to rename across volumes.

@{b}OLDDIR@{ub}/K
	Like DELDIR but to keep the old version of those files, which
	are replaced (overwritten) with a new version of the same file
	(or a file with the same name).

	You can specify the same directory for DELDIR and OLDDIR if you
	want.

@{b}DATE@{ub}/S
	This keyword is only usefull in combination with DELDIR and/or
	OLDDIR. It tells @{b}MirrorCopy@{ub} to create a subdirectory with a name
	made of the current date inside the DELDIR/OLDDIR directory and
	use that subdirectory as DELDIR/OLDDIR directory. This way you
	can keep the files of different @{b}MirrorCopy@{ub} runs in different
	directories - especial usefull if you have files that change
	often.

	The name of the date-subdirectory looks like this: yyyy-mm-dd_Xxx
	with:
		yyyy	the four digit year
		mm	the two digit month
		dd	the two digit day
		Xxx	the first three characters of the day name

	This way, by sorting the directories by name, they are sorted
	by date as well.

@{b}VERBOSE@{ub}/S
	Enables additional output about what's going on. And a little
	statistic at the end with the number of files and directories
	that where copied/deleted/created/etc.

@{b}QUIET@{ub}/S
	This keyword tells @{b}MirrorCopy@{ub} to create no shell output, except
	error messages. QUIET even disables the output created with the
	VERBOSE keyword.

@ENDNODE

**********************************************************************

@NODE BUGS "Known Bugs"
@{u}Known Bugs@{uu}

No known bugs. But if @{b}you@{ub} found a bug, please send @{"me" LINK AUTHOR} a bugreport! (Do not
rely on someone else doing it! Thanks!)

@ENDNODE

**********************************************************************

@NODE HISTORY "History"
@{u}History@{uu}

@{b}version 1.0 (3.3.1999)@{ub}
· First public release.

@ENDNODE

**********************************************************************

@NODE FUTURE "Future"
@{u}Future@{uu}

If you have any ideas, why not send @{"me" LINK AUTHOR} an email!?

@ENDNODE

**********************************************************************

@NODE AUTHOR "Author"
@{u}Author@{uu}

Snail-Mail:	Jan Hendrik Schulz
		Elsässer Straße 19
		22049 Hamburg
		Germany

EMail:		schulz_j@informatik.fh-hamburg.de
   or:		schulzjan@dame.de

@{b}IMPORTANT NOTES:@{ub}
· Please @{b}don't@{ub} send your emails to @{b}both@{ub} email-addresses! First try @{b}one@{ub}
  of them and only if that fails try the other one. @{b}Thanks!@{ub}
· If you expect an answer via snail-mail, please send me enough money
  or (german!) stamps to cover my costs.

@ENDNODE

**********************************************************************

@NODE THANKS "Thanks to"
@{u}Thanks to@{uu}

Wouter van Oortmerssen		for AmigaE

@ENDNODE

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