v97INF6: Introduction to comp.binaries/sources.amiga, Part 01/01
Bill Zimmer - Moderator
Submitted-by: z...@ibx.com (Bill Zimmer)
Posting-number: Volume 97, Issue INF6
Archive-name: administrivia/intro6/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 (grwa...@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!
(This also includes 'testing' messages. Rather than send a 'test'
message, why not send something appropriate for posting?)
Such messages will be deleted from the software queue, without
indication (though you may receive an acknowledgement when the
posting is received).
--------
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:
am...@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 BIT...@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 ftp...@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-...@abcfd20.larc.nasa.gov (Amiga Sources/Binaries Moderator)
| Subject: v90i374: lome 1.1 - line oriented macro processor, Part01/03
| Reply-To: Darren New <n...@ee.udel.edu>
| Newsgroups: comp.binaries.amiga
|
| Submitted-by: Darren New <n...@ee.udel.edu>
| 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 - z...@ibx.com