From mlehman5@VIOLET.BERKELEY.EDU Wed Feb 2 00:56:47 1994 Date: Tue, 1 Feb 1994 15:58:20 -0800 From: Matthew Lehman Reply to: Agriculture Discussion To: Multiple recipients of list AGRIC-L Subject: 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 Subject: Almanac User's Guide From: Almanac Information Server ## 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