@database BrowseAminet.guide

@node "Main" "Aminet Browser for DaFTP"

@{b}Aminet Browser for DaFTP graphical FTP client@{ub}
by Osma Ahvenlampi and Dan Murrel Jr.

@{" Legalese     " link "Legal"}  The things no one likes to read...
@{" Thanks       " link "Thnks"}  Who made this possible?
@{" Introduction " link "Intro"}  What's the purpose of this program?
@{" Installing   " link "Instl"}  How to start using it..
@{" Usage        " link "Usage"}  And what to do then.
@{" Advanced     " link "Advan"}  Advanced usage notes.
@{" History      " link "Histr"}  What bloopers were fixed in this version.

@endnode

@node "Legal" "Copyright, disclaimer, and othe legal mumbo jumbo"

BrowseAminet (Browse.DaFTP) is Copyright © 1994 by Osma Ahvenlampi, from
here on referenced as the Author. All rights reserved. BrowseAminet is
freely  distributable as long as it has not been modified without a prior
permission  from the Author, and no fee is charged for copying it. In
other words, BrowseAminet is provided free to use.

While a lot of effort has been taken to ensure correct function,
BrowseAminet comes with NO WARRANTY. In case it does not work as intended
or does unexpected things or damage, the Author can not be held liable.
By using BrowseAminet, you accept the responsibility.

@endnode

@node "Thnks" "The people who must be thanked for making this possible"

Dan Murrell Jr., for making DaFTP, which is awesome, and starting this
project.

Urban Müller and all the other Aminet maintainers, for keeping the archive
running. Without you, this program would have no purpose.

All the great people who have helped me when I've ran into difficulties.

@endnode

@node "Intro" "What is BrowseAminet for?"

BrowseAminet was written to serve a couple of purposes. First, it was a
demonstration of how to use DaFTP's ARexx interface. Most features of that
interface are used in BrowseAminet, and thus is serves as a reference for
other scripts.

Second, and more importantly, BrowseAminet is intended to simplify access
to @{"Aminet" link "Aminet"}. Normal FTP is quite unfriendly to use with large software
archives that update frequently. While a graphical FTP makes this easier,
it also can slow you down when you try to get several new files in
different directories.

Aminet admistrators try to make access simpler by providing good lists of
recent uploads with descriptions of the programs. Urban D. Müller has
written a program called Aminet Download Tool to use these lists (which he
designed himself). However, ADT was mainly written for UNIX systems, and
thus it isn't very Amiga-like.

This is where BrowseAminet comes into picture. An ARexx script to use
DaFTP's capabilities, it can connect to any Aminet mirror site, grab the
recent files list, convert it to an AmigaGuide document, hiding the files
you've already seen, and give you a chance to just point and click in the
document to get the files you want.

@endnode

@node "Instl" "How should you install BrowseAminet?"

The installation is very simple. First, you will naturally need DaFTP.
BrowseAminet will work best if DaFTP can be found in the Workbench search
path, but that is not necessary, if you always start DaFTP first.

Second, and this is important, Browse.DaFTP has to be placed in REXX:.
This is because it is called several times from within the AmigaGuide
documents it generates, and if you do not place it in a directory where RX
will find it, things will just fail.

Third, to be able to use the online help feature, you will need to copy
this document (BrowseAminet.guide) to a directory in the AmigaGuide search
path.

@{"An example of installation is here." link "Install-Example"}

That's all the installation there is. Now you can just execute the script,
and it will pop up an AmigaGuide window with a small list of select Aminet
sites. Don't worry if your favourite site is not in the list. Just connect
to any of the sites listed, and BrowseAminet will ask for an up to date
site list. The next time you use it, it will show you the complete list of
Aminet mirrors. This updating will happen automatically any time the
Aminet mirror list changes.

@endnode

@node "Install-Example" "An example of installation steps"

Note that this will probably not work as is on your system. It should give
you the general idea, though.

Copy DaFTP_AS225 TO: Inet:C/DaFTP
Path Inet:C ADD
Copy Browse.DaFTP TO: REXX:
Copy BrowseAminet.guide TO: HELP:

@endnode

