Article 1167 of comp.sources.amiga: Submitted-by: zim@ibx.com (Bill Zimmer) Posting-number: Volume 96, Issue INF4 Archive-name: administrivia/intro4/part01 [ Most of this is from Tad Guy. Michael 'Moose' Dinn made a few ] [ modifications and I have also modified the text here and there. ] Welcome to comp.sources.amiga and comp.binaries.amiga. This posting is an introduction to these newsgroups. There are several topics covered here, each preceded with a Subject: line. If you become bored with the current topic, you can skip to the next by searching for the next Subject:. However, you should read this entire posting before submitting software, or asking questions about these groups. The subjects in this article are: + Why are sources in shar format? or... Waiter! There's a binary in my source! + How a comp.binaries.amiga submission is packed. + How to unpack a submission. + What software is useful in unpacking postings? + What these groups are NOT! + How do I submit software? + A (admittedly incomplete) list of archives sites + Format of Articles + Credits... The archive sites listed below may contain these old postings. If you know of any additional archive sites, please let me know. -------- Subject: Why are sources stored in shars? or... Waiter! There's a binary in my source! It's historical. Traditionally, a `sources' group contains just that -- source code. While it may be more useful for Amiga users to receive uuencoded Lha files containing the source code, one of the traditions of a sources group is to present the programs in a format that can be easily decoded by systems the postings were not intended for. Thus, sources are packaged in plain UNIX shar files. Occasionally a source file will contain unprintable characters, often ANSI sequences. It's unlikely that these files will pass through gateways unscathed, thus those files are `uuencoded'. Care is taken that the uuencoded filename is (1) different from the original filename, and (2) within the 14 characters in length. More frequently, the binary for a program is very small, at least relative to the size of the sources. In these cases, the executable is also uuencoded and packaged with the sources, and a suitable message from the moderator is included in Part01 of the postings. In cases where there are many binary files, or the binary files dwarf the sources, a separate companion posting is issued in comp.binaries.amiga containing those files and any documentation included in the package. Often, the comment from the moderator will refer to the other postings. -------- Subject: How a comp.binaries.amiga submission is packed. Each comp.binaries.amiga submission is packaged using the Lha archiver. Lha not only compresses the submission, but also checks the files for corruption, and preserves the original directory structure and timestamps. The Lha archiver is available from most Amiga archive sites and BBS'. Binary submissions and Lha files contain 8-bit data, which cannot be reliably transferred over USENET or by mail. The Lha archive is thus encoded down to 7-bits using the ``uuencode'' program. The ``uudecode'' program, required to reverse this encoding, is also available from many Amiga archives (often under the name ``uucode''). USENET has a conventional limit of 64k bytes per posting. While larger postings often occur, they are also often mysteriously corrupted at some point. Unfortunately, most of the uuencoded Lha archives in comp.binaries.amiga are larger than 64k bytes. In order to get each posting to 64k or smaller, the single uuencoded Lha archive is ``split'' into 64k pieces, which can later be concatenated back into the original uuencoded Lha archive. The UNIX ``cat'' and the AmigaDOS ``join'' commands are ideal for this. Each part of the now-split uuencoded Lha archive is then wrapped using some simple UNIX commands in a form called a ``shell archive''. This makes the postings easier to unpack on UNIX systems, and can be unpacked on Amiga's using the UNSHAR or SH utilities, available from some amiga BBS'. At this point, a single submission has been Lha'ed, uuencoded, split, and each part shar'ed. This is what you find posted to comp.binaries.amiga. -------- Subject: How to unpack a submission. Before a submission can be used, it must be unpacked in the reverse order it was packed. This is easily done on UNIX machines, and can be done on Amigas with the appropriate utilities. 1. Save each part to a different file name of your choosing. How this is done depends on what news reader or mail user agent you're using. Often, there will be a command `s' or `o' to save a message to disk. Some news readers can even unpack postings automatically. Consult the documentation of your mail or news reader for more information. 2. Remove the USENET headers (the first line of each file should be ``#!/bin/sh''). This step can be skipped if you have the ``unshar'' utility. Use your favorite text editor to accomplish this. You must edit each part of the submission. 3. Run each file using ``sh'', or ``unshar''. If you're using a UNIX system, you could use ``sh filename'' or ``unshar filename'', depending on which utility you're using. Repeat this for each part of the submission. If a comp.sources.amiga posting is being unpacked, then at this point the source files should be in the current directory, and you can stop here. If a comp.binaries.amiga posting is being unpacked, then step 3 will create a uuencoded form of the Lha file. 4. Decode the uuencoded Lha archive using ``uudecode''. This will generate the original Lha archive. ``uudecode filename.zuu'' 5. Use Lha to extract the files from the Lha archive. ``lha x// filename.lha'' Typically, it's easiest to do steps 1-5 on a UNIX machine, although utilities exist to do all those steps on an Amiga. Once you have a Lha archive, though, you will probably find it easiest to transfer the archive to your Amiga and use Amiga Lha to extract the archive there. -------- Subject: What software is useful in unpacking postings? All these tools mentioned in this article are free for the taking if you can find them: . The Lha archiver is available from many Amiga BBS' and Amiga archives on the Internet. Lha is generally available in the same places. . The uuencoding utilities are often already installed on UNIX machines, and there is also at least one Amiga version, which typically goes under the name of ``uucode''. . Concatenating the parts of a submission is easily done under UNIX with the ``cat'' command, or under AmigaDOS with the ``join'' command. . Under UNIX, the `unshar' utility, if available, can be used to unpack the shar'ed postings. In the absence of `unshar', the Bourne Shell (/bin/sh) can be used, though it is less secure against `trojan-horse' shar files (not that any would be posted to the Amiga code groups, of course). Similar utilities exist for the Amiga, often called ``UNSHAR'' and ``SH''. . The NewsBreak utility by Fred Walter (grwalter@watfun.uwaterloo.ca) can automate much of the unpacking process. It has been posted to comp.sources.misc, and should be available from sites that archive that group (like ftp.uu.net). -------- Subject: What these groups are NOT! Please do not even think of posting discussion message, request for software, messages containing ``SEND INDEX'', etc. to these groups! Such messages will be deleted from the software queue, without indication (though you will receive an acknowledgement when the posting is received). Each posting to these groups contains a line stating where non-sources should be posted. Read that line. -------- Subject: How do I submit software? The role of the moderator of comp.sources.amiga and comp.binaries.amiga is to receive submissions, ensure they are not copyrighted (or if they are, to ensure that permission is granted to redistribute them), and to repackage the submission in the form described above. Persons wanting to make submissions to the these groups do NOT need to worry about encoding the submission as described above, although doing so makes my job easier and means the submission will get out faster. However, it is vitally important to include in your submission: + A simple, one word `name' for the software package, for use in the Subject line when the package is posted. + A simple, one line `description' of the software package, also for use in the Subject line. + The version number, if any, of the software. This is required if an older version of the software has previously been posted within the last year. + A brief (one or paragraph) description of the software, for inclusion in Part01 when the software is posted. It's acceptable to quote part of the documentation for this. + Permission to freely distribute this program (explicitly stated). + In the case of shareware, the license may NOT *require* payment, but may request payment. The distinction is subtle, but important. Note that binary submissions must be encoded into 7-bits to insure it is received intact. This can be done using the ``uuencode'' utility described above, or with any number of similar utilities (such as ``btoa''). It's easiest for the moderator to unpack Lha and LHarc files, so even `sources only' postings can be submitted in this format. They will be repackaged as described above before they will appear in the newsgroups. There are two ways to get your submission to the moderator: . Post your submission to the appropriate newsgroup. If your USENET software is properly configured (yeah, right), this will automatically forward your submission to the moderator, without your having to know the moderator's address. This is probably the most intuitive method, though the most likely to fail due to improperly managed USENET software. . Mail your submission to the moderator's address. This requires that your know the moderator's address, but is the only choice for persons at sites with improperly configured USENET software. Considering that the address appears several times in this posting, this shouldn't be a problem. If your submission is received by the moderator, you will get a response back by mail (although network problems may cause your submission or the acknowledgement to be delayed). If you don't get an acknowledgement within a week, assume something has gone wrong. The best course of action is to attempt to contact the moderator by email (please don't send your submission again, instead hold onto it until you and the moderator determine a reliable way for you to send your submission). Submissions to comp.sources.amiga and comp.binaries.amiga may be mailed to: amiga@uunet.uu.net or ...!uunet!amiga Consult your system administrator if you have trouble sending mail. Comments and suggestions are welcome. They should also be addressed to the addresses above. -------- Subject: A (admittedly incomplete) list of archive sites The list below is incomplete, but is provided as a good starting point for locating back issues of comp.sources.amiga and comp.binaries.amiga. Please consult these sites instead of posting a message asking where you can find some particular piece of software, or asking that some part of a large package be reposted... The following sites allow anonymous ftp. To access these sites, use your host's `ftp' command to connect (see your system documentation or guru), login as `anonymous', with your email address as the password. (Also, the FTP FAQ is posted monthly to comp.sys.amiga.misc). ccsun.unicamp.br 143.106.1.5 /pub2/usenet/comp.sources.amiga ftp.wustl.edu 128.252.135.4 /usenet/comp.binaries.amiga /usenet/comp.sources.amiga ftp.germany.eu.net 192.76.144.75 /pub/newsarchive/comp.sources.amiga /pub/newsarchive/comp.binaries.amiga ftp.uu.net 128.252.135.4 /usenet/comp.sources.amiga ftp.sterling.com 192.124.9.1 /usenet/comp.sources.amiga The above sites were found using archie. If you know of any other sites that archive either comp.binaries.amiga or comp.sources.amiga, please let me know. If you cannot reach these sites (because you're not on the Internet, or because of some local limitation on network access), but you can receive email, then send a message to BITFTP@PUCC.PRINCETON.EDU containing the word `HELP'. You will receive instructions on using the BITFTP server to access anonymous ftp sites entirely by email. This will only work if you are on BITNET. For non-BITNET users, send an email message containing the word 'help' to ftpmail@decwrl.dec.com. -------- Subject: Format of Articles This section goes into detail on the format of comp.sources.amiga and comp.binaries.amiga, with an emphasis on automatic archival of the postings. While this may be too much detail, I've received queries about most of this information at one time or another. However, if you're more interested in using the postings rather than using the header lines, you should proceed to the next section. The format of articles in comp.sources.amiga and comp.binaries.amiga is modeled after that of other sources groups (notably, comp.sources.unix). This is done with the goal of allowing existing archival software developed for those groups to process amiga postings without modification. Here is a sample article, with uninteresting header lines removed: | From: amiga-request@abcfd20.larc.nasa.gov (Amiga Sources/Binaries Moderator) | Subject: v90i374: lome 1.1 - line oriented macro processor, Part01/03 | Reply-To: Darren New | Newsgroups: comp.binaries.amiga | | Submitted-by: Darren New | Posting-number: Volume 90, Issue 374 | Archive-name: util/lome-1.1/part01 | | [ See comp.sources.unix for the sources to these programs. ...tad ] | | This set of executable contains three general purpose line-oriented | macro processors and the documentation to run them and a couple of | examples. When a package is posted to comp.sources.amiga or comp.binaries.amiga, it is split into multiple `parts', where a part is (roughly) 64,000 bytes. This is done to allow the articles to pass through some gateways which may limit posting sizes. When each part is posted, it contains the current part number and the number of parts in the Subject line of the primary header. Each comp.sources.amiga and comp.binaries.amiga posting contains two groups of header lines. The first is called the `primary' or `main' header, and is the header used by most USENET software. It includes the `Subject', `From', and `Newsgroups' lines, among others. The second header (strictly speaking, this header is in the body of the posting) is termed the `auxiliary' header, and contains information useful to automatic archival software. This header contains the `Submitted-by', `Posting-number', and `Archive-name' lines. Use of these lines is explained below. Optionally following the two headers is a comment from the moderator (always enclosed in the []'s, unless he forgets), and a description of the software being posted. Except in unusual cases, this description is included only in the first part of a multi-part posting. Often, the description is taken from the documentation included with the software. Following the description, if any, is a UNIX `shar' file containing the actual software. See the section on `How to Use the Postings' for information on unpacking `shar' files. In the interests of making automatic archival easy, there are some simple rules to some of the header lines: + The From: line lists the email address of the moderator, not the address of the person who submitted the software. That address can be found in both the `Reply-To' header line, or in the `Submitted-By' auxiliary header line. + The subject line is formatted thus: Subject: volish: name [version] - description, partxx/yy Where volish is the volume and issue number, name is a one word name for the piece of software, optionally followed by a version number. After the hyphen is a one-line description or title for the software, followed by this article's part number (xx), and the total number of parts for this package (yy). While the format of the Subject line is relatively consistent, the auxiliary headers `Posting-name' and `Archive-name' and the primary header `Newsgroup' should instead be used to generate file names for archiving. + The Reply-To line contains the email address of the person submitting the software package. This line is present to deflect inquiries about the package to the person who submitted it, rather than the moderator. + The first newsgroup listed in the Newsgroup line is the `primary' newsgroup the posting belongs to. Occasionally, a posting will be crossposted to other (often discussion) groups. In the case of a cross posted article, only the first newsgroup should be used for archiving. In the secondary header, there is: + The Submitted-By line, like the `Reply-To' line, contains the email address of the person who submitted the software package. This line is intended for use by archival software, though I haven't found one that uses it... + The Posting-number line contains the volume and issue number of this posting. Each posting contains a unique volume and issue number. + The Archive-name line contains the path name that should be used by an archive site when archiving this article. The pathname always ends with the part number (though that wasn't always the case in earlier postings), and care is taken to limit component names to 14 characters for archive sites with obsolescent filesystems. -------- Subject: Credits... Tad Guy - The original author of this informational posting Michael Dinn - The previous moderator who modified this article slightly. -- Bill Zimmer - zim@ibx.com