home *** CD-ROM | disk | FTP | other *** search
/ RBBS in a Box Volume 1 #3.1 / RBBSIABOX31.cdr / swal / std1212.doc < prev    next >
Encoding:
Text File  |  1985-01-15  |  10.1 KB  |  284 lines
  1.                                                                   Page 1 of 5
  2.  
  3.  
  4.  
  5.  
  6.                             STD41212.DOC
  7.                        BBS Standards Document
  8.                     VERSION 1.00, RELEASE 841212
  9.                             by:  J. Gold
  10. <Your BBS name here>
  11.  
  12.  
  13.  
  14.  
  15.                     DOCUMENTATION TOPICS
  16.  
  17.                     0.0  Preface
  18.                     1.0  Introduction
  19.                     2.0  For New Users
  20.                     3.0  THE PROBLEM
  21.                     4.0  THE SOLUTION
  22.                     4.1  Suggestions for Uploaders
  23.                     4.2  Suggestions for SYSOPs
  24.                     5.0  Acknowledgements
  25.  
  26.              Appendix A  Library Documentation
  27.                     A.1  ABSTRACT.DOC
  28.                     A.2  BUILD.BAT
  29.  
  30.  
  31.  
  32.  
  33.  
  34. 0.0  Preface
  35.  
  36.      This is the initial release of a document which is an attempt to 
  37. standardize the storage of files on Bulletin Board Systems (BBS). The 
  38. suggestions embodied herein are open to comment and revision in the 
  39. future.  It is hoped that some community wide standard will result.
  40.  
  41.  
  42.  
  43.  
  44. 1.0  Introduction
  45.  
  46.      Recently, on BBS it has become common to pack files for 
  47. downloading in two ways:
  48.  
  49. 1. in a library, which merges several related files in one large file.
  50.  
  51. 2. in a squeezed or squished format, which compresses the size of a file
  52.    from 5 to 50 %.
  53.  
  54.                                                                   Page 2 of 5
  55. 2.0  For New Users
  56.  
  57. If this is the first time you are accessing a BBS, the talk of file 
  58. transfer protocols, XMODEM, squeezing, and libraries may all seem a
  59. bit confusing.  Simply put, there is a lot of great *FREE* software
  60. available out there.  However, first you need a way to move it from
  61. the BBS to your PC.  To do this, you must use a file-transfer pack-
  62. age. Unfortunately, to get some of the better file-transfer programs
  63. you already need a file-transfer program.
  64.  
  65. Since most files stored on a BBS are in binary format,  not in ASCII
  66. format, you need one of the better file-transfer programs which will
  67. support a binary transfer PROTOCOL.  The most popular micro-to-micro
  68. protocol is called XMODEM.  The BBS will probably indicate where you
  69. can find one of these programs.   Hopefully,  it is in ASCII format,
  70. since that is how you will transfer it.  Once you have this program,
  71. you can transfer (download) files using the XMODEM protocol.
  72.  
  73. The next step is to be able to "unpack" files which are kept in some
  74. special packed format.  Again hopefully, the BBS will indicate which
  75. are the best unpacking programs to use.   You  may  ask,  why bother
  76. "packing" files.  Well, read on.
  77.  
  78.  
  79.  
  80.  
  81. 3.0  The Problem
  82.  
  83. The advantages of squeezing include:
  84.  
  85.         o reduced transmission time
  86.  
  87.         o reduction of storage requirements on the BBS
  88.  
  89. The advantages of libraries include:
  90.  
  91.         o reduced operator / user intervention, ie. you only
  92.           need to upload/download one file and not wait by
  93.           the terminal to enter the next command when the
  94.           previous one completes.
  95.  
  96.         o All necessary files for an application are together.
  97.           So one "essential" module does not get "lost" between
  98.           download from one system to upload to the next.
  99.  
  100.         o A downloader does not have to first get a documentation
  101.           file, and then "search" through a BBS directory to get
  102.           all related files.
  103.  
  104. The disadvantage of both packing techniques is:
  105.  
  106.                 INCOMPATIBILITY ! !
  107.  
  108. There are a multiplicity of versions of these two popular programs.
  109. A user may find that he cannot unsqueeze the documentation file of
  110. a program he has spent 30 minutes to download because he is using
  111. a version of UNSQUEEZE incompatible with the version of SQUEEZE
  112. originally used to pack the file.
  113.  
  114.                                                                   Page 3 of 5
  115. 4.0  The Solution
  116.  
  117. Since new variations of packing and unpacking utilities will continue 
  118. to spread it is hard to standardize one definition. Therefore, it is
  119. essential that uploaders and  SYSOPs make sure that downloaders know
  120. how to unpack files.
  121.  
  122.  
  123.  
  124.  
  125. 4.1  Suggestions for Uploaders
  126.  
  127. The widest distribution of software requires that downloaders be able
  128. to unpack the software that you upload.  SYSOPs often do not have the
  129. time to check every program, so the burden rests on you.
  130.  
  131.         o Upload all utilities, programs,  etc.  consisting of more 
  132.           than one file in squeezed library format.
  133.  
  134.         o Don't bother squeezing individual files. Instead, squeeze 
  135.           the entire library.
  136.  
  137.         o Make  sure  the  BBS  you  upload to has the utilities to 
  138.           unpack your library, squeezed file, or squeezed-library.
  139.  
  140.         o Include an ABSTRACT.DOC  and other  documentation  files, 
  141.           described in appendix A.
  142.  
  143.         o Upload the ABSTRACT.DOC file:  first,  seperately, and in 
  144.           unsqueezed format.
  145.  
  146.  
  147.  
  148.  
  149. 4.2  Suggestions for SYSOPs
  150.  
  151. o Indicate  you  preference  for-or-against  squeezed-libraries.  If for,
  152.   which versions of squeeze,  unsqueeze and the librarian should be used.
  153.   Display a message prominently in some combination of: a bulletin,   the
  154.   welcome message, the heading of the upload directory.
  155.  
  156. o Keep this file or a similar one on your system.
  157.  
  158. o When time permits,  go through  all  squeezed and library files on your
  159.   system.  Make  sure  that  they  can be unpacked by the versions of the
  160.   librarian and unsqueeze utilities that you have told downloaders to use.
  161.  
  162. o When time permits,  purge  old versions of utilities, especially if the
  163.   newer versions are downward compatible.   If incompatible, keep the old
  164.   versions around, but indicate that they should not be used.
  165.  
  166. o Provide an  explanation  of how to acquire a file-transfer program with
  167.   the XMODEM protocol.  Keep a copy of this program and its documentation
  168.   available for downloading in  ASCII  format.
  169.  
  170.                                                                   Page 4 of 5
  171. 4.3  Size Restrictions
  172.  
  173. Also known as "Remember the poor user with a 160KB disk drive".
  174. If you ever wonder why many software houses distribute software
  175. on single-sided, 8 sector/track diskettes, this is it.  So, here
  176. are some suggested guidelines for file sizes:
  177.  
  178.      o in general:
  179.             40KB TO 80KB
  180.  
  181.      o for programs which can run under DOS 1.x:
  182.             160KB = maximum size of UNSQUEEZED file or library
  183.  
  184.      o for programs which only run under DOS 2.x:
  185.             360KB = maximum size of UNSQUEEZED file or library
  186.  
  187.  
  188.  
  189. 5.0  Acknowledgements
  190.  
  191.      (The following paragraph is excerpted
  192.       from NUSQ104.DOC by Cliff Sharp.)
  193.  
  194. The  first file squeezer  and  unsqueezer  in  the public  domain 
  195. were  written  by  Richard  Greenlaw,    in  the   C  programming
  196. language.   A  Z80  assembly  language  version  was done by Gail
  197. Zacharias  at MIT in the Spring of 1983.   In late '83 Dave  Rand
  198. wrote  an  8080  version,  which went through  several  versions,
  199. culminating  in USQ120.COM.   Paul Homchick assumed the  task  of
  200. converting  Dave's  efforts  to 8086/8088 assembly  language  for
  201. execution under CP/M-86 in early 1984,  and Cliff Sharp converted 
  202. Paul's version to run under MS-DOS a bit later.
  203.  
  204.      (The following two paragraphs are excerpted
  205.       from LU86401.DOC by Paul J. Homchick)
  206.  
  207. Gary Novosielski designed the LU format and wrote the  first 
  208. programs  supporting  'LBR'  files.   He  has  continued  to 
  209. maintain and improve the LU format by distributing a file of 
  210. the offical LU format definition.  The  current  version  of 
  211. this definition is contained in LUDEF5.DOC. Interested users 
  212. are directed to that file for  more  complete information on 
  213. the LU format.
  214.  
  215. This program [LU]  had its genesis in the UNIX progam LAR.C.
  216. LAR  was  rendered  into  C  that  mortal  compilers   could
  217. understand by Tom Jennings who renamed the source to LU.C.
  218.  
  219.                      (End of excerpts)
  220.  
  221. CP/M and CP/M-86 are trademarks of Digital Research, Inc.
  222. MS (as in MS-DOS) is a trademark of Microsoft, Inc.
  223.  
  224.                                                                   Page 5 of 5
  225. Appendix A: Library documentation
  226.  
  227. Each library should include information on the function of each module 
  228. in that library, the version number of programs, release dates, and
  229. instructions on how to unpack individual modules.
  230.  
  231.  
  232. A.1  ABSTRACT.DOC
  233.  
  234. This file gives a SHORT abstract of all information needed to unpack
  235. and use the library.  It will direct you to other documentation.  It
  236. should contain:
  237.  
  238.         o a SHORT description of the functionallity provided.
  239.           Save the full description for the README.1ST file.
  240.         o the current VERSION number (ie: 1.00)
  241.         o what, if anything, is being superceeded.
  242.         o the author's name (ya want credit don't ya?)
  243.         o a one line description of each module in the library
  244.         o the current RELEASE of each module (format: YYMMDD)
  245.         o which version of squeeze and the librarian was used
  246.           to pack the squeezed-library.
  247.  
  248. If the name of your squeezed-library is  ABCDEFG.LQR, then the 
  249. name of your ABSTRACT.DOC file should be ABCDEFG.DOC. It should
  250. be the 1st file in the library.
  251.  
  252. When uploading your squeezed-library, upload your ABSTRACT.DOC file:
  253.  
  254.         o SEPERATELY
  255.         o FIRST
  256.         o UN-SQUEEZED
  257.  
  258.  
  259.  
  260. A.2  README.1ST
  261.  
  262. This file should contain a fuller description of the  functionallity
  263. provided by the library.   It is the first file which should be read
  264. by the downloader.  It may include references to other documentation
  265. files.
  266.  
  267.  
  268.  
  269. A.3  BUILD.BAT (optional)
  270.  
  271. This file should contain all the files necessary to rebuild the library
  272. from its component modules.   This  file is important if you distribute
  273. your library with the intention of having it updated and re-distributed
  274. by other users.
  275.  
  276.  
  277. A.4  INSTALL.BAT (optional)
  278.  
  279. This file should contain all necessary commands to split-up the library
  280. and perform any special installation procedures.  This is helpful if
  281. there is a complex installation procedure.
  282.  
  283. -- END -- STD.DOC --
  284.