@node "Usage" "What to do now that BrowseAminet is installed?"
@next "Histr"

Using BrowseAminet is simple. Execute it. Or, if you have already
installed BrowseAminet, just @{"click here to start it" rx "Browse.DaFTP"}.

If this is the first time you use BrowseAminet, you will be asked for your
rough location. This is used to choose the find server BrowseAminet uses.

Choose your favourite site from the list that pops up, and watch DaFTP
connect to that site. BrowseAminet will ask DaFTP to download the recent
files list, and subsequently make an AmigaGuide document of the new files
uploaded since you last used BrowseAminet.

This document is full of buttons.. Here is an example of what it will look
like. Just click on any button to see an explanation of what that button
does:

@{"  Show last week  " link "Help-ShowAll"}   @{" Search for a file " link "Help-Search"}   @{" Top downloads chart " link "Help-Chart"}
@{" Get marked files " link "Help-GetMarked"}   @{"    Upload file    " link "Help-Upload"}   @{"  BrowseAminet Help  " link "Help-Help"}

@{" MultiCX136.lha   " link "Help-GetFile"} util/cdit @{"  13K" link "Help-MarkFile"} @{" Multi Commodity v1.36 " link "Help-GetReadme"}
@{" Shri20.lha       " link "Help-GetFile"} util/cdit @{"   6K" link "Help-MarkFile"} @{" XpkSHRI.library 2.0 w/ 2 times faster decompr " link "Help-GetReadme"}

BrowseAminet can pop up a lot of windows, although they will all appear
over each other (at least with V40 AmigaGuide). You can close any window
at any time you wish, and the rest of them will continue working normally.

@endnode

@node "Help-ShowAll" "Show all files"
@toc "Usage"

  @{b}Show last week@{ub}      Search for a file     Top downloads chart
 Get marked files        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

Normally, BrowseAminet will only show the files uploaded to Aminet since
your last use. This button will tell it to make a document with all the
files uploaded in the last 7 days listed.

@endnode

@node "Help-Search" "Search by keyword"
@toc "Usage"

  Show last week      @{b}Search for a file@{ub}     Top downloads chart
 Get marked files        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

This button activates the search feature of BrowseAminet. This function
has some special requirements. First of all, it needs the TCP: device.
This is provided by AmiTCP's Inet-Handler. I am not aware of a similar
feature in AS225. The second requirement is ESR, a string requester by
Scott Ellis.

Provided both of these requirements are filled, pressing this button will
pop up a string requester, in which you can type the search keyword. This
will be sent to an ADT find server, and you will see next the files matching
the keyword. Currently, finds are limited to a maximum of 30 matches.

@endnode

@node "Help-Chart" "Top downloads chart"
@toc "Usage"

  Show last week      Search for a file     @{b}Top downloads chart@{ub}
 Get marked files        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

This button will get the "Aminet Top 10 downloads in the last week" chart
file and show it to you. This file is not, unfortunately, in the normal
BrowseAminet format. Maybe this will change later..

@endnode

@node "Help-GetMarked" "Get marked files"
@toc "Usage"

  Show last week      Search for a file     Top downloads chart
 @{b}Get marked files@{ub}        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

This button will tell DaFTP to get all the files marked for later download
with the @{"Mark" link "Help-MarkFile"} button (that shows file size).

@endnode

@node "Help-Upload" "Upload a file to Aminet"
@toc "Usage"

  Show last week      Search for a file      Top downloads chart
 Get marked files        @{b}Upload file@{ub}         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

This button will pop up a file requester, in which you can select the file
you want to upload to Aminet. The directory should also contain a .readme
file (for example, CoolUtil.lha and CoolUtil.readme), that has, at a
minimum, one line starting with "Short: " and containing the short
description of the file. For more information, refer to Aminet upload
policy readme.

@endnode

@node "Help-Help" "Help"
@toc "Usage"

  Show last week      Search for a file     Top downloads chart
 Get marked files        Upload file         @{b}BrowseAminet Help@{ub}

 MultiCX136.lha    util/cdit   13K  Multi Commodity v1.36
 Shri20.lha        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

