From almanac@amani.ces.ncsu.eduThu Jul 11 17:55:56 1996 Date: Thu, 11 Jul 1996 17:52:31 -0400 (EDT) From: Almanac Information Server Reply to: owner-almanac@amani.ces.ncsu.edu To: "Lawrence F. London, Jr." Subject: RE: (none) -------- ## Regarding your request: send guide Almanac Users Guide NC State University Extension Service Last Updated: May 1, 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- Almanac Users Guide 2 media documents to network users through electronic mail and accepts document submissions. Almanac allows you to get reports, newsletters, journals, articles, (in the near future) sounds, and graphics images. 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 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 ces.ncsu.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@ces.ncsu.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. 2.2. Address for Submissions Send all submissions to the address below. The limitations men- tioned above apply here as well. Almanac Users Guide 3 > submit@ces.ncsu.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@ces.ncsu.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 exttrain-mg Subscribe to the "exttrain-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 horticulture folder/topic: > send horticulture catalog This catalog will in turn list available data under the topic of "horticulture". 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. For example, if you just received the catalog of Horticulture Information Leaflets (topic name horticulture), and would like to receive the document on "Commercial Irish Potato Production" then you would request > send horticulture hil-22 A mail message similar to the one below would be sent to you. Subject: RE: horticulture hil-22 From: almanac (Almanac Information Server) To: juser@wolf.ces.ncsu.edu (Joe User) ## Regarding your request: send horticulture hil-22 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 hort hil-22 with the same result, since hort is a valid alias for horticul- ture. 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 Almanac Users Guide 7 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 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. Almanac Users Guide 8 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@ces.ncsu.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 Extension Training Specialists, exttrain-mg: > subscribe exttrain-mg 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 (juser@wolf.ces.ncsu.edu) to exttrain-mg, set the address option before issuing the subscribe command. > set address juser@wolf.ces.ncsu.edu > subscribe exttrain-mg 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 exttrain-mg as follows: Almanac Users Guide 9 > set address leeg@csri.toronto.edu > subscribe exttrain-mg > set address peartn@csri.toronto.edu > subscribe exttrain-mg > set address lifesona@csri.toronto.edu > subscribe exttrain-mg 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 exttrain-mg list: > unsubscribe exttrain-mg 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: 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. silent Use to supress the ## Regarding your re- quest: line. Almanac's options are set by issuing the set command followed by an option and possible arguments: Almanac Users Guide 10 > 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 dvips Converts DVI files to PostScript format For example, to receive a PostScript version of the primary cat- alog: > set filter a2ps > send catalog 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 juser@wolf.ces.ncsu.edu > send hort hil-22 Almanac Users Guide 11 This would send the requested file to juser@wolf.ces.ncsu.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 Horticulture Leafleats in the same message, but want to receive them in separate files: > set separate on > send horticulture hil-22 > send horticulture hil-300 > send horticulture hil-612 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. Almanac Users Guide 12 6.6. Silent Normally, Almanac prints the line ## Regarding your request: preceding the output of your request. If you do not want this line printed, you can set the silent option: > set silent on 6.7. 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.7.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. then you must use this mode. 6.7.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. Almanac Users Guide 13 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 juser@wolf.ces.ncsu.edu > To: almanac@ces.ncsu.edu > Reply-To: juser@wolf.ces.ncsu.edu > Subject: Potato Leaflet 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 juser@wolf.ces.ncsu.edu ____________________ *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 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@ces.ncsu.edu > Return-Receipt-To: userk@wolf.ces.ncsu.edu > Reply-To: juser@wolf.ces.ncsu.edu > Subject: Potato Leaflet 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@ces.ncsu.edu