home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 August / PCWorld_2000-08_cd.bin / Software / TemaCD / freedos / full.bin / SOURCE / UNZ532 / PROGINFO / ZIPPORTS < prev   
Text File  |  1996-02-17  |  14KB  |  286 lines
  1. __________________________________________________________________________
  2.  
  3.   This is the Info-ZIP file ZipPorts, last updated on 17 February 1996.
  4. __________________________________________________________________________
  5.  
  6.  
  7. This document defines a set of rules and guidelines for those who wish to
  8. contribute patches to Zip and UnZip (or even entire ports to new operating
  9. systems).  The list below is something between a style sheet and a "Miss 
  10. Manners" etiquette guide.  While Info-ZIP encourages contributions and 
  11. fixes from anyone who finds something worth changing, we are also aware
  12. of the fact that no two programmers have the programming style and that 
  13. unrestrained changes by a few dozen contributors would result in hideously
  14. ugly (and unmaintainable) Frankenstein code.  So consider the following an
  15. attempt by the maintainers to maintain sanity as well as useful code.
  16.  
  17. (The first version of this document was called either "ZipRules" or the
  18. "No Feelthy ..." file and was compiled by David Kirschbaum in consulta-
  19. tion with Mark Adler, Cave McNewt and others.  The current incarnation
  20. expands upon the original with insights gained from a few more years of
  21. happy hacking...)
  22.  
  23.  
  24. Summary:
  25.  
  26.   (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS
  27. (0.1) The Golden Rule:    DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
  28. (0.2) The Silver Rule:    DO UNTO THE LATEST BETA CODE
  29. (0.3) The Bronze Rule:    NO FEELTHY PIGGYBACKS
  30.  
  31.   (1) NO FEELTHY TABS
  32.   (2) NO FEELTHY CARRIAGE RETURNS
  33.   (3) NO FEELTHY 8-BIT CHARS
  34.   (4) NO FEELTHY LEFT-JUSTIFIED DASHES
  35.   (5) NO FEELTHY FANCY_FILENAMES
  36.   (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
  37.   (7) NO FEELTHY E-MAIL BINARIES
  38.  
  39.  
  40. Explanations:
  41.  
  42.   (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS
  43.  
  44.       No doubt about it, this is the one which really pisses us off and
  45.       pretty much guarantees that your port or patch will be ignored and/
  46.       or laughed at.  Examples range from the *really* severe cases which
  47.       "port" by ripping out all of the existing multi-OS code, to more
  48.       subtle oopers like relying on a local capability which doesn't exist
  49.       on other OSes or in older compilers (e.g., the use of ANSI "#elif"
  50.       or "#pragma" or "##" constructs, C++ comments, GNU extensions, etc.).
  51.       As to the former, use #ifdefs for your new code (see rule 0.3).  And
  52.       as to the latter, trust us--there are few things we'd like better
  53.       than to be able to use some of the elegant "new" features out there
  54.       (many of which have been around for a decade or more).  But our code
  55.       still compiles on machines dating back even longer, at least in spirit
  56.       --e.g., the AT&T 3B1 family and Dynix/ptx.  Until we say otherwise,
  57.       dinosaurs are supported.
  58.  
  59.  
  60. (0.1) The Golden Rule:  DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
  61.  
  62.       In other words, try to fit into the local style of programming--no
  63.       matter how painful it may be.  This includes cosmetic aspects like
  64.       indenting the same amount (both in the main C code and in the in-
  65.       clude files), using braces and comments similarly, NO TABS (see rule
  66.       #1), etc.; but also more substantive things like (for UnZip) putting
  67.       character strings into static (far) variables and using the LoadFar-
  68.       String macros to avoid overflowing limited MS-DOS data segments, and
  69.       using the ugly Info() macro instead of the more usual *printf() 
  70.       functions so that dynamic-link-library ports are simpler.  NEVER put
  71.       single-OS code (e.g., OS/2) of more than two or three lines into the
  72.       main (generic) modules; those are shared by everybody, and nobody else
  73.       cares about it or wants to see it.
  74.  
  75.       Note that not only do Zip and UnZip differ in these respects, so do
  76.       individual parts of each program.  While it would be nice to have
  77.       global consistency, cosmetic changes are not a high priority; for
  78.       now we'll settle for local consistency--i.e., don't make things any
  79.       worse than they already are.
  80.  
  81.       Exception (BIG exception):  single-letter variable names.  Despite
  82.       the prevailing practice in much of Zip and parts of UnZip, and de-
  83.       spite the fact that one-letter variables allow you to pack really
  84.       cool, compact and complicated expressions onto one line, they also
  85.       make the code very difficult to maintain and are therefore *strongly*
  86.       discouraged.  Don't ask us who is responsible in the first place;
  87.       while this sort of brain damage is not uncommon among former BASIC
  88.       programmers, it is nevertheless a lifelong embarrassment, and we do
  89.       try to pity the poor sod (that is, when we're not chasing bugs and
  90.       cursing him).  :-)
  91.  
  92.  
  93. (0.2) The Silver Rule:  DO UNTO THE LATEST BETA CODE
  94.  
  95.       Few things are as annoying as receiving a large patch which obviously
  96.       represents a lot of time and careful work but which is relative to
  97.       an old version of Info-ZIP code.  As wonderful as Larry Wall's patch
  98.       program is at applying context diffs to modified code, we regularly
  99.       make near-global changes and/or reorganize big chunks of the sources
  100.       (particularly in UnZip), and "patch" can't work miracles--big changes
  101.       invariably break any patch which is relative to an old version of the
  102.       code.
  103.  
  104.       Bottom line:  contact the Info-ZIP core team FIRST (via the zip-bugs
  105.       e-mail address) and get up to date with the latest code before begin-
  106.       ning a big new port.  And try to *stay* up to date while working on
  107.       your port--at least, as much as possible.
  108.  
  109.       
  110. (0.3) The Bronze Rule:  NO FEELTHY PIGGYBACKS
  111.  
  112.       UnZip is currently ported to something like 12 operating systems
  113.       (a few more or less depending on how one counts), and each of these,
  114.       with the possible exception of VM/CMS, has a unique macro identifying
  115.       it:  AMIGA, ATARI_ST, __human68k__, MACOS, MSDOS, MVS, OS2, TOPS20,
  116.       UNIX, VMS, WIN32.  Zip is moving in the same direction.  New ports
  117.       should NOT piggyback one of the existing ports unless they are sub-
  118.       stantially similar--for example, Minix and Coherent are basically Unix
  119.       and therefore are included in the UNIX macro, but DOS djgpp ports and
  120.       OS/2 emx ports (both of which use the Unix-originated GNU C compiler
  121.       and often have "unix" defined by default) are obviously *not* Unix.
  122.       [The existing MTS port is a special exception; basically only one per-
  123.       son knows what MTS really is, and he's not telling.  Presumably it's
  124.       not very close to Unix, but it's not worth arguing about it now.]
  125.       Along the same lines, neither OS/2 nor Human68K is the same as (or
  126.       even close to) MS-DOS.  MVS and VM/CMS, on the other hand, are quite
  127.       similar to each other and are therefore combined in most places.
  128.  
  129.       Bottom line:  when adding a new port (e.g., QDOS), create a new macro
  130.       for it ("QDOS"), a new subdirectory ("qdos") and a new source file for
  131.       OS-specific code ("qdos/qdos.c").  Use #ifdefs to fit any OS-specific
  132.       changes into the existing code (e.g., unzpriv.h).  If it's close enough
  133.       to an existing port that piggybacking is a temptation, define a new
  134.       "combination macro" (e.g., "CMS_MVS") and replace the old macros as
  135.       required.  (This last applies to UnZip, at least; the old preference
  136.       in Zip was fewer macros and long #ifdef lines, so talk to Onno or Jean-
  137.       loup about that.)  See also rule 0.1.
  138.  
  139.       (Note that, for UnZip, new ports need not attempt to deal with all
  140.       features.  Among other things, the wildcard-zipfile code in do_wild()
  141.       may be replaced with a supplied dummy version, since opendir/readdir/
  142.       closedir() or the equivalent can be difficult to implement.)
  143.  
  144.  
  145.   (1) NO FEELTHY TABS
  146.  
  147.       Some editors and e-mail systems either have no capability to use
  148.       and/or display tab characters (ASCII 9) correctly, or they use non-
  149.       standard or variable-width tab columns, or other horrors.  Some edi-
  150.       tors auto-convert spaces to tabs, after which the blind use of "diff
  151.       -c" results in a huge and mostly useless patch.  Yes, *we* know about
  152.       diff's "-b" option, but not everyone does.  And yes, we also know this
  153.       makes the source files bigger, even after compression; so be it.  If
  154.       we *really* cared that much about the size of the sources, we'd still
  155.       be writing Unix-only utilities.
  156.  
  157.       Bottom line:  use spaces, not tabs.
  158.  
  159.       Exception:  some of the makefiles (the Unix one in particular) require
  160.       tabs as part of the syntax.
  161.  
  162.       Related utility programs:
  163.           Unix, OS/2 and MS-DOS:  expand, unexpand.
  164.           MS-DOS:  Buerg's TABS; Toad Hall's TOADSOFT.
  165.           And some editors have the conversion built-in.
  166.  
  167.  
  168.   (2) NO FEELTHY CARRIAGE RETURNS
  169.  
  170.       All source, documentation and other text files shall have Unix style
  171.       line endings (LF only, a.k.a. ctrl-J), not the DOS/OS2/NT CR+LF or Mac
  172.       CR-only line endings.
  173.  
  174.       Reason:  "real programmers" in any environment can convert back and
  175.       forth between Unix and DOS/Mac style.  All PC compilers but a few old
  176.       Borland versions can use either Unix or MS-DOS end-of-lines.  Buerg's
  177.       LIST (file-display utility) for MS-DOS can use Unix or MS-DOS EOLs.
  178.       Both Zip and UnZip can convert line-endings as appropriate.  But Unix
  179.       utilities like diff and patch die a horrible death (or produce horrible
  180.       output) if the target files have CRs.
  181.  
  182.       Related utilities:  flip for Unix, OS/2 and MS-DOS; Unix "tr".
  183.  
  184.       Exceptions:  documentation in pre-compiled binary distributions should
  185.       be in the local (target) format.
  186.  
  187.  
  188.   (3) NO FEELTHY 8-BIT CHARS
  189.  
  190.       Do all your editing in a plain-text ASCII editor.  No WordPerfect, MS
  191.       Word, WordStar document mode, or other word processor files, thenkyew.
  192.       No desktop publishing.  *Especially* no EBCDIC.  No TIFFs, no GIFs, no
  193.       embedded pictures or dancing ladies (too bad, Cave Newt).  [Sigh... -CN]
  194.  
  195.       Reason:  compatibility with different consoles.  My old XT clone is
  196.       the most limited!
  197.  
  198.       Exceptions:  some Macintosh makefiles apparently require some 8-bit
  199.       characters; the Human68k port uses 8-bit characters for Kanji or Kana
  200.       comments (I think); etc.
  201.  
  202.       Related utilities:  vi, emacs, EDLIN, Turbo C editor, other programmers'
  203.       editors, various word processor -> text conversion utilities.
  204.  
  205.  
  206.   (4) NO FEELTHY LEFT-JUSTIFIED DASHES
  207.  
  208.       Always precede repeated dashes (------) with one or more leading non-
  209.       dash characters:  spaces, tabs, pound signs (#), comments (/*), what-
  210.       ever.
  211.  
  212.       Reason:  sooner or later your source file will be e-mailed through an
  213.       undigestifier utility, most of which treat leading dashes as end-of-
  214.       message separators.  We'd rather not have your code broken up into a
  215.       dozen separate untitled messages, thank you.
  216.  
  217.  
  218.   (5) NO FEELTHY FANCY_FILENAMES
  219.  
  220.       Assume the worst:  that someone on a brain-damaged DOS system has to
  221.       work with everything your magic fingers produced.  Keep the filenames
  222.       unimaginative and within MS-DOS limits (i.e., ordinary A..Z, 1..9,
  223.       "-$_!"-type characters, in the 8.3 "filename.ext" format).  Mac and
  224.       Unix users, giggle all you want, but no spaces or multiple dots.
  225.  
  226.       Reason:  compatibility with different file systems.  MS-DOS FAT is the
  227.       most limited, with the exception of CompuServe (6.3, argh).
  228.  
  229.       Exceptions:  slightly longer names are occasionally acceptable within
  230.       OS-specific subdirectories, but don't do that unless there's a good
  231.       reason for it.
  232.  
  233.  
  234.   (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
  235.  
  236.       Beta testers and developers are in general expected to have both
  237.       ftp capability and the ability to deal with zipfiles.  Those without
  238.       should either find a friend who does or else learn about ftp-mailers.
  239.  
  240.       Reason:  the core development team barely has time to work on the
  241.       code, much less prepare oddball formats and/or mail betas out (and
  242.       the situation is getting worse, sigh).
  243.  
  244.       Exceptions:  anyone seriously proposing to do a new port will be
  245.       given special treatment, particularly with respect to UnZip; we
  246.       obviously realize that bootstrapping a completely new port can be
  247.       quite difficult and have no desire to make it even harder due to
  248.       lack of access to the latest code (rule 0.2).
  249.  
  250.       Public releases of UnZip, on the other hand, will be available in
  251.       two formats:  .tar.Z (16-bit compress'd tar) and .zip (either "plain"
  252.       or self-extracting).  Zip sources and executables will generally only
  253.       be distributed in .zip format, since Zip is pretty much useless without
  254.       UnZip.
  255.  
  256.  
  257.   (7) NO FEELTHY E-MAIL BINARIES
  258.  
  259.       Binary files (e.g., executables, test zipfiles, etc.) should NEVER
  260.       be mailed raw.  Where possible, they should be uploaded via ftp in
  261.       BINARY mode; if that's impossible, Mark's "ship" ASCII-encoder should
  262.       be used; and if that's unavailable, uuencode or xxencode should be
  263.       used.  Weirdo NeXTmail, mailtool and MIME formats are also Right Out.
  264.  
  265.       Files larger than 50KB may need to be broken into pieces for mailing
  266.       (be sure to label them in order!), unless "ship" is used (it can
  267.       auto-split, label and mail files if told to do so).  If Down Under
  268.       is involved, files must be broken into under-20KB chunks.
  269.  
  270.       Reasons:  to prevent sounds of gagging mailers from resounding through-
  271.       out the land.  To be relatively efficient in the binary->ASCII conver-
  272.       sion.  (Yeah, yeah, I know, there's better conversions out there.  But
  273.       not as widely known, and they often break on BITNET gateways.)
  274.  
  275.       Related utilities:  ship, uuencode, uudecode, uuxfer20, quux, others.
  276.       Just make sure they don't leave embedded or trailing spaces (that is,
  277.       they should use the "`" character in place of ASCII 32).  Otherwise
  278.       mailers are prone to truncate or whatever.
  279.  
  280.  
  281. Greg Roelofs (a.k.a. Cave Newt)
  282. Info-ZIP UnZip maintainer
  283.  
  284. David Kirschbaum
  285. former Info-ZIP Coordinator
  286.