This button will, surprisingly, show the @{"BrowseAminet online help" link "Usage"}.
However, this will only work if BrowseAminet.guide is placed in the
AmigaGuide search path.

@endnode

@node "Help-GetFile" "Get a file immediately (file name in the list)"
@toc "Usage"

  Show last week      Search for a file     Top downloads chart
 Get marked files        Upload file         BrowseAminet Help

 @{b}MultiCX136.lha@{ub}    util/cdit   13K  Multi Commodity v1.36
 @{b}Shri20.lha@{ub}        util/cdit    6K  XpkSHRI.library 2.0 w/ 2 times faster decompr

By clicking on any file name, you can instruct DaFTP to immediately
download the file.

@endnode

@node "Help-MarkFile" "Mark a file for later download (file size in the list"
@toc "Usage"

  Show last week      Search for a file     Top downloads chart
 Get marked files        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   @{b}13K@{ub}  Multi Commodity v1.36
 Shri20.lha        util/cdit   @{b} 6K@{ub}  XpkSHRI.library 2.0 w/ 2 times faster decompr

By clicking on the button displaying the size of the file, you will place
the file in the DaFTP Batch Mode file list for @{"later download" link "Help-GetMarked"}.

@endnode

@node "Help-GetReadme" "Get file description (short description in the list)"
@toc "Usage"

  Show last week      Search for a file     Top downloads chart
 Get marked files        Upload file         BrowseAminet Help

 MultiCX136.lha    util/cdit   13K  @{b}Multi Commodity v1.36 @{ub}
 Shri20.lha        util/cdit    6K  @{b}XpkSHRI.library 2.0 w/ 2 times faster decompr @{ub}

By clicking on the button showing the short description of the file, you
will instruct BrowseAminet to immediately get and display the full .readme
for the file.

@endnode

@node "Advan" "Advanced usage notes for power users"

While BrowseAminet is fully usable without a need to know anything told in
this chapter, power users may find that some of these things make use of
BrowseAminet faster.

@{b}Bypassing the front page@{ub}

You can make BrowseAminet skip the front page and connect to your
preferred Aminet mirror immediately by calling it with the command

    RX Browse.DaFTP CONNECT <address>

where <address> is the name of your favourite Aminet site.

Similarly, if you want to find an older file, without having to first
connect to an Aminet site, use

    RX Browse.DaFTP FIND <address>

where <address> is, once again, the name of your favourite Aminet site.
Note that this is NOT the find server address, but the address of the
Aminet mirror where the file will be fetched from in case you want to
download it.

@{b}Using GZIP compression with the RECENT file@{ub}

If you want to make BrowseAminet use compressed recent file lists, this
can be done simply by changing the ENVARC:BrowseAminet configuration file.
The second line of this file is in the form

<find server> <use-gzip> <max find hits>

So, just change the @{i}use-gzip@{ui} value from 0 to 1. Oh, and don't
edit this file while BrowseAminet is operational, because the changes will
be lost when it updates the file when quitting.

@{b}Getting more matches in file searches@{ub}

If a maximum of 30 matches for a file search you,
you can make it larger by changing the value of the @{i}max find hits@{ui}
in the prefs file (see above).

@endnode

@node "Histr" "What bloopers were fixed in this version?"

0.13
    Forgot to give the pubscreen name to DaFTP..
0.12
    Changed to use rexxreqtools.library, made find function more
    configurable.
0.11
    A bugfix in prefs file handling
0.10
    Support for ADT find servers added (needs TCP: device, which is a part
    of AmiTCP.. Maybe there's something for AS225 also, don't know
    really.)
    Can also UPLOAD a file to Aminet...

BrowseAminet has been tested on V40 AmigaOS (OS 3.1).

@endnode

@node "Aminet" "About Aminet"

Aminet is the premiere archive of freely distributable Amiga software.
Centrally located at ftp.wustl.edu, USA, it is mirrored around the world
and also available on CD-ROM. Aminet has received over 10,000 files, and
the complete archive, with full program distributions compressed with the
LhA archiver, takes almost 2 gigabytes of disk space.

A big thanks must go to all the great people who donate their time and
effort to keep Aminet operating.

@endnode