[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