home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / JRCPP.ZIP / README.DOC < prev    next >
Text File  |  1990-03-27  |  11KB  |  245 lines
  1.                      JRCPP README FILE (3/27/90)
  2.                 James Roskind C Porting Preprocessor
  3.                      (Full ANSI C Preprocessor)
  4.  
  5.  
  6.  
  7.     Copyright (C) 1990 James Roskind, All rights reserved. Permission 
  8.     is  granted  to copy and distribute this file as part any machine 
  9.     readable archive containing the entire, unmodified, JRCPP  PUBLIC 
  10.     DISTRIBUTION PACKAGE (henceforth call the "Package").  The set of 
  11.     files that form the Package are described in the README file that 
  12.     is  a  part  of the Package.  Permission is granted to individual 
  13.     users of the Package to copy individual portions of  the  Package 
  14.     (i.e.,  component  files) in any form (e.g.: printed, electronic, 
  15.     electro-optical, etc.) desired  for  the  purpose  of  supporting 
  16.     users   of  the  Package  (i.e.,  providing  online,  or  onshelf 
  17.     documentation access; executing the  binary  JRCPP  code,  etc.).  
  18.     Permission  is  not  granted  to  distribute copies of individual 
  19.     portions of the Package, unless a machine readable version of the 
  20.     complete  Package  is also made available with such distribution. 
  21.     Abstracting with credit is permitted.   There  is  no  charge  or 
  22.     royalty  fee  required  for  copies  made in compliance with this 
  23.     notice.  To otherwise copy  elements  of  this  package  requires 
  24.     prior permission in writing from James Roskind.
  25.  
  26.     James Roskind
  27.     516 Latania Palm Drive
  28.     Indialantic FL 32903
  29.  
  30.     End of copyright notice
  31.  
  32.  
  33. What  the  above  copyright  means  is  that  you are free to use and 
  34. distribute (or even sell) the entire set of files  in  this  Package, 
  35. but  you  can't split them up, and distribute them as separate files.  
  36. The notice also says that you  cannot  modify  the  copies  that  you 
  37. distribute, and this ESPECIALLY includes NOT REMOVING the any part of 
  38. the copyright notice in any file.  JRCPP  currently  implements  a  C 
  39. Preprocessor,  but  the  users  of  this Package do NOT surrender any 
  40. right of ownership or copyright to any source text that is  processed 
  41. by JRCPP, either before or after processing.  Similarly, there are no 
  42. royalty or fee requirements for using the post-preprocessed output of 
  43. JRCPP.  
  44.  
  45. This  Package is expected to be distributed by shareware and freeware 
  46. channels (including BBS sites), but the fees paid for  "distribution" 
  47. costs  are  strictly  exchanged  between  the  distributor,  and  the 
  48. recipient, and James Roskind makes no express or  implied  warranties 
  49. about  the  quality  or integrity of such indirectly acquired copies.  
  50. Distributors  and  users  may  obtain   the   Package   (the   Public 
  51. distribution form) directly from the author by following the ordering 
  52. procedures in the REGISTRATION file.
  53.  
  54.  
  55. DISCLAIMER:
  56.  
  57. JAMES ROSKIND PROVIDES THIS FILE "AS  IS"  WITHOUT  WARRANTY  OF  ANY 
  58. KIND,  EITHER  EXPRESS  OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE 
  59. IMPLIED WARRANTIES OF MERCHANTABILITY OR  FITNESS  FOR  A  PARTICULAR 
  60. PURPOSE.   THE  ENTIRE  RISK AS TO THE QUALITY AND PERFORMANCE OF THE 
  61. PROGRAM AND DOCUMENTATION IS WITH YOU.   Some  states  do  not  allow 
  62. disclaimer  of express or implied warranties in certain transactions, 
  63. therefore, this statement may not apply to you.
  64.  
  65.  
  66. UNIX is a registered trademark of AT&T Bell Laboratories.
  67. ---------------------------------------------------------------------
  68.  
  69.  
  70.  
  71.  
  72.                     JRCPP README FILE 
  73.         
  74.           James Roskind C Porting Preprocessor
  75.                 (Full ANSI C Preprocessor)
  76.  
  77.  
  78. TABLE OF CONTENTS
  79.  
  80.  
  81.     DEFINITION OF JRCPP PUBLIC DISTRIBUTION PACKAGE
  82.     WHY IS JRCPP USEFUL FOR DEVELOPERS?
  83.     WHAT IS THE DIFFERENCE BETWEEN JRCPP AND JRCPPCHK?
  84.     WHY IS ONLY JRCPPCHK DISTRIBUTED PUBLICLY?
  85.  
  86.  
  87.  
  88. DEFINITION OF JRCPP PUBLIC DISTRIBUTION PACKAGE
  89.  
  90.  
  91. This  is  the  main  README  file  for  JRCPP.   The   JRCPP   PUBLIC 
  92. DISTRIBUTION PACKAGE consists of the 8 files:
  93.  
  94.         README.DOC              This file
  95.         REGISTER.DOC            How to become a registered user
  96.         USERS.DOC               User's Reference Manual
  97.         LANGREF.DOC             Language Reference Manual
  98.         DIAGNOST.DOC            Diagnostics Reference Manual
  99.         REFGRAM.Y               Reference grammar for JRCPP
  100.         JRCPPCHK.EXE            Executable version of JRCPP 
  101.     
  102. The  above list constitutes the entire "Package", as described in the 
  103. copyright notices.  Users are invited to redistribute the above  list 
  104. of  files  as  a whole (typically in some compressed archive format).  
  105. This includes placing the set of files on a BBS, or  distribution  by 
  106. commercial or non-commercial means.
  107.  
  108.  
  109. WHY IS JRCPP USEFUL FOR DEVELOPERS?
  110.  
  111. Although  the  ANSI  C standard has been approved, very few compilers 
  112. are fully ANSI compliant (so far).  Worse than than, even fewer  have 
  113. ANSI  C  compliant  preprocessors  (but there seems universal acclaim 
  114. that support of all of the ANSI C standard  is  a  high  priority  on 
  115. every  compiler  vendor's  wish  list).  Rather than waiting for your 
  116. compiler to evolve to the generally more portable ANSI standards, you 
  117. can begin TODAY to use all the features of ANSI C preprocessing, with 
  118. the confidence that your code will  be  portable  through  tomorrow's 
  119. compilers.   One step in this process is to begin to use ANSI C macro 
  120. definitions and coding conventions.
  121.  
  122. With the  belief  that  ANSI  conformant  code  is  highly  desirable 
  123. (including  the  preprocessing macro definitions and expansions), the 
  124. next point to address  is  why  you  should  use  JRCPP.   First  and 
  125. foremost  it is available TODAY.  Second, as a shareware offering, it 
  126. provides exceptional price/performance ratios.  Finally, JRCPP offers 
  127. exceptional  performance  in a number of areas, independent of price.  
  128. The following list surveys these advantages.
  129.  
  130. The extensive diagnostic message set  (over  170  distinct  messages) 
  131. tends  to pinpoint causes and locations of errors in the preprocessor 
  132. phases of C translation.  Simple examples include:
  133.  
  134.     1)  Detecting  /*  within a comment.  This typically is caused by 
  135.     accidentally forgetting to terminate the  previous  comment,  and 
  136.     can (without such diagnostics) be VERY hard to locate.
  137.         
  138.     2)  Failure  to  close  a #if with a #endif is diagnosed with the 
  139.     line number corresponding to the #if (and  NOT  simply  with  the 
  140.     message "unexpected end of file").
  141.  
  142. There are very few static limits in JRCPP.  This tends to allow  very 
  143. complex  macro  expressions to be evaluated.  The only restriction is 
  144. available memory, and this is generally not a restriction under OS/2.
  145.  
  146. Full support of ANSI C  preprocessing  constructs  are  provided  (as 
  147. opposed  to  some  subset,  plus  some  excuse  by  the vendor of the 
  148. compiler.) Since the preprocessing of C source code is separable from 
  149. compilation  as  a  whole,  JRCPP  can  be  used  with any existing C 
  150. compiler as a "front end" preprocessor.
  151.  
  152. Extensively customizable features  provide  compatibility  with  most 
  153. existing  preprocessors,  and  hence provide a migration path towards 
  154. more portable ANSI C code.  Customization of  the  diagnostic  system 
  155. also supports the easy separation of "wheat from chaff" in diagnostic 
  156. listings.
  157.  
  158. For additional reasons, and details of the  above  reasons,  see  the 
  159. JRCPP USERS MANUAL.
  160.  
  161.  
  162.  
  163.  
  164. WHAT IS THE DIFFERENCE BETWEEN JRCPP AND JRCPPCHK?
  165.  
  166. A  registered user receives several versions of JRCPP.  These include 
  167. highly  optimized  versions,   target/platform   specific   versions, 
  168. versions  to  assist  in  providing  problem (bug) reports, etc.  All 
  169. versions are fully functional, but some provided superior  assurances 
  170. of  correctness,  while  others  provided  superior  execution  time.  
  171. JRCPPCHK is  a  version  that  provides  the  greatest  assurance  of 
  172. correctness  (it  has massive internal checking).  Assuming there are 
  173. no bugs in the implementation of JRCPP, and there are no bugs in  the 
  174. compilation  and  linking  (i.e.,  building) of JRCPP, then JRCPP and 
  175. JRCPPCHK  should  provide  identical  preprocessing  results   (i.e., 
  176. JRCPPCHK is NOT a crippled version of JRCPP).
  177.  
  178. As  noted, the version of JRCPP that is distributed with this Package 
  179. has several  distinctive  attributes.   These  restrictions  are  NOT 
  180. fundamental  to  the  product,  but  simply  allowed  for  the widest 
  181. distribution of a competent product.  See the REGISTER.DOC  file  for 
  182. details  of  other  versions.   The following are the restrictions on 
  183. JRCPPCHK:
  184.     
  185.     1)  It is a bound OS/2 and MSDOS executable.  Hence it should run 
  186.     under DOS 3.x and greater, as well as OS/2 1.1 and later.
  187.         
  188.     2) It was compiled for use on 80286, 80386, and 80486  platforms.  
  189.     It  may  not  run  on 8088 based platforms. (Registered users can 
  190.     obtain an 8088 based version).
  191.         
  192.     3)  It  contains  "assertions".  The assertions provide extensive 
  193.     internal error checking.  The presence of these assertions  slows 
  194.     execution by 33%, and increases the size of the executable's code 
  195.     by  20%.   These  assertions  also  tend  to  guarantee  reliable 
  196.     software despite the fact that this is a beta release!
  197.  
  198.     4)  When JRCPPCHK.EXE is executed, the banner displayed on stderr 
  199.     should include: "ASSERT checking is  active".   The  presence  of 
  200.     this  message  distinguishes  this executable from other versions 
  201.     that are supplied ONLY to registered users.
  202.  
  203.  
  204.  
  205. WHY IS ONLY JRCPPCHK DISTRIBUTED PUBLICLY?
  206.  
  207.  
  208. The  decision  to  distribute  JRCPPCHK  as  part   of   the   public 
  209. distribution package was based on the following thoughts:
  210.  
  211.     1) Since JRCPP is a new product, releasing the heavily "asserted" 
  212.     JRCPPCHK during beta phases can prevent  the  tarnishing  of  the 
  213.     product  name.   The  use  of  JRCPPCHK  is simply a conservative 
  214.     selection, that poses a mild performance penalty.
  215.     
  216.     2) If all the versions that were planned for release were  placed 
  217.     in  the  public  collection,  the collection might be too big for 
  218.     most BBS systems to sponsor it, and too big  for  most  users  to 
  219.     download it.  This reason precluded supplying multiple versions.
  220.     
  221.     3)  By  giving  users  a  full  function  product  with  a slight 
  222.     performance degradation, they might be more motivated to register 
  223.     and  obtain  newer  releases,  with superior performance (but the 
  224.     same quality).
  225.  
  226.  
  227. If you have any comments on the above decisions for  public  release, 
  228. please  feel  free  to  submit  them for consideration.  Distributing 
  229. shareware is a very "nonclassical" means  of  product  marketing  and 
  230. dissemination,  and  input  from  users can prove most valuable.  The 
  231. goal is to provided a very high quality product, obtain  payment  for 
  232. the  author,  and  save  the  user  money  by eliminating the cost of 
  233. marketing and  distribution  channels.   If  you  could  direct  your 
  234. comments towards these three goals, they would prove most interesting.
  235.  
  236. Thank you for your interest and support.
  237.  
  238. James Roskind
  239. 516 Latania Palm Drive
  240. Indialantic FL 32903
  241. (407)729-4348
  242. jar@ileaf.com
  243. or 
  244. ...!uunet!leafusa!jar
  245.