		HTML Merge Application Synopsis

The HTML Merge application was built to provide a productivity tool
for html writers and others to modify existing html web page files
more efficiently and with a lot less pain and strain.  As html and
the web evolve, constant change will be the name of the game for some
time to come.  This tool will make that change less painful.  The
tool creates a new file for each file you specify in the session file
set.  Each new file contains information extracted from the specified
files and merges that information between optional header/footer
markups.  The original files are preserved allowing you to reference
them as necessary after the operation.  You may define your new html
markups in the optional header and/or footer files.  Embedded in the
header/footer markups, you may define variables.  HTML Merge will
scan the existing file for those variables, extract the text
specified by the variable, and substitute the extracted text for
those variables when it creates the new files.  Variables usually
define text from the original file that you want retained in the new
file but under the same or a different format and usually represent
titles, headers, references, links, images...  HTML Merge requires
you to define the text you wish to retain (generally the body) from
the original files and allows you to define operations (substitute or
remove) to carry out on the retained text.  The retained text is:

* sandwiched between the header and footer markups;
* placed after the header markups if no footer file is defined;
* placed before the footer markups if no header file is defined, or
* is the new file if no header of footer file is defined.

If you simply want to carry out operations on existing files, you
need not define a header or footer, you simply specify:

* you want all the text from each session file;
* you want to be prompted as each file is created to select the text
to retain; or
* you define unique beginning and ending strings that encompass the
text you wish retained and

the operations you wish to carry out on the retained text.

How is all this accomplished?  You direct HTML Merge by creating a
rule file where you define the variables, the text to retain, and the
operations you wish to carry out on the retained text.  The
application allows you to build a new, edit an exiting, or use a rule
file you specify.  The rule file (discussed in The Rule
File section) is the key to successfully merging the new
markups with the extracted text.  Briefly, the rule file has four
sections which are:
1.	&command
The command section is required and is where you define pertinent
information for the application such as the file extension you want
to the new files to have, the location of the header and footer files
(if any) and the file types (identified by their extension) that you
are defining operations for and want to process.
2.	&scan
The scan section is only required if you define a header or footer
file and in the header/footer you defined variables.  Variables are
definitions of unique character patterns that HTML Merge will search
for in the original file, extract the information between the unique
starting and ending pattern expressions, and substitute that
extracted information for the variable in the header/footer. 
Variables, as stated above, usually define text that represent
titles, headers, references, links, images... from the original file
that you want retained in the new file.  As an example, you may want
to extract the original title for reuse in the new file so you define
a variable named title in your header file.  You must then define the
variable title in the scan section and the unique starting and ending
expressions in the existing files that delimit the title information
you want extracted.  An example variable definition might be,
title=<title>????</title>.  In this example <title> is the starting
expression, </title> is the ending expression, and to the application
???? means "extract text between".
3.	&retain
The retain section of the rule file is required since it defines to
the application what to retain from the original file.  As enumerated
above, the retain section supports three ways to define what text to
retain.  You may use the keywords all or prompt to direct HTML Merge
to extract the entire file or, as each file is created, prompt you
for the text to be retained.  The entire file contents are displayed
when you specify prompt allowing you to highlight the text you want
to retain.  The final method allows you  to define unique start and
end character pattern expressions and let HTML Merge extract the
information between those expressions from each selected file and
merge it into the new file.  An example of defining a start and end
expression might be, <body>????</body>.  It is important to note that
the start and end expressions need NOT be hypertext markups but must
be unique or you will get more or less than you expect.
4.	&cleanup
The clean up section is optional.  This is the section that instructs
HTML Merge what retained information in each new file to replace or
delete.  The clean up section can be used in two different ways.

First, if you are changing the touch and feel of a web site you will
more than likely define the majority of your new markups in the
header and footer files and will be retaining the body of the old
files.  You can use this section to remove or replace
unwanted/outdated information/markups that might still reside in the
old body information.

Second, if you are primarily modifying/updating markups, you will
most likely not have a header or footer file and will use the keyword
all to retain all of the text from original file.  You can then
specify the markups to be replaced or removed in this section.

NOTE:	This section is disabled until the application is licensed.

Building/Editing the Rule File:
As stated above, HTML Merge has a built in rule file builder/editor. 
Once you become accustomed to the expression definitions you may wish
to build/edit your rule files using the text editor of your choice. 
To use the rule file builder/editor, start HTML Merge and click the
Build Rule File button.  You will get a file dialog that lets you
either select an existing file to edit or allows you to create a new
rule file.  In either case, you will get a tabbed dialog (one tab for
each rule section) that allows you to add/edit/delete expressions for
each of the rule sections.  Once you have built/edited the rule file,
click the OK button on the tabbed dialog.  You then get the
opportunity to save the rule file under its existing name or as a new
file.

General:
HTML Merge  remembers the last directory from which merge and rule
files were selected and will default to the appropriate directory on
the next invocation.  Additionally, HTML Merge  will save up to the
last 100 (20 by default) paths and rule file names and allow you to
reuse those file names on subsequent invocations.  For those of you
who want a constant start position on your desktop, HTML Merge 
remembers its last size and desktop position and will restore itself
to that size and position until you change it.  If you position it
partially or fully off the desktop, it will restore itself fully on
the desktop.

Limitations:
The application was designed to handle a huge number of merge files
from multiple directory's.  There is a display limitation that will
limit the number of files you can merge at one time but it is so big
(greater 100,000 display lines and 1 merge consumes 1 display line)
that it should never come into play.  The application automatically
supports the UNIX and DOS end-of-line formats.  The UNIX end-of-line
format, however, displays the new line as a solid block since it is
NOT interpreted by the edit control as a hard line break.  Start,
end, remove, and substitute strings are limited to 260 characters
each.  There is no known size constraint for the extracted and 
retained text.

Invoke HTML Merge; build, edit, or specify a rule file, select as
many files to merge into new files from as many directory's as you
want, and let her rip.

Author's Note:
This tool was primarily designed as a productivity tool for HTML/web
authors for use on hypertext files.  However, since a text character
pattern matching schema was employed, it can be used on any text file
to accomplish tasks only you might visualize.  My son has found
several uses for this tool that I never envisioned.  He has also used
this tool for its intended purpose of modifying web sites.  He
changed his entire web site in a single operation using this tool. 
He accomplished the modification of over 400 hypertext files located
in 30 plus directories in less than 10  minutes which includes the
time to construct the header, footer, and rule files.  Of course, his
experimenting with different page styles is not included in that
time.  I have included his header, footer, and rule file as an
example to illustrate how this tool has actually been
used.  I built the tool initially at his request and have now
enhanced and hardened it for general use.



