
------------------------------------------------------------------------------

	                                lll      ii    bbb     
        	                        ll             bb     
	     rr rrr  nnnnn    aaaa     ll     iii     bb     
	     rrr rr nn  nn      aa    ll      ii     bbbbb  
	    rr  rr nn  nn   aaaaa    ll      ii     bb  bb 
	   rr     nn  nn  aa  aa    ll      ii     bb  bb 
	 rrrr    nn  nn   aaa aa  llll    iiii   bb bbb    (c)

 			     RNALIB 2.0  
 
                      U S E R S '   G U I D E

            Copyright (c) 1989,1990, by Paolo Ventafridda
	             (venta@i2ack.sublink.org)
              Marco Lorenzini (marlor@gear.sublink.org)



INTRODUCTION
------------
RNA  handles  files inside internal directories  named  'LIBRARIES'.
The  DEFAULT  LIBRARY is referred as 'system library'  and  contains
this  HELP, system notes and anything that might interest you  about
RNA itself, included the INDEX of available libraries.

As  a  remote  user you can 'list' contents  of  libraries:   files,
sizes,  creation date.  Furthermore you can get - if available - the
verbose  description of a library;  this is called 'index', and it's
up to the sysop.  An index might not exist for some libraries.
The 'system library' has a special index available:  it lists all of
available public libraries.

You can query RNA by sending normal e-mail to a user named 'rnalib'.
This user does not really exist:  it's a dummy login for a "daemon".
Your  mail  is  read by a PROGRAM, not by a human, so you  must  pay
attention to fit some simple rules while 'talking' to him.

COMMAND SYNTAX
--------------
RNA recognizes command lines inside your email by grepping out of it
a  couple  of "@@".  So any line containing "@@"  potentially  might
contain commands.
Other  lines are IGNORED;  they are not processed, and not even read
by a human (again), so your greetings and thanks are useless ;-)
A command SHOULD start with @@ and last a single line.

You  can leave spaces ahead, that's no problem, but you can't by any
mean  put  words.  RNA would not understand.  There's  an  exception
however:   the  magic world 'Subject:' is correctly  recognized  and
skipped,  so that you can forward requests using the 'subject' field
of  your mail without bothering further on.  After '@@' there HAS to
be  at  least  one space or a tab.  A command  line  cannot  contain
'magic characters' like :  *\/'`"| .

***** BEWARE: DO NOT PUT <TABS> instead of spaces. *****

ADDRESS FOR THE ANSWER
----------------------
RNA is capable of recognizing automatically your email address.  You
don't  need to tell RNA were to ship its answers.  RNA will use your
email headers to figure out which path replies should go on.
Mail  will  come  straight  forward  to  you,  using  a  'UUCP-BANG'
addressing  style.  RNA will NOT consider headers declarations  such
as "Reply-To:" or "Sender:".

ASCII AND BINARY FILES
----------------------
You can ask for any files you 'list' inside libraries;  they will be
ship  inside ordinary email.  Unfortunately, email cannot be used to
transfer  binary  files,  so  we had to use something  in  order  to
translate binaries into pure-ascii text.

RNA  currently  uses  two kind of such converters:   "uuencode"  and
"btoa".   Both of them do the same job;  the only difference is that
"btoa" is more recent than "uuencode", and saves some 15% size while
'expanding'  the binary code into ascii .  However, you might expect
a  binary file sized -say- 100 to be encoded to a size of 150;  this
kind of translators do their best, but keep their limits.

Now  you  got the situation:  if you need a binary file, BE SURE  to
have  a  copy of either "uuencode" or "btoa" available, so that  you
will  convert  them  back to their original format as  soon  as  you
receive rna mail.

Of course, since "btoa" is much better than uuencode, if you have it
then USE it!  We'll see how to specify a 'btoa encoding' later on.

FILE COMPRESSION
----------------

If you are dealing with ascii files, then it's worth while trying
to use the famous 'compress' utility.  This will reduce up to 50%
or more file's sizes. Once a file has been compressed, you need
to convert it back to ascii with uuencode or btoa. These utilities
will expand a compressed file from 15-25% . Overall, you get a
size reduction of some 35-25%, which is not bad. 

LAYERS
------

Normally, RNA will use e-mail for delivering requested stuff.
E-mail needs to be ascii, that's why we use convertors.
If you use 'uucp' or 'uusend', there's no need to re-convert
a compressed file! In this case, go for a simple 'compress'
shipping through binary layers such as uucp.
Caution: using uucp/uusend presumes that the network you're on
allows - host by host - these remote commands.
Not always this is true; ask your postmaster!

STANDARD RNA COMMANDS
---------------------
A  list of available RNAlib commands follows.  Parameters inside  {}
mean  that it is not necessary.  Parameters inside [] means that  an
argument  is  required.  Commands can be both upper and lower  case;
arguments  ARE case-sensitive.  With 'origin' we mean the  user/host
who sent the query.
***** BEWARE: DO NOT PUT <TABS> instead of spaces. *****

----------------------------|--------------------------------------------
       command              |                  action
----------------------------|--------------------------------------------
        
        help                      sends back this help
        
        index {library}           sends a verbose description of
                                  library contents. If no library is
                                  specified, the system library is assumed
                                  and a list of available libraries is
                                  sent. At the end, a 'list' command is
                                  automatically executed. So you get a full
                                  description of what's inside a lib.


        list {library}            sends a list of library's contents.
                                  If no library is specified, system 
                                  library is assumed. This is useful
                                  whenever you need file names and their
                                  lenght, while you already know their
                                  meaning.

        find [filename]           searches inside ALL available libraries
                                  for files whose names match 'filename'.
                                  A result of the research is returned.

	credits                   will return how many bytes you are
                                  authorized to request before being denied.
                                  This is to prevent abnormal network traffic.
                                  Remember that someone is always PAYING for
                                  your requests. This command will report
                                  your credit left.

        send [filename] {from [library]} {with [encode_type]} {via [layer]}

                                  sends 'filename' from selected library;
                                  If no library is specified, system 
                                  library is assumed.

	* AVAILABLE ENCODE-TYPES and some of their aliases:

	  	uuencode		encode, ascii, DEFAULT
		btoa
		compress		compr
		compress-uuencode	compress-encode
		compress-btoa

	* AVAILABLE VIA-LAYERS and some of their aliases:

		uusend			
		uucp
		email			DEFAULT, mail, e-mail
		
	* Note: upper/lowercase allowed for all choices except DEFAULT
	  which is always uppercase.

	* Note: you can use also following internal aliases:

		with			using
		via			over, through 
		from			inside, in

Important Notes on 'send' 
------------------------

1-      When you ask for a file to be sent, RNA checks if it's ASCII or
        BINARY automatically. 

2-      You can ask for compression of files; obviously the result has
	to be converted to ascii, either with uuencode or btoa.
	If you don't specify btoa, uuencode will be used as default.

3-	If file is already compressed (its name is terminated by a .Z)
	rnalib will ignore your compress-request.

4-	If you ask for a file 'with uuencode' or 'with btoa', and this 
	file is a simple ascii-text, RNA will NOT follow your
	indication and ship the file as-it-is. In fact, there's no
	need to increase sizes and higher usenet's traffic!

5-	If you ask for a file 'via uucp' or 'via uusend', ascii convertors
	(btoa and uuencode) will NOT be used. See #4 for the reason.
	You are welcome to use 'compress', instead!


6-      If it's a binary file, RNA will AUTOMATICALLY encode it using:
        
                I) "uuencode" as a default
               II) "btoa" if specified and if locally available
        
        You may notice at this point that a declaration like
                        "with uuencode"
        is useless, since if the file needs to be encoded it will actually
        be treated just with this method; and if file is already ascii,
        this declaration will simply be discarded. The specification was
        allowed for future versions of RNA.

BLACKLISTS
----------
Blacklisting means that you are off-limits from this rna-site.
It could be as well that one of the hosts you're going through
has been blacklisted.
Blacklisting is applied for different reasons. One is 'credits':
this 'variable' can be fixed for hosts, for users and for gateways.
If rna keeps saying you're blacklisted, try asking around if 
someone else has been using rna as hell. The whole network you're on
might have been isolated.
Another reason is SECURITY: rna here traces all requests and analyzes
their contents. Whenever there's a 'strange' attempt to hurt itself,
a mail to postmaster is generated automatically.
Please do not send requests containing funny characters like
' $ * and so on. Note that wildcards are not allowed too.



RNALIB COMMAND EXAMPLES
-----------------------

(1)     You want to know which libraries are available.

                @@ index


(2)     You want to know what's inside  'games'.

                @@ index games

(3)     You just want to list a library named 'games'.

                @@ list games

(4)     You want to get a file named 'tetris' inside library 'games'.

                @@ send tetris from games

	This file will reach you via e-mail once transformed into
	ascii with uuencode.

(5)	You want tetris via e-mail using btoa.

		@@ send tetris from games using btoa
		or
		@@ send tetris from games with btoa

(6)	You want to reduce tetris's size:

		@@ send tetris from games using compress

	This file will reach you via e-mail after being
	compressed and uuencoded.

(7)	As (6), but using btoa instead of uuencode:

		@@ send tetris from games using compress-btoa

(8)	You are willing to try uucp transfer instead of email:

		@@ send tetris from games using compress over uucp

(9)     You want to search for files whose names contain 'rfc'.

                @@ find rfc

        You will get back a list of files with their related library.
        For instance you might get a message telling you that a file
        called 'rfc822' is available inside library 'documents'.
        At this point you can get it with:

                @@ send rfc822 from documents

	or any other valid syntax.

DIAGNOSTICS
-----------
RNA  will send you as much error diagnostics as possible, suggesting
you alternative commands and query methods.  If something goes wrong
you will receive a complete diagnostic of the problem and a possible
solution.


EXTERNAL DESTINATIONS (privileged origins only)
---------------------  ---------- ------ ----
Normally RNAlib sends its output to the origin of the query-message.
However, if you are a 'privileged origin' you may also specify for a
'send'  command a different destination, i.e.  another user, also on
another system.

To  do this, simply add to the normal 'send' command a 'to' followed
by the email address of the destination user.  This address might be
a UUCP-BANG or an ARPA format;  the address WILL NOT BE CHECKED.

Example:
                @@ send tetris from games with btoa to bob@usixth

Of course you can also use:
                                to usixth!bob
                                to onesys!twosys!user
                                to user@host.domain
                                etc.etc.

If  your  request is not a valid one for any reasons  -  nonexistent
library  or  files, syntax errors etc.  - response messages will  be
sent  to  YOU, NOT to the 'external destination'.  So if  you  don't
receive  anything  back from RNAlib, then your request was  accepted
and the stuff was sent to the specified external user.

BEWARE:   if  something goes wrong, at this point, the message  will
come  back  to RNAlib and archived as 'rejected mail'.   This  would
happen when your 'external destination' does not exist (user or host
unknown).  IT'S UP TO YOU that the 'to' argument is VALID.


USING EXTERNAL DESTINATIONS
---------------------------
RNA will only allow you to use 'to' inside a 'send' request.
This is not a real limitation, since :

-       It's no use to send a 'list' of files to another one.
        He might serve himself as well, right?

-       This HELP file is available inside the system library (default),
        and it's called 'HELP'.
        So if you want to send this file to a friend, all you have to
        do is :
                        @@ send HELP to user@host

-       Index is a simple file inside each library, called "INDEX".
        Index might not be available, though. System library however
        HAS an 'INDEX' containing list of available libraries.
        So you might always try:

                        @@ send INDEX to user@host

        which is equivalent to '@@ index'

                        @@ send INDEX from games to user@host

        which is equivalent to '@@ index games'.


                  -- END OF RNALIB 2.0 USERS' GUIDE --

------------------------------------------------------------------------------
