SavePage.awebrx

                                Version 1.0

                     Public Domain by Magnus Holmgren


Introducton
===========

This script allows you to save a web page, together with all embeded
images, to a drawer. The entire window, optionally with subframes, as well
as a single frame, can be saved.


Requirements
============

SavePage.awebrx Requires AWeb 3.0 or higher.


Disclaimer
==========

The author is in no way responsible for moral and/or material damages that
his program may cause to people or things. The programmer gave his best to
limit the problems that this tool may cause, but he is not able to
guarantee its efficiency in all situations. Using this program, you the
user, are responsible for all moral, material, civil and penal things.


Distribution
============

This script is public domain. Use it in whatever way you want.


Installation
============

The easiest way is to use the included installation script, which installs
"SavePage.awebrx", this documentation ("SavePage.doc") and optionally
creates an initial configuration.

Otherwise, simply copy the script, and perhaps this documentation, to some
convenient place. Recommended places are "AWeb3:Plugins/" or
"AWeb3:Plugins/SavePage/".

Then add an entry for the "SavePage.awebrx" script in the ARexx menu, as a
GUI button, as a frame popup or as a key; whatever you find convenient. A
recommended configuration includes a frame popup menu entry and at least
one of the other alternatives.

For the ARexx menu entry, simply enter the name of the script (including
path), followed by any arguments. For the other alternatives (frame popup
menu, GUI button and key), enter the AWeb ARexx command "Run", followed by
the name of the script (again with path) and any arguments.

See below for information about available arguments.


Usage
=====

Call syntax:

	SavePage.awebrx [<frame>] [FRAMES|ASKFRAMES] [DRAWERS]
	                [TO "<drawer>"]

<frame> is the ID of the frame to save. If not specified, the page in the
currently active window (i.e. the "topmost" frame) is saved.

If "FRAMES" is specified, any frames in the page in question will be saved
as well. If "ASKFRAMES" is specified, SavePage will ask if frames should be
saved or not. If both are specified, "FRAMES" will be ignored.

If "DRAWERS" is specified, then SavePage will try to recreate the directory
structure and store objects in appropriate drawers. See below for details on
this feature.

If "TO" is specified (note that <drawer> *must* be quoted) the page will be
saved to the specified drawer. If not specified, a file requester will ask
for the drawer to save to.

For example, you could add a frame popup menu entry like this:

    Run AWebPath:Plugins/SavePage.awebrx %i FRAMES

This would save the current page and any frames within it. To save the page
to "Ram:", asking if frames should be saved, use the following:

    Run AWebPath:Plugins/SavePage.awebrx ASKFRAMES TO "Ram:"

No files will be overwritten. If a file already exists, a number will be
appended to the name. Names that are too long are truncated.


Creating drawers
================

The "DRAWERS" argument causes SavePage.awebrx to attempt to recreate the
correct drawer structure locally. The saved page is considered to be the
base URL for this process (for frames the "saved page" is the topmost frame
that is saved). All other URLs are compared with the base URL, and drawers
are created based on that.

Drawers will only be created in the destination drawer. So, if a file is
located in a parent drawer of the base URL, then SavePage.awebrx will
create the drawer "root" and store the file relative to the root of the
server within this drawer. If a file is stored on a different host, a
drawer named after the host is created and the file is stored relative to
the root of the host within this drawer.

Now, that was a bit abstract, and quite possibly difficult to understand.
;) An example should clear things up. Consider the following URLs:

    http://www.foo.com/bar/pages/home.html
    http://www.foo.com/bar/images/logo.gif
    http://www.foo.com/bar/pages/images/group.jpg
    http://www.bar.com/foo/counter.jpg

SavePage.awebrx will create the following files and drawers (in the "TO"
drawer):

    home.html
    root/bar/images/logo.gif
    images/group.jpg
    www.bar.com/foo/counter.jpg

There are a few problems here. Temporarily redirected URLs (e.g., sites
with "virtual host names") could be handled as the last image in the
example above. This is because the base URL is not redirected (as the
script sees it), while the rest of the URLs are. In that case, the files
will be stored in a drawer named after the host they really are stored on.

Another problem with redirected pages is cased by AWeb. When the script
tells AWeb to save an URL at a certain place in your computer, AWeb will
"forget" what that place was, and will open a file requester. This will
happen regardless if SavePage.awebrx is recreating the drawer structure or
not.


History
=======

Version 1.0 - 1999-Jan-23
-----------

Initial release.


Author
======

Magnus Holmgren <lear@algonet.se>


Acknowledgements
================

William Parker - For beta testing, a few suggestions, and the Installer
script that was used as a base for the current Installer script.