Almanac Users Guide Oregon State University Extension Service Last Updated: March 26, 1992 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 Almanac Users Guide 2 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, you can quickly retrieve USDA market news, articles about the use of computer in agricultural science, and Extension Comput- ing Technology Newsletters. Use of this service is cost-free to electronic mail users and offers documents in many types of elec- tronic 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 auto- matically 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 that the bracket should not be typed. 2. Almanac-related E-Mail Addresses -ADDR- Almanac has several electronic mail addresses on the machine oes.orst.edu. It is important to send your message to the appro- priate address. Some are dealt with automatically while others go to humans. 2.1. Address for Requests Almanac's electronic mail address is > almanac@oes.orst.edu This is the address to which you will 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. Almanac Users Guide 3 2.2. Address for Submissions Send all submissions to the address below. The limitations men- tioned above apply here as well. > submit@oes.orst.edu See Section 8 for more information on submissions. 2.3. Address for Reporting Bugs All bugs in Almanac should be reported to > almanac-bugs@oes.orst.edu 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 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. Be sure that you use only genuine Almanac commands in the body of your message. The following list shows a few stan- dard Almanac commands: Command Description send catalog Get a list of available topics send guide Get this document subscribe extech-mg Subscribe to the "extech-mg" 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: Almanac Users Guide 4 Help File Description guide The users guide that you are now read- ing. catalog Lists and describes all available prima- ry topics. mail-catalog Lists and describes all current mailing groups. filter-list Shows the available filters, which are used to convert a file format. authors The Guidelines for Authors, which lists all the requirements for submitting an article to Almanac. Use send in your mail message to get a catalog of topics, as shown here: > send catalog 3.2. Guide Formats At the end of Section 1 it was mentioned that this guide can be retrieved by: > send guide This command will send you a plain text version of the guide with no control characters at all. To receive a text version that uses control characters to pro- duce underlines and bolding (similar to a Unix man(1) page): > send guide.txt To receive a PostScript* version of the guide: ____________________ *PostScript is a registered trademark of Adobe Systems. Almanac Users Guide 5 > send guide.ps To receive a uuencoded DVI (DeVice Independent) version of the guide: > mode uuencode > send guide.dvi 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 cabi- net. 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 extension folder/topic: > send extension catalog This catalog will in turn list available data under the topic of "extension". 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 Almanac Users Guide 6 alphanumeric name, but will generally be a number. For example, if you just received the catalog of Extension Com- puting Technology Newsletters (topic name extension ectn), and would like to receive volume 2, then you would request > send extension ectn 2 A mail message similar to the one below would be sent to you. Subject: RE: ectn vol 2 From: almanac (Almanac Information Server) To: userj@oes.orst.edu (Joe User) ## Regarding your request: send extension ectn 2 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. For instance, in the previous example you could have requested: > send ext ectn 2 with the same result, since ext is a valid alias for extension. 4.4. 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. 4.4.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: Almanac Users Guide 7 > 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 requestable 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.4.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: Almanac Users Guide 8 > 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@oes.orst.edu: > 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 reports, farmbill: > subscribe farmbill The OES Almanac also servers several hundred USDA "Market News Report" mailing lists. These are subscribed to slightly differ- ently. If you wish to subscribe to the USDA National Feedstuffs Market Review, which has the market news code pagr850: > subscribe market-news pagr850 5.2. Subscribing a Third Party You may also subscribe another person to a mailing list. First, be sure that the person wants to be on the list. Then, to sub- scribe Joe User (userj@ccmail.orst.edu) to pagr850, set the address option before issuing the subscribe command. > set address userj@ccmail.orst.edu > subscribe market-news pagr850 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. Almanac Users Guide 9 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 pagr850 as follows: > set address leeg@csri.toronto.edu > subscribe market-news pagr850 > set address peartn@csri.toronto.edu > subscribe market-news pagr850 > set address lifesona@csri.toronto.edu > subscribe market-news pagr850 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 farmbill list: > unsubscribe farmbill As mentioned above, market news reports are treated a bit dif- ferently: > unsubscribe market-news pagr850 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 pre- ceding the request for which you want the option applied. Options remain in effect for all subsequent requests in your message. The following list shows the available options: Almanac Users Guide 10 Option Description filter Use before a send command to change file format. reply-to Use before a send command to send the re- ply to a third party. address See Section 5 regarding the subscribe com- mand. 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 a2ps Converts ASCII files to PostScript for- mat col-b Converts or eliminates control charac- ters from text files strings Extracts the strings from binary files dvi2ps Converts DVI files to PostScript format as2ss Converts Amiga IFF sound files to Sparc- Station ulaw format raw2ss Converts raw sound files to SparcStation ulaw format ulaw2iff Converts SparcStation ulaw sound files to IFF format Almanac Users Guide 11 For example, to receive a PostScript version of the primary cat- alog: > set filter a2ps > send catalog When using filters, take care that the format of the Almanac file matches exactly what the filter expects as input. For instance, at this time sound files are uuencoded. This means that you should not try to request a sound file and filter it through ulaw2iff. This would attempt to convert the uunencoding rather than the actual IFF format. To receive a complete list of the available filters: > send filter-list 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@ccmail.orst.edu > send ext ectn 2 This would send the requested file to userj@ccmail.orst.edu. See Section 7 for information about how to use your mail sys- tem'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). Turn on 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 USDA market news reports in the same message, but want to receive them in separate files: Almanac Users Guide 12 > set separate on > send market-news wacb421 > send market-news wacb431 > send market-news wacb172 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 gener- ally handle messages of up to 500K. Likewise, if your mailing can only handle files of 20K, you should set your slimit appro- priately. 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 cur- rently 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 nec- essary for binary files, which cannot be sent through e-mail. If Almanac gives the following error Request would return binary data. Use encoding mode. Almanac Users Guide 13 then you must use this 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 fea- tures which can be useful in conjunction with Almanac. These fea- tures are in the form of its header lines. 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 par- ty. 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@ccmail.orst.edu: > To: almanac@oes.orst.edu > Reply-To: userj@ccmail.orst.edu > Subject: Celery Report You may also include your own mail address in the Reply-To line ____________________ *Simple Mail Transfer Protocol. This is the standard mail format for Unix mailers, specifically sendmail(8). Check with your site ad- ministrator if you are not sure whether your are running SMTP- compatible mail. Almanac Users Guide 14 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@ccmail.orst.edu 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 message. 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@oes.orst.edu > Return-Receipt-To: userk@ccmail.orst.edu > Reply-To: userj@ccmail.orst.edu > Subject: Celery Report 8. Submitting an Article -SUBM- If you have an article or any other information that you believe would be useful to have available on Almanac, send a note to the following mail address: > submit@oes.orst.edu