Frozen Fish 1: Amiga

home *** CD-ROM | disk | FTP | other *** search

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / readme < prev next >

Wrap

Text File | 1994-04-07 | 24.7 KB | 530 lines

BBS/FTP README (Updated 4/7/94) -------- OVERVIEW -------- This is the root directory of a file tree containing over 6000 archives, mostly lha archives, but also including a few gzip compressed tar archives. See the other informational files on this CD-ROM for details about what is contained in these archives. This file deals purely with details about how this CD-ROM might be used in a BBS or FTP environment. Some of the details discussed here include: o How do I unpack all these *.lha archives. o What are all these *.pi (product info) files and why they are important. o Some history behind why the CD-ROM is organized as it is, and the tradeoffs that went in to deciding on a particular organi- zation. o How you can arrange to access the contents of the CD-ROM from several different "views" using symbolic links, and what support is provided to make this relatively easy to set up. o The default alternative "view". ------------ LHA ARCHIVES ------------ Almost all the archives on this CD-ROM are in "lha format". The shareware version of lha is included in the :c directory of this CD-ROM, so all you have to do to unpack any archive is use a command of the form: lha -mraxe x archive.lha Please consider registering with the lha author, Stefan Boberg, for the latest version of lha, so he can continue to support this fine program. ------------------ PRODUCT INFO FILES ------------------ If you have already peeked in some of the directories of this CD-ROM, you probably noticed that for every archive there is a corresponding file of the same name with ".pi" appended to the name. These are "product info" files, and contain important information about the contents of the archive that they correspond to. The current specification for the structure and contents of these files can be found in the "Product-Infos" file in the "Information" directory on this CD-ROM, and should continue to be posted periodically in the usenet news group "comp.sys.amiga.announce" as it evolves. The product info files are a way to organize lots of information about a program in an extensible text format that is relatively simple for programs to parse. It looks something like: .name myprog .fullname My smart little program .version 1.4 .short Computes winning horse, 100% accurate. .author Me .address 123 Somestreet Anywhere, USA Aside from the information about where to find an archive (implied by the location of the corresponding product info file), two other very important pieces of information that are included in these product info files are the version number (if known) and a 40 character or less short description of what is contained in each archive. When used in a BBS or FTP environment the pieces of information that are usually desirable to have include: o Name of the archive. o Location of the archive (where BBS software can find archive) o Version number of the material in the archive. o Size of the archive. o Date of release of the material in the archive. A common way of making this information available to the BBS sysop, and ultimately the BBS software, is to build a "files.bbs" file in each directory where the files are found, or possibly in a separate directory, depending upon the BBS software. These files are typically fixed field width files with one line per archive, and look something like: foo1.4.lha 103200 04-Jan-94 Do the dishes, watch TV bar34.lha 33567 11-Mar-94 Take out the trash, eat dinner One major problem is that no two BBS systems seem to agree on the exact format of this file, and from what information I've been able to obtain, generally have rigid requirements for exactly where each field must be and how big it must be. Rather than attempt to include direct support for one or more different BBS systems, in a variety of different formats, I've elected to provide some simple tools that BBS operators can use to build their own information files in whatever format the BBS requires. This is where the product info files come in. The directory "PItools" contains several small tools for manipulating product info files. The most important of these is "pitool", which can walk the entire directory tree of the CD-ROM and perform a number of different operations on the product info files that it finds. One thing it can do is to print a one line entry to it's standard output stream for each product info file that it processes, and format this field according to a specifier string that looks a lot like a typical C "printf" style string. The following example prints the file's "basename" in a left justified 24 character wide field, followed by a space, followed by the contents of the ".short" field in a left justified 40 character wide field, and finally, a newline character: pitool -b -F "%-24B %-40S\n" -f - /FrozenFish-Apr94/BBS/ALib/d9xx/d950 BBDoors.lha rexxDoors for BBBBS, V6.5 BusyPointers.lha 'NickPrefs' busy pointers collection. ClockTool.lha Manipulate battery and/or system clocks Enforcer.lha Tool to monitor illegal memory access. PayAdvice.lha Pay analysis program. Sushi.lha Intercept Enforcer raw serial output. bbsQUICK.lha bbsQUICK offline module for BBBBS, V6.4 Disk950.lha Library admin files for disk 950. This example prints the file "basename" in a right justified 24 character wide field, followed by a space, followed by the complete pathname to that file in a field of unlimited length, and then a newline character: pitool -b -F "%24B %P\n" -f - /cdrom/BBS/ALib/d9xx/d950 BBDoors.lha cdrom:BBS/ALib/d9xx/d950/BBDoors.lha BusyPointers.lha cdrom:BBS/ALib/d9xx/d950/BusyPointers.lha ClockTool.lha cdrom:BBS/ALib/d9xx/d950/ClockTool.lha Enforcer.lha cdrom:BBS/ALib/d9xx/d950/Enforcer.lha PayAdvice.lha cdrom:BBS/ALib/d9xx/d950/PayAdvice.lha Sushi.lha cdrom:BBS/ALib/d9xx/d950/Sushi.lha bbsQUICK.lha cdrom:BBS/ALib/d9xx/d950/bbsQUICK.lha Disk950.lha cdrom:BBS/ALib/d9xx/d950/Disk950.lha This example prints the file "basename" in a left justfied 20 character wide field, followed by a space, the version number in a right justified 6 character wide field, followed by another space, the size of the archive in Kb in a 3 character wide right justified field, followed immediately by the literal string "Kb => ", followed by the directory in which the file is stored in a field of unlimited length, followed by a newline: pitool -b -F "%-20B %6V %3KKb => %D\n" -f - /cdrom/BBS/ALib/d9xx/d950 BBDoors.lha 6.5 187Kb => cdrom:BBS/ALib/d9xx/d950/ BusyPointers.lha ?.? 11Kb => cdrom:BBS/ALib/d9xx/d950/ ClockTool.lha 1.0 26Kb => cdrom:BBS/ALib/d9xx/d950/ Enforcer.lha 37.55 66Kb => cdrom:BBS/ALib/d9xx/d950/ PayAdvice.lha 3.00 52Kb => cdrom:BBS/ALib/d9xx/d950/ Sushi.lha 37.10 14Kb => cdrom:BBS/ALib/d9xx/d950/ bbsQUICK.lha 6.4 26Kb => cdrom:BBS/ALib/d9xx/d950/ Disk950.lha ?.? 23Kb => cdrom:BBS/ALib/d9xx/d950/ The source to this utility is provided in case any further customizations are needed, however it is currently only compiled and tested with the GNU compiler (also included on this CD-ROM in BBS/GNU). ------------------- CD-ROM ORGANIZATION ------------------- A couple months prior to creating this CD-ROM I posted various notes asking for feedback on how people would like to see the BBS and FTP sections of my CD-ROM's organized. I got less feedback than I had hoped for, but what I did get was quite useful. There seems to be two very distinct "camps" of people, with conflicting desires for how the material should be organized. One group of people wants to see the floppy disk structure preserved for that portion of the material that comes from the floppy disk library, and have that structure reflected in the organization of the material on the CD-ROM. If they know the disk number that a particular program appears on, they want to quickly and easily locate the appropriate directory containing the material. Within that directory they expect to find either one archive containing the entire contents of that floppy disk, or several archives with each containing one submission included on that floppy disk. Usually these people expect to be owners of the CD-ROM and copy the material directly off the CD-ROM to a hard drive, or they expect to access the material via internet and ftp it from a site that has the CD-ROM mounted. Also in this camp are people that want to be able to quickly find all the parts that go into making up a particular floppy disk so that they can recreate a given floppy for further distribution. The other group of people wants to see the material organized along functional lines (games, demos, graphics, programming tools, etc), and don't really care too much about preserving the floppy structure. They want a minimal directory structure (10-25 directories or so), with no more than a few hundred files in each directory. Generally these people are BBS owners that want to make the CD-ROM contents available to the general public via their BBS. They need additional support in the form of "files.bbs" type files, or some other way to get information about the CD-ROM contents into a form that their BBS can use. For recording the CD-ROM, I decided upon was a structure that preserves the original organization of the material, using a fairly shallow directory tree with short names. This should satisfy the needs of most owners of the CD-ROM and people that access the contents via ftp where they can directly browse the structure and get specific files as they are found. As an example, consider the location of material from floppy disk 504: BBS - root directory of BBS/FTP material BBS/ALib - root directory of disks 1-975 BBS/ALib/d5xx - floppy disks 500-599 BBS/ALib/d5xx/d504 - floppy disk 504 BBS/ALib/d5xx/d504/Disk504.crc - CRC list for all files on disk 504 BBS/ALib/d5xx/d504/Disk504.lha - Archive of disk "overhead files" BBS/ALib/d5xx/d504/View.lha - Archive of the "View" submission BBS/ALib/d5xx/d504/ViewDir.lha - Archive of the "ViewDir" submission . . . Note that all the files relevant to disk 504 can be found in the single directory "BBS/ALib/d5xx/d504". To reconstruct disk 504, all that is needed is to format a floppy and unarchive all of the archives that are found in the d504 directory in the root directory of the floppy. The brik program can be used afterwards, with the Disk504.crc file as input, to verify that all the files that are expected to be on the floppy are in the correct location and have the correct contents. The program "PufferFish", found elsewhere on this CD-ROM, will do all of this for you, for any disk or range of disks, with a few clicks of the mouse. -------------------- USING SYMBOLIC LINKS -------------------- In order to satisfy the diverse needs of people that want to see the CD-ROM organized on something other than the traditional disk format, I have included some tools and scripts that will allow the contents of the CD-ROM to be presented with any arbitrary organization, by using the "symbolic link" feature built into Kickstart 2.04 or later. The same techniques will also work for people that want to access this CD-ROM on Unix systems that support symbolic links. == DISCLAIMER == Symbolic links are a new feature in AmigaDOS, and have probably not had a lot of testing, as is evident from the fact that most of the currently available standard Commodore utilities don't fully support them. If you munge your hard drive, create files that are hard to delete, create file trees that cause your backup utility to choke, or otherwise scramble your disks, I am NOT RESPONSIBLE. I strongly suggest that you first experiment with these techniques in a separate scratch partition that can simply be reformatted if something goes wrong. Basically, a symbolic link is a file that contains the name of another file, where the actual file contents are to be found. For example, the notation: file1 -> file2 means that "file1" is a symbolic link containing the string "file2", and the actual file contents are in "file2". When the system opens "file1", it arranges that any attempt to read/write "file1" actually reads/writes "file2". The useful feature of symbolic links is that "file1" can be a file on either your hard drive or a floppy disk, and "file2" can be a file on the CD-ROM. Since you are able to create a directory tree of links using any organization you like, you can effectively reorganize the contents of the CD-ROM without actually changing it in any way. You are simply changing your effective view of it. You can have as many effective views as you want simultaneously by simply having several different trees of symbolic links. New alternative views can be added at any time. Plus your view can even include multiple CD-ROM's or random files that are stored in some other part of your system. So when an update is released to some program on the CD-ROM, it can be added right alongside the older material that is included on the CD-ROM by simply adding another link. Nobody but the BBS sysop has to know where the actual material is stored. --------------------------- EXAMPLE WITH SYMBOLIC LINKS --------------------------- Don't be discouraged by the gory details of this example, since the CD-ROM comes with an archive containing a script and "files.bbs" files that can be used to set up a default view which divides the CD-ROM up into 25 different areas, with 100-700 files in each area. So you shouldn't have to get down to this level unless you want a more custom setup. As a concrete example, let's assume that we want to create a directory "sys:bbs/filereaders" that will have all of the text readers that have ever appeared in the floppy library, and then make the contents of this directory accessible via the BBS. We could of course simply copy each of the relevant archives off the CD-ROM into sys:bbs/filereaders, but then this defeats most of the advantages of having a CD-ROM in the first place, other than as a distribution medium. We will limit our example to one single text reading program, "MuchMore". By using "pitool" with the right format as shown below, we can get a list of the complete pathnames to all files on the CD-ROM for which there is a product info file, and what their version numbers are. Then using "grep" on this list, we can select only those files we are interested in: cd sys:bbs/filereaders pitool -b -f - -F "%P %V\n" >junkfile /FrozenFish-Apr94/BBS/ALib grep "MuchMore\.lha" junkfile >muchmorefiles cat muchmorefiles FrozenFish-Apr94:BBS/ALib/d2xx/d234/MuchMore.lha 1.8 FrozenFish-Apr94:BBS/ALib/d2xx/d253/MuchMore.lha 2.5 FrozenFish-Apr94:BBS/ALib/d3xx/d378/MuchMore.lha 2.7 FrozenFish-Apr94:BBS/ALib/d5xx/d560/MuchMore.lha 3.0 FrozenFish-Apr94:BBS/ALib/d8xx/d895/MuchMore.lha 3.3 FrozenFish-Apr94:BBS/ALib/d9xx/d935/MuchMore.lha 3.6 FrozenFish-Apr94:BBS/ALib/d9xx/d962/MuchMore.lha 4.2 We now know what the name of each archive is (the last component in the pathname), where it is stored, and what version number it is. The next step is to generate symbolic links in the current directory that point to each file on the CD-ROM. I have provided a simple program that does this, called "symlinks". The symlinks program takes as input a file containing lines in the above format, and makes links in either the current directory or a directory that has the same name as the first character of the name of the archive ('m' in this case). Because all the archives have the same name, the symlinks program arranges for each link to have a unique name by included either the version number or the floppy disk number in the name of the archive. Since the version numbers are known for all the files in this example, the version numbers are given preference. The symlinks program can either make the links directly, or emit a script that can be run, possibly after some "hand tweaking", to generate the links: symlinks -s <muchmorefiles >execute.me cat execute.me ln -s FrozenFish-Apr94:BBS/ALib/d2xx/d234/MuchMore.lha MuchMore-1.8.lha ln -s FrozenFish-Apr94:BBS/ALib/d2xx/d234/MuchMore.lha.pi MuchMore-1.8.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d2xx/d253/MuchMore.lha MuchMore-2.5.lha ln -s FrozenFish-Apr94:BBS/ALib/d2xx/d253/MuchMore.lha.pi MuchMore-2.5.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d3xx/d378/MuchMore.lha MuchMore-2.7.lha ln -s FrozenFish-Apr94:BBS/ALib/d3xx/d378/MuchMore.lha.pi MuchMore-2.7.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d5xx/d560/MuchMore.lha MuchMore-3.0.lha ln -s FrozenFish-Apr94:BBS/ALib/d5xx/d560/MuchMore.lha.pi MuchMore-3.0.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d8xx/d895/MuchMore.lha MuchMore-3.3.lha ln -s FrozenFish-Apr94:BBS/ALib/d8xx/d895/MuchMore.lha.pi MuchMore-3.3.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d9xx/d935/MuchMore.lha MuchMore-3.6.lha ln -s FrozenFish-Apr94:BBS/ALib/d9xx/d935/MuchMore.lha.pi MuchMore-3.6.lha.pi ln -s FrozenFish-Apr94:BBS/ALib/d9xx/d962/MuchMore.lha MuchMore-4.2.lha ln -s FrozenFish-Apr94:BBS/ALib/d9xx/d962/MuchMore.lha.pi MuchMore-4.2.lha.pi Note that this program also arranges for the product info file to be linked as well. This is so "pitool" can be used later to automatically build appropriate description files when run on the tree of symbolic links. After that is done, the links to the product info files can be deleted if desired. After executing the above script, doing an "ls -l" on the directory reveals the symbolic links (output edited to make it more clear and to fit on 80 char line): ls -l MuchMore-1.8.lha -> FrozenFish-Apr94:BBS/ALib/d2xx/d234/MuchMore.lha MuchMore-1.8.lha.pi -> FrozenFish-Apr94:BBS/ALib/d2xx/d234/MuchMore.lha.pi MuchMore-2.5.lha -> FrozenFish-Apr94:BBS/ALib/d2xx/d253/MuchMore.lha MuchMore-2.5.lha.pi -> FrozenFish-Apr94:BBS/ALib/d2xx/d253/MuchMore.lha.pi MuchMore-2.7.lha -> FrozenFish-Apr94:BBS/ALib/d3xx/d378/MuchMore.lha MuchMore-2.7.lha.pi -> FrozenFish-Apr94:BBS/ALib/d3xx/d378/MuchMore.lha.pi MuchMore-3.0.lha -> FrozenFish-Apr94:BBS/ALib/d5xx/d560/MuchMore.lha MuchMore-3.0.lha.pi -> FrozenFish-Apr94:BBS/ALib/d5xx/d560/MuchMore.lha.pi MuchMore-3.3.lha -> FrozenFish-Apr94:BBS/ALib/d8xx/d895/MuchMore.lha MuchMore-3.3.lha.pi -> FrozenFish-Apr94:BBS/ALib/d8xx/d895/MuchMore.lha.pi MuchMore-3.6.lha -> FrozenFish-Apr94:BBS/ALib/d9xx/d935/MuchMore.lha MuchMore-3.6.lha.pi -> FrozenFish-Apr94:BBS/ALib/d9xx/d935/MuchMore.lha.pi MuchMore-4.2.lha -> FrozenFish-Apr94:BBS/ALib/d9xx/d962/MuchMore.lha MuchMore-4.2.lha.pi -> FrozenFish-Apr94:BBS/ALib/d9xx/d962/MuchMore.lha.pi Note that if you use the standard Commodore commands (dir or list), these files may appear to be directories rather than links or regular files. This is a deficiency in the Commodore utilities that will hopefully be fixed in a future release. For now I recommend doing maintenance on symbolic links by using the GNU utilities "ls", "rm", and "ln", that handle symbolic links exactly as their UNIX counterparts. These can all be found in the ":C" directory on this CD-ROM, and in the archives that are included in the BBS/GNU directory, if you find you are missing something. See the notes further down in this document about ixemul.library and needing to use a larger stack value than you might normally be used to. If we run pitool now in this directory (or in a tree of such directories), we can generate "files.bbs" files in each directory: cd sys:bbs/textreaders pitool -b -F "%-24B %3KK %S\n" . <---- note trailing '.' cat files.bbs MuchMore-1.8.lha 36K Nice text viewer, like "more" or "less". MuchMore-2.5.lha 53K Very nice text display program. MuchMore-2.7.lha 42K Nice text displayer, like "more"/"less". MuchMore-3.0.lha 43K Program like "more", "less", "pg", etc. MuchMore-3.3.lha 61K Program like "more", "less", "pg", etc. MuchMore-3.6.lha 64K Program like "more", "less", "pg", etc. MuchMore-4.2.lha 86K Soft scroll text viewer with xpk-support Also note that the -f option can be used to specify the name of the "files.bbs" type file. This is useful to support multiple different kinds of information files (generated by different -F strings), or to force the name to match what your BBS system expects. At this point, we should simply be able to add sys:bbs/textreaders as a new file area, and have the BBS pick up the file descriptions from the files.bbs file that was built. Accesses to the files in that area will follow the symbolic link to the actual file on the CD-ROM. One caution though, many tools don't work properly on symbolic links. One of those tools is lha version 1.38, the apparently last shareware freely distributable version of lha. It is entirely possible that whatever BBS system you are using may choke on links as well. If so, you should ask the vendor of your BBS to support links, since I think this technique is quite powerful, and will become more important as time goes on and CD-ROM's get more and more common. ------------------------ DEFAULT ALTERNATIVE VIEW ------------------------ The directory BBS/Support contains at least one default view as "view1.lha". This archive contains a script called "view1.script", and an archive of files.bbs files called "view1desc.lha". When the script is executed, it creates a subtree of directories in the current directory, with one directory for each letter of the alphabet, and then creates symbolic links in each of those directories to files on the CD-ROM that start with that letter. The link names incorporate the version number of the material or the disk number, as described above. If this still isn't sufficient to make the names unique, an additional differentiator string is added to the file basename. I.E. M/MuchMore-1.8.lha M/MuchMore-1.8-a.lha M/MuchMore-1.8-b.lha This can happen when there are more than one copy of the same version of the material on the same CD-ROM (such as included both in the floppy library and in the "Useful" tree). After building the directory tree and populating it with symbolic links, the view1.script file unarchives "view1desc.lha" to populate each directory with default "files.bbs" files. Doing a "wc -l #?/files.bbs" on the current version of these files shows the statistics of what directories are present and how many archive files are in each. Note that the complete GNU distribution is placed in it's own private directory: 127 GNU/files.bbs 435 a/files.bbs 237 b/files.bbs 379 c/files.bbs 1342 d/files.bbs 121 e/files.bbs 240 f/files.bbs 112 g/files.bbs 122 h/files.bbs 182 i/files.bbs 49 j/files.bbs 66 k/files.bbs 177 l/files.bbs 461 m/files.bbs 124 n/files.bbs 50 o/files.bbs 420 p/files.bbs 38 q/files.bbs 194 r/files.bbs 529 s/files.bbs 282 t/files.bbs 78 u/files.bbs 134 v/files.bbs 121 w/files.bbs 54 x/files.bbs 23 y/files.bbs 31 z/files.bbs 6128 total It is hoped that additional views will become available fairly quickly, including one that is structured along more functional lines, like "games/", "pictures/", "compilers/", etc. As more information is added to the product info files (all 6000+ of them!), generating these views will be an almost trivial operation. ---------------------------- GZIP COMPRESSED TAR ARCHIVES ---------------------------- A few archives here are in what is known as "compressed tar archive" format. These are archives that are made with "tar" and then compressed with the "gzip" compressor. Generally they are the original unchanged archives for GNU distributions, exactly as released by the Free Software Foundation. To unpack them, you can do: gzip -d foo.tar.gz tar -xvf foo.tar or if you have a shell that supports pipes, you can avoid making the uncompressed tar archive (which might be quite large), and simply do: gzip -d <foo.tar.gz | tar -xvf - Both gzip and tar are included in the ":C" directory on this CD-ROM. -------------- IXEMUL.LIBRARY -------------- All of the utilities described here are compiled with GNU gcc, and require the ixemul.library to be found in the LIBS: directory. The "Setup" script in the root directory of this CD-ROM can arrange for this CD-ROM's ":C" and ":LIBS" directories to be added to your C: and LIBS: assign paths respectively, so you don't have to actually copy anything off the CD-ROM to run the tools. Be sure to set your stack size to a fairly large value, say 50,000 or more, before running any of the tools. -Fred ><>