[Prev][Next][Index][Thread]
Almanac User's Guide (fwd)
Here's the user's guide which you would request by sending mail to the
almanac server and putting in the body of the message send guide.
---------- Forwarded message ----------
From: almanac@esusda.gov
To: Matt Lehman <mlehman5@violet.berkeley.edu>
Subject: Almanac User's Guide
From: Almanac Information Server <almanac@esusda.gov>
## Regarding your request:
send guide
Title:Almanac Users' Guide-Extension Service, USDA(ES)
Author:USDA Extension Service, Washington DC
Document-date:Oct. 22, 1993
Expires:
----------------------------------------------------------------------------
Almanac Users Guide
U.S.D.A Extension Service
Washington, DC
Last Updated: October 22, 1993
0. Table of Contents
You may move directly to any section of this guide by using your
text viewer's search option to locate the upper-case search string
for that section. The list below shows the search strings for each
section.
Section Search String
1 Introduction
2 Mail Addresses -ADDR-
3 Receiving Help -HELP-
4 Receiving Information -FILE-
5 Mailing Lists -LIST-
6 Specifying Options -OPTN-
7 E-Mail Options -MAIL-
8 Submitting Articles -SUBM-
1. Introduction
This guide describes what Almanac is, what it offers, and how to
use it. It explains how to retrieve help and information files.
In addition, it demonstrates the use of options in messages, both
Almanac retrieval options and electronic mail options. Instruc-
tions for submitting articles for retrieval through Almanac are
also included.
Besides occasional examples, this guide does not attempt to
describe all the information that is available through Almanac.
See the next section for instructions on how to request a catalog.
Almanac is an information server designed to answer requests
received through electronic mail. Almanac was developed at the
Oregon Extension Service at Oregon State University from a grant by
the W. K. Kellogg Foundation. It delivers auto-generated, multi-
media documents to network users through electronic mail and
accepts document submissions. Almanac allows you to get reports,
newsletters, journals, articles, sounds, and graphics images. With
Almanac locate at ES-USDA, you can quickly retrieve ARS extracts,
and subscribe to various USDA and Extension Service information
sources such as USDA AGam, Press Releases in addition to
publications produced within ES-USDA.
Use of this service is cost-free to electronic mail users and
offers documents in many types of electronic publishing formats.
In the future, Almanac will offer SGML-based documents that can be
converted into dynamic electronic publications using software sys-
tems such as DynaText. These multi-media documents will be
automatically formatted and displayed. SGML tags generate links
such as a table of contents that allow readers to jump to detail
levels in the document. In addition, SGML documents can integrate
graphic images, sound, and animation applications.
All example messages in this guide are shown with angle brackets on
the left hand margin. For instance, this document can be retrieved
by sending the message
> send guide
** NOTE ** the bracket should not be typed.
2. Almanac-related E-Mail Addresses -ADDR-
Almanac has several electronic mail addresses on the machine at
esusda.gov. It is important to send your message to the appropri-
ate address. Some are dealt with automatically while others go to
humans.
2.1. Address for Requests
Almanac's electronic mail address is
> almanac@esusda.gov
This is the address to which you send all requests for Information
If your machine is not directly connected to the Internet, your
addressing may be different. Consult your site administrator if
the above address does not work.
2.2. Address for Submissions
Send all submissions to the address below. The limitations men-
tioned above apply here as well.
> submit@esusda.gov
See Section 8 for more information on submissions.
2.3. Address for Reporting Bugs
All bugs in Almanac should be reported to
> almanac-bugs@esusda.gov
Try to be as specific as possible when describing the problem.
Include an example if possible.
3. Requesting Help -HELP-
You may use any electronic mail program that is capable of sending
a message over the Internet to send a message to Almanac. If you
need help using your mail program, contact your site administrator.
It is not necessary to include a subject in your message, although it
is recommended. Be sure that you use only lower case Almanac commands
in the body of your message. The following examples show a few
standard Almanac commands that are used on this system:
Command Description
send catalog Get a list of available topics
send guide Get this document
subscribe usda.cite Subscribe to the "USDA ES CITE " mailing list
mode uuencode Uuencode the document in the reply
set slimit 20 Split reply messages over 20 kilobytes
3.1. Using the send Command
If you received this guide from Almanac, then you have already
used the send command. Send tells Almanac to send the informa-
tion you requested to your mail address. It can be used to
request either a help or topic file.
The following help files are available:
Help File Description
------------ ------------------------------------------
guide The users guide that you are now reading.
catalog Lists and describes all available primary
topics.
mail-catalog Lists and describes all current mailing
groups.
submit-full The Guidelines for Authors, which lists
all the requirements for submitting an
article to Almanac and to ES-gopher.
submit-brief A brief summary of document headers, for
those who have submitted before, but need
a quick reminder of header fields.
Use send in your mail message to get a catalog of topics, as
shown here:
> send catalog
4. Requesting Files -FILE-
Almanac is primarily a server for retrieving files. In order to
easily locate specific files, some discussion is necessary regard-
ing the organization of these files.
4.1. Organization of Topics
Almanac's topics can be thought of as folders in a filing
cabinet. Each folder contains a number of files. In addition,
a folder may contain folders within it, which contain files or
folders themselves.
When you send the request
> send catalog
you will receive a catalog of the primary folders in the "filing
cabinet". Each of these folders have their own catalogs.
For example, to receive the catalog for the ERS reports area,
> send ers-reports catalog
This catalog will in turn list available data under the topic of
"ers-reports". These data may be either files or folders.
4.2. Making the Request
After searching through these topic folders, you will find a
file that you want to retrieve. The file may have any
alphanumeric name, but will generally be a number.
For example, if you just received the catalog of ERS reports,
(topic name ers-reports), and would like to receive the document
called 0001, then you would request
> send ers-reports 00001
A mail message similar to the one below would be sent to you.
Subject: RE: ers-reports request
From: almanac (Almanac Information Server)
To: userj@esusda.gov (Joe User)
## Regarding your request:
send ers-reports 00001
Body of the document
...
4.3. Aliases
Many of the files and folders have abbreviated names called
aliases. Whenever a catalog says that a file or folder has an
alias, that alias can be used instead of the full name. You could
then request the document/file by using the alias of that section.
4.4. Requesting Multiple Files
Almanac provides a limited ability to request multiple
files in a single mail message. Note that in these cases
Almanac will consider all the files to be one single request,
so almanac will return only a single mail message, except if
the file is larger than 64K.
## Regarding your request:
Your request
followed by all of the files requested.
4.4.1. Requesting All Files of a Topic
You may request all of a topic's files together using a
quoted asterisk in place of a number. For example, to
request all of the ERS reports:
> send ers-reports "*"
******* NOTE *******
Take care when using the asterisk. You may request many more
files than you wanted. This can become expensive depending
on your e-mail routing.
4.4.2. Requesting Selected Files
You may request multiple selected files from a single topic
area by enclosing a comma-separated list within quote marks
and brackets. For example, to request several ERS reports,
00001, 0002, 00003 and 00004:
> send ers-reports "[0001,0002,00003,00004]"
Those familiar with the Unix* shells may notice a familiarity in
these methods. Almanac uses the Bourne shell, sh(1), to
retrieve the desired files. Any Bourne shell wildcard expansion
will work when requesting files from Almanac. Note that these
techniques only work when requesting actual files. See the dis-
cussion below on Non-files.
4.5. Special Cases
With a system as flexible as Almanac, there are necessarily
exceptions to the simple system described above. These are not
crucial differences, but noteworthy nonetheless.
____________________
*Unix is a registered trademark of AT&T.
Almanac Users Guide 8
4.5.1. Non-files
Although all of the information received from Almanac can be
thought of as a file, not all retrievable data is actually
stored as a file within Almanac. Almanac can also execute
programs, as in the case of quote. By sending the request:
> send quote
you are in fact asking Almanac to execute a program which
returns a random quotation. The difference is subtle but
important. A file's contents will be static--it will not
change no matter how many times you request it. A program,
on the other hand, returns dynamic information.
quote is an extreme example of dynamic information; you are
unlikely to receive the same quotation twice. Another reque-
stable program, send alm-stats, on the other hand, changes
gradually over time, giving a dynamic report of Almanac's
usage.
Despite the fact that not all information that you receive
from Almanac is a file, This document will continue to refer
to them as files for the sake of simplicity.
4.5.2. Non-folder Primary Topics
It was mentioned in Section 4.1 that when you request the
primary catalog
> send catalog
you receive a catalog of the primary "folders," which in turn
have their own catalogs. This is not strictly true; quote,
mentioned above, does not have a catalog because it is not a
folder containing data, but instead provides data itself.
The non-folders in the primary catalog are marked as such.
5. Mailing Lists -LIST-
Almanac is the server for a number of mailing lists. Electronic
mailing lists, also known as "mailing groups," "reflectors" or
"exploders," are much like physical mailing lists. If you have an
e-mail address, you can simply subscribe to a list. After that,
you will receive every message that is "posted" to the list.
Some lists are two-way forums, in which the subscribers of the list
post messages to each other. Others are one-way servers which send
out reports, newsletters and other periodicals to the subscribers.
To receive a catalog of the mailing lists that Almanac serves, send
the following:
> send mail-catalog
This catalog briefly describes the purpose of each list and whether
it's a forum or server list.
5.1. Subscribing
Once you have found a mailing list in the catalog to which you
want to subscribe, send the following subscribe command to
almanac@esusda.gov:
> subscribe mailing-list
where mailing-list is the name of the desired list.
For example, if you wish to subscribe to the mailing list which
serves USDA Farm Bill news releases, usda.farmbill:
> subscribe usda.farmbill
5.2. Subscribing a Third Party
You may also subscribe another person to a mailing list. First,
make sure the person wants to be on the list. Then, to subscribe
Joe User (userj@cite.esusda.gov) to pagr850, set the address
option before issuing the subscribe command.
> set address userj@cite.esusda.gov
> subscribe usda.farmbill
This tells Almanac that all further subscriptions should go to
Joe User rather than yourself. See Section 6 for more informa-
tion on setting options.
The address option is in effect for the rest of the request mes-
sage, unless it is changed by setting again. You can subscribe
a number of people to a mailing list as follows:
> set address leeg@csri.toronto.edu
> subscribe usda.cdev
> set address peartn@csri.toronto.edu
> subscribe usda.cedv
> set address lifesona@csri.toronto.edu
> subscribe usda.cdev
5.3. Unsubscribing
If you no longer wish to receive an Almanac mailing list, you
may unsubscribe to it in the same manner that you subscribed.
For example, to unsubscribe from the usda.farmbill list:
> unsubscribe usda.farmbill
Unsubscribe requests will take effect within 24 hours of when
the request is received by Almanac.
6. Retrieval Options -OPTN-
Almanac's options specify how information will be sent to you.
Options should be specified on a separate line in your message
preceding the request for which you want the option applied.
Options remain in effect for all subsequent requests in your mes-
sage. The following list shows the available options:
Option Description
filter Use before a send command to change file
format.
reply-to Use before a send command to send the
reply to a third party.
address See Section 5 regarding the subscribe
command.
separate Use before a send command to receive each
request in a separate mail message.
slimit Use to define the maximum size message
that your mailing system can receive.
Almanac's options are set by issuing the set command followed by an
option and possible arguments:
> set option argument
where option is one of the options in the table above, and argument
may be a qualification of the option. Specific examples are shown
below.
6.1. Filter
Use the filter option to tell Almanac to convert a file to a
different format before sending it. The following list shows
some of the available filter options:
Filter Description
-------- ---------------------------------------------
col-b Converts or eliminates control characters
from text files
strings Extracts the strings from binary files
When using filters, take care that the format of the Almanac
file matches exactly what the filter expects as input.
6.2. Reply-To
If your mail system does not support a reply-to option, then you
can include a reply-to line in your message, as shown here:
> set reply-to userj@cite.esusda.gov
> send rrdb catalog
This would send the requested file to userj@ccmail.orst.edu.
See Section 7 for information about how to use your mail
system's Reply-To option.
6.3. Address
The address option is similar to reply-to. It used with the
subscribe command, which is described in Section 5.
6.4. Separate
By default, if you send several requests in one message, the
requested files will be returned to you in one message (unless
the reply exceeds the slimit value--see the next section).
Use the separate option before the send command if you wish to
receive each request in a separate file. For example, if you
would like to request three ERS reports in the same message, but
want to receive them in separate files:
> set separate
> send ers-reports 00003
> send ers-reports 00230
> send ers-reports 00005
6.5. Slimit
Use the slimit option to tell Almanac the maximum message size
that your mailer can handle. For example, if you request a file
106K (kilobytes) in length and your electronic mail system can-
not receive messages larger than 50K, then send the following
command:
> set slimit 50
Your 106K file will be broken up between three reply messages,
the first two being 50K, the third 6K.
Slimit defaults to 64K so that Almanac can send mail through
most mailers. If your mailer can handle larger files, it is
advisable to set the SLIMIT higher. Internet mailers can gen-
erally handle messages of up to 500K. Likewise, if your mailing
can only handle files of 20K, you should set your slimit
appropriately.
6.6. Modes
A mode sets several options at once. With a mode you can form
an entire environment for your request message. There are
currently two major modes.
6.6.1. Mode Uuencode
The uuencode mode is invoked with the command
> mode uuencode
It will set up your environment so that the rest of the
requests in your message an returned uuencoded. This is
necessary for binary files, which cannot be sent through e-
mail. If Almanac gives an error message, use the encoding mode.
6.6.2. Mode Unix-compress
The unix-compress mode sets more of your environment. If
your machine can uncompress files that have been compressed
with 16-bit Lempel-Ziv compression, as with the Unix
compress(1) command, then you can reduce your transfer time
by having Almanac compress the reply message. Note that
because a compressed file becomes a binary file, it must then
be uuencoded to be sent over e-mail. Thus, the unix-compress
mode also calls the uuencode mode.
7. Electronic Mail Options -MAIL-
Almanac can receive all SMTP* mail. SMTP has a few build-in
features which can be useful in conjunction with Almanac. These
features are in the form of its header lines.
____________________
*Simple Mail Transfer Protocol. This is the standard mail format
for Unix mailers, specifically sendmail(8). Check with your site
administrator if you are not sure whether your are running SMTP-
compatible mail.
Almanac Users Guide 14
Following are some of the mail systems options that can be used
when mailing a request to Almanac:
SMTP Option Description
Reply-To Use to forward a request to a third
party.
Return-Receipt-To Use to verify that Almanac received your
request.
7.1. Reply-To
Add a Reply-To line to your message header to tell Almanac to
send your request to a third party. For example, enter the fol-
lowing header to request a file and forward it to a user whose
mail address is userj@cite.esusda.gov
> To: almanac@esusda.gov
> Reply-To: userj@cite.esusda.gov
> Subject: Farmbill Information
You may also include your own mail address in the Reply-To line
to send your request to the third party as well as to yourself.
Note that the Subject line is optional, but may help you to
identify the reply message. Recall from Section 6 that if your
mailer does not support a Reply-To header, you can set the
reply-to option in the body of the message:
> set reply-to userj@es-cit.esusda.gov
7.2. Return-Receipt-To
Add a Return-Receipt-To line with your own mail address to your
message header to verify that your request was received by
Almanac. You will receive a reply when Almanac accepts your mes-
sage. The following example shows how to use the Return-
Receipt-To line when sending a request for a reply to a third
party:
> To: almanac@esusda.gov
> Return-Receipt-To: userk@some.agency.gov
> Reply-To: userj@cite.esusda.gov
> Subject: Celery Report
8. Submitting an Article -SUBM-
Use the send command to receive the Guidelines for Authors, as
shown here:
> send submit-full
The Guidelines for Authors describes requirements for suitable
material, style, document preparation, bibliographic formats, and
file formats. It also includes a sample manuscript. Binary files
must be encoded with uuencode(1) before mailing. See the Guide-
lines for Authors if you need more information. The mail address
for submissions to Almanac is:
> submit@esusda.gov