AutoPub Application Synopsis (Win95/WinNT)

The AutoPub application was built to provide a productivity tool for
html writers who take large existing documents (medical, legal,
technical, procedural, etc.), convert them to html, and publish the
html version on the world wide web. 

In most cases, the html author uses a third party product to convert
the original Microsoft Word, WordPerfect, or other word processor
document to html format.  The author must then polish the output to
achieve the desired "touch and feel".  If the document is lengthy, it
is usually broken up into smaller more manageable files and a Table
of Contents (TOC) is created to allow the reader to go immediately to
a specific section. This technique alleviates the reader from getting
bogged down by lengthy preamble in which they have no interest. 
AutoPub provides the means to the establish the desired "touch and
feel", break the large document into many smaller ones,  and generate
the TOC much faster than it can be done manually. 

What AutoPub Does
AutoPub reads the rule file you specify containing your defined
commands.  It then reads the source document into memory and modifies
the memory copy of the file based on these pattern commands.  You use
AutoPub's pattern commands to insert file break point patterns, as a
minimum.  Typically, you will insert file break point patterns
between the major number formatted sections of the big document but
that is up to you.  For example, you may insert a break point pattern
before 1., before 2., before 3. etc., if the document uses as its
major number format 1., 2., 3., etc.  AutoPub will, for each file
break pattern found:
1. extract the text between the start and end file marker patterns;
2. create an individual file for that text section;
3. copy header markups from a header template file to the created
file;
4. copy the extracted text to the file; and
5. copy footer markups from a footer template file to the created
file.
As indicated by items 3 and 5 above, AutoPub sandwiches the extracted
section text between header and footer markups when it creates the
smaller individual files.  You dictate the header and footer markups
by creating header and footer template files and directing AutoPub to
use them.  In the header template file, you define the traditional
markups that begin any WWW page, and the markups that customize it to
a "touch and feel" style that suits your taste.  In the footer
template file, you define the markups the customer will need to
navigate to the previous or next document section or back to the TOC
page.  In your footer navigational hyperlink references, you embed
the appropriate AutoPub system variables and the correct file names
and TOC entry text are substituted for these variables as each file
is created.  You are not restricted to the style described above. 
For example, if you choose to put the navigational hyperlinks in the
header you are free to do so.  Instead of putting the navigational
hyperlink references in the footer template you put them in the
header template, embed the appropriate AutoPub system variables in
the hyperlink references, and AutoPub substitutes the correct file
names and TOC entry text for these variables as it copies the header
markups to each file created.

If you have directed AutoPub to create a Table of Contents, the WWW
reader can scan the resulting TOC page for the document section they
wish to view, click on its hyperlink, and go directly to the
appropriate information in the small html file.   AutoPub will
extract TOC entry text between TOC markers you insert in the memory
copy of the document to create the Table of Contents page.  For this
to occur, you must create a TOC template file, direct AutoPub to use
it, and define a TOC entry line template within the TOC template
file.  As AutoPub creates the TOC file, it supplies the appropriate
file names and associated TOC entry text for its system variables
that you have embedded in your hyperlink references that make up the
TOC entry line template. If constructed to do so, the reader could
start at the beginning of the document and read it in its entirety by
clicking on hyperlinks at the bottom of each web page (document
section) to take them to the next or preceding page or back to the
Table of Contents.

Does AutoPub do this by you just feeding it the document?  Do you
write reports, procedures, etc. exactly the same way everyone else in
the world does.  I'm not trying to be sarcastic but pointing out
reality.  No application can read your mind to know how you want the
finished product to look or interpret the millions of ways documents
are formatted.  Html authors wouldn't be needed if an application
could do that, and the application writer could ask a lot of money
for such a product.  AutoPub does provide the methodology and the
command set to allow you to accomplish this task in a manner that
suits your needs and tastes.  The command set allows you to modify a
memory copy of the original document marking it with unique character
patterns that will later be used to extract TOC entry text and allow
AutoPub to chop up the memory copy of the document into many smaller
files.   You dictate the display style and navigation methodology by
defining the appropriate markups in the your header, footer, and TOC
templates.  Using AutoPub, you can publish a manageable document that
has the "touch and feel" you dictate in an amazingly  short time.

How:
How does AutoPub do this task?  Anything accomplished procedurally
needs a set of rules to live by.  AutoPub is no different.  You
dictate to AutoPub the rules it will use to break up the big file
into smaller files via its character pattern matching command set. 
You tell AutoPub where to find the source document and what name you
want the Table of Contents and individual files to have.  You create
a header and footer template file that contain the markups that will
define the start and end of each created page and tell AutoPub where
to find these files.  In the header template file, you define the
page layout and the "touch and feel" you want every page to have.  In
the footer template you define the navigational markups and provide
any additional information you deem reasonable for each page.  You
will embed AutoPub's predefined system variables in your markups to
generate the navigational hyperlinks.  You may create a TOC template
markup file that tells AutoPub how to construct the TOC page, and you
tell AutoPub where to find this file.  You decide how you want to
break up the document and using AutoPub's Wrap and Add character
pattern matching commands, to encapsulate the text you want in the
TOC and to specify the break point markers for files.  You will
define two unique sets of character pattern definitions, one for TOC
text and the other to specify file break points.  Since these unique
sets of character patterns are at your discretion, you tell AutoPub
what they are via the MakeTOC and MakeFile commands.  You may also
use the command set to delete unwanted text (Delete), replace
existing text with new text (Replace), and extract information from
the document and assign that information to variables you define
(Extract).  You can use your variables in any manner you wish in the
header, footer, and TOC templates.  AutoPub will substitute the
extracted text for your variables during WWW file creation when it
encounters them while copying the header, footer, and TOC template
file markups.  You must surround your variables with %% (e.g., if
your variable is title it must appear in the referenced files as
%%title%%) so AutoPub can distinguish that it is a variable. 
Additionally, you tell AutoPub in which order you want each command
type executed (e.g., all deletes 1st, all replaces 2nd, all extracts
3rd, all wraps 4th, followed by adds 5th).

Where:
Where is all this information kept?  AutoPub uses a rule file to hold
the information described above.  You can either create this file
manually using the text editor of your choice or let AutoPub assist
you via its Rule Editor.  If you create the rule file manually, your
rules must conform to the rule file command syntax.  If you use the
Rule Editor your rules are automatically converted to the rule file
syntax and are much easier to comprehend.  You will create a rule
file for each document you convert because no two documents are the
same.  You can assign the rule file and the header, footer, and
template files any name that makes sense to you.

Difficulty:
Doing the first document is the hardest part and may take longer than
breaking it up manually because of the learning curve.  But after
you've done one, you will have header, footer, and TOC template files
tailored to your "touch and feel" style that can be copied and
altered on the next document you do.  You will also have become
acquainted with the pattern matching command set that you will use to
define the rules to break up the document.  To help you get started,
an example document and rule files plus header, footer, and TOC
template files have been included with the application (see section
on Getting Started.  It is important to note that the header, footer,
and TOC template files reflect the author's style.  You may alter
these files to suit your own style tastes.

Uploading the Created Files to the WWW Server
If you are a registered customer, you will be allowed to upload the
TOC, WWW, and your generated images files at the conclusion of the
publishing operation.  See Uploading To The Server for details on
uploading.

General:
AutoPub remembers the last directory from which a rule file was
selected and will default to the that directory on the next
invocation.  Additionally, AutoPub will save up to the last 40 path
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, AutoPub 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.

Launching Your Editor/Browser:
AutoPub provides methods for you to launch both your text file editor
and your browser with a file you select from its log window.  To
launch a file, first left click on the display line containing file
you want to review.  This selects the line (encloses it in the red
rectangular box).  To launch your text editor with that file, left
click again (double click).  To launch your browser with that file,
right click on the selected line.  You define the editor and, if your
registered, the browser of your choice in the Options
Menu/Preferences TabHID_PREFERENCES.

UNIX vs DOS End-of-Line Formats:
The application automatically supports both the UNIX and DOS
end-of-line formats (hard line breaks).  The UNIX end-of-line format,
however, is displayed by AutoPub and most other Window applications
as a solid block since it is NOT interpreted by the edit controls as
a hard line break.  Additionally, AutoPub provides the !$ token to
allow you to indicate end of the current line in lieu of keying the
Enter key.  In the Rule Editor, if your pattern ends in a line break,
AutoPub will automatically display the !$ when you revisit the
command so you are aware that it is the last part of your pattern.

Limitations:
When creating the individual html files, AutoPub will append a
number, starting with 000, to the root name defined by WWWFileName:
in the &Header section of the rule file.  As each successive file is
created, the number is incremented by one.  This implies that there
is a limitation to the number of files (1000) that can be created
from a single document without ambiguity.

Acknowledgments
This application was initially suggested by Gary Cronin who is
President of Friday Associates of Burlington, Vermont.  The author
wishes to thank Gary, not only for the suggestion, but for his
support while the application was being developed.

