OS/2 Shareware BBS: 9 Archive/09-Archive.zip/unzip512.zip/ZipPorts

Text File | 1994-08-15 | 14KB | 279 lines

__________________________________________________________________________

  This is the Info-ZIP file ZipPorts, last updated on 15 August 1994.
__________________________________________________________________________


This document defines a set of rules and guidelines for those who wish to
contribute patches to Zip and UnZip (or even entire ports to new operating
systems).  The list below is something between a style sheet and a "Miss
Manners" etiquette guide.  While Info-ZIP encourages contributions and
fixes from anyone who finds something worth changing, we are also aware
of the fact that no two programmers have the programming style and that
unrestrained changes by a few dozen contributors would result in hideously
ugly (and unmaintainable) Frankenstein code.  So consider the following an
attempt by the maintainers to maintain sanity as well as useful code.

(The first version of this document was called either "ZipRules" or the
"No Feelthy ..." file and was compiled by David Kirschbaum in consulta-
tion with Mark Adler, Cave McNewt and others.  The current incarnation
expands upon the original with insights gained from a few more years of
happy hacking...)


Summary:

  (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS
(0.1) The Golden Rule:    DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
(0.2) The Silver Rule:    DO UNTO THE LATEST BETA CODE
(0.3) The Bronze Rule:    NO FEELTHY PIGGYBACKS

  (1) NO FEELTHY TABS
  (2) NO FEELTHY CARRIAGE RETURNS
  (3) NO FEELTHY 8-BIT CHARS
  (4) NO FEELTHY LEFT-JUSTIFIED DASHES
  (5) NO FEELTHY FANCY_FILENAMES
  (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
  (7) NO FEELTHY E-MAIL BINARIES


Explanations:

  (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS

      No doubt about it, this is the one which really pisses us off and
      pretty much guarantees that your port or patch will be ignored and/
      or laughed at.  Examples range from the *really* severe cases which
      "port" by ripping out all of the existing multi-OS code, to more
      subtle oopers like relying on a local capability which doesn't exist
      on other OSes or in older compilers (e.g., the use of ANSI "#elif"
      constructs, C++ comments, GNU extensions, etc.).  As to the former,
      use #ifdefs for your new code (see rule 0.3).  And as to the latter,
      trust us--there are few things we'd like better than to be able to
      use some of the elegant "new" features out there (many of which have
      been around for a decade or more).  But our code still compiles on
      machines dating back even longer, at least in spirit--e.g., the AT&T
      3B1 family and Dynix/ptx.  Until we say otherwise, dinosaurs are
      supported.


(0.1) The Golden Rule:  DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE

      In other words, try to fit into the local style of programming--no
      matter how painful it may be.  This includes cosmetic aspects like
      indenting the same amount (both in the main C code and in the in-
      clude files), using braces and comments similarly, NO TABS (see rule
      #1), etc.; but also more substantive things like (for UnZip) putting
      character strings into static (far) variables and using the LoadFar-
      String macros to avoid overflowing limited MS-DOS data segments, and
      using the PRINTF/FPRINTF/PUTC macros instead of the corresponding
      functions so that dynamic-link-library ports are simpler.

      Note that not only do Zip and UnZip differ in these respects, so do
      individual parts of each program.  While it would be nice to have
      global consistency, cosmetic changes are not a high priority; for
      now we'll settle for local consistency--i.e., don't make things any
      worse than they already are.

      Exception (BIG exception):  single-letter variable names.  Despite
      the prevailing practice in much of Zip and parts of UnZip, and de-
      spite the fact that one-letter variables allow you to pack really
      cool, compact and complicated expressions onto one line, they also
      make the code very difficult to maintain and are therefore *strongly*
      discouraged.  Don't ask us who is responsible in the first place;
      while this sort of brain damage is not uncommon among former BASIC
      programmers, it is nevertheless a lifelong embarrassment, and we do
      try to pity the poor sod (that is, when we're not chasing bugs and
      cursing him).  :-)


(0.2) The Silver Rule:  DO UNTO THE LATEST BETA CODE

      Few things are as annoying as receiving a large patch which obviously
      represents a lot of time and careful work but which is relative to
      an old version of Info-ZIP code.  As wonderful as Larry Wall's patch
      program is at applying context diffs to modified code, we regularly
      make near-global changes and/or reorganize big chunks of the sources
      (particularly in UnZip), and "patch" can't work miracles--big changes
      invariably break any patch which is relative to an old version of the
      code.

      Bottom line:  contact the Info-ZIP core team FIRST (via the zip-bugs
      e-mail address) and get up to date with the latest code before begin-
      ning a big new port.


(0.3) The Bronze Rule:  NO FEELTHY PIGGYBACKS

      UnZip is currently ported to something like 10 operating systems
      (a few more or less depending on how one counts), and each of these
      has a unique macro identifying it:  AMIGA, ATARI_ST, __human68k__,
      MACOS, MSDOS, OS2, NT (or WIN32), TOPS20, UNIX, VMS.  Zip is moving
      in the same direction.  New ports should NOT piggyback one of the
      existing ports unless they are substantially similar--for example,
      Minix and Coherent are basically Unix and therefore are included in
      the UNIX macro, but DOS djgpp ports and OS/2 emx ports (both of which
      use the Unix-originated GNU C compiler and often have "unix" defined
      by default) are obviously *not* Unix.  [The existing MTS port is a
      special exception; basically only one person knows what MTS really
      is, and he's not telling.  Presumably it's not very close to Unix,
      but it's not worth arguing about it now.]  Along the same lines,
      neither OS/2 nor Human68K is the same as (or even close to) MS-DOS.

      Bottom line:  when adding a new port (e.g., MVS), create a new macro
      for it ("MVS"), a new subdirectory ("mvs") and a new source file for
      OS-specific code ("mvs/mvs.c").  Use #ifdefs to fit any OS-specific
      changes into the existing code (e.g., unzip.h).  If it's close enough
      to an existing port that piggybacking is a temptation, define a new
      "combination macro" (e.g., "MVS_UNIX") and replace the old macros as
      required.  (This last applies to UnZip, at least; Jean-loup prefers
      fewer macros and long #ifdef lines, so talk to him about Zip.)  See
      also rule 0.1.

      (Note that, for UnZip, new ports need not attempt to deal with all
      features.  Among other things, the wildcard-zipfile code in do_wild()
      may be replaced with a supplied dummy version, since opendir/readdir/
      closedir() or the equivalent can be difficult to implement.)


  (1) NO FEELTHY TABS

      Some editors and e-mail systems either have no capability to use
      and/or display tab characters (ASCII 9) correctly, or they use non-
      standard or variable-width tab columns, or other horrors.  Some edi-
      tors auto-convert spaces to tabs, after which the blind use of "diff
      -c" results in a huge and mostly useless patch.  Yes, *we* know about
      diff's "-b" option, but not everyone does.  And yes, we also know this
      makes the source files bigger, even after compression; so be it.

      Bottom line:  use spaces, not tabs.

      Exception:  some of the makefiles (the Unix one in particular), for
      which tabs are required as part of the syntax.

      Related utility programs:
          Unix, OS/2 and MS-DOS:  expand, unexpand.
          MS-DOS:  Buerg's TABS; Toad Hall's TOADSOFT.
          And some editors have the conversion built-in.


  (2) NO FEELTHY CARRIAGE RETURNS

      All source, documentation and other text files shall have Unix style
      line endings (LF only, a.k.a. ctrl-J), not the DOS/OS2/NT CR+LF or Mac
      CR-only line endings.

      Reason:  "real programmers" in any environment can convert back and
      forth between Unix and DOS/Mac style.  All PC compilers but a few old
      Borland versions can use either Unix or MS-DOS end-of-lines.  Buerg's
      LIST (file-display utility) for MS-DOS can use Unix or MS-DOS EOLs.
      Both Zip and UnZip can convert line-endings as appropriate.  But Unix
      utilities like diff and patch die a horrible death (or produce horrible
      output) if the target files have CRs.

      Related utilities:  flip for Unix, OS/2 and MS-DOS; Unix "tr".

      Exceptions:  documentation in pre-compiled binary distributions should
      be in the local (target) format.


  (3) NO FEELTHY 8-BIT CHARS

      Do all your editing in a plain-text ASCII editor.  No WordPerfect, MS
      Word, WordStar document mode, or other word processor files, thenkyew.
      No desktop publishing.  *Especially* no EBCDIC.  No TIFFs, no GIFs, no
      embedded pictures or dancing ladies (too bad, Cave Newt).  [Sigh... -CN]

      Reason:  compatibility with different consoles.  My old XT clone is
      the most limited!

      Exceptions:  some Macintosh makefiles apparently require some 8-bit
      characters; the Human68k port uses 8-bit characters to Kanji or Kana
      comments (I think); etc.

      Related utilities:  vi, emacs, EDLIN, Turbo C editor, other programmers'
      editors, various word processor -> text conversion utilities.


  (4) NO FEELTHY LEFT-JUSTIFIED DASHES

      Always precede repeated dashes (------) with one or more leading non-
      dash characters:  spaces, tabs, pound signs (#), comments (/*), what-
      ever.

      Reason:  sooner or later your source file will be e-mailed through an
      undigestifier utility, most of which treat leading dashes as end-of-
      message separators.  We'd rather not have your code broken up into a
      dozen separate untitled messages, thank you.


  (5) NO FEELTHY FANCY_FILENAMES

      Assume the worst:  that someone on a brain-damaged DOS system has to
      work with everything your magic fingers produced.  Keep the filenames
      unimaginative and within MS-DOS limits (i.e., ordinary A..Z, 1..9,
      "-$_!"-type characters, in the 8.3 "filename.ext" format).  Mac and
      Unix users, giggle all you want, but no spaces or multiple dots.

      Reason:  compatibility with different file systems.  MS-DOS FAT is the
      most limited, with the exception of CompuServe (6.3, argh).

      Exceptions:  slightly longer names are occasionally acceptable within
      OS-specific subdirectories, but don't do that unless there's a good
      reason for it.


  (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS

      Beta testers and developers are in general expected to have both
      ftp capability and the ability to deal with zipfiles.  Those without
      should either find a friend who does or else learn about ftp-mailers.

      Reason:  the core development team barely has time to work on the
      code, much less prepare oddball formats and/or mail betas out (and
      the situation is getting worse, sigh).

      Exceptions:  anyone seriously proposing to do a new port will be
      given special treatment, particularly with respect to UnZip; we
      obviously realize that bootstrapping a completely new port can be
      quite difficult and have no desire to make it even harder due to
      lack of access to the latest code (rule 0.2).

      Public releases of UnZip, on the other hand, will be available in
      the following formats:  .tar.Z (16-bit compress'd tar), .zoo (ver-
      sion 2.10, available for Unix, OS/2, MS-DOS, VMS, etc.), and .zip
      (either "plain" or self-extracting).  Zip sources and executables
      will generally only be distributed in .zip format, since Zip is
      pretty much useless without UnZip.


  (7) NO FEELTHY E-MAIL BINARIES

      Binary files (e.g., executables, test zipfiles, etc.) should NEVER
      be mailed raw.  Where possible, they should be uploaded via ftp in
      BINARY mode; if that's impossible, Mark's "ship" ASCII-encoder should
      be used; and if that's unavailable, uuencode or xxencode should be
      used.  Weirdo NeXTmail, mailtool and MIME formats are also Right Out.

      Files larger than 50KB may need to be broken into pieces for mailing
      (be sure to label them in order!), unless "ship" is used (it can
      auto-split, label and mail files if told to do so).  If Down Under
      is involved, files must be broken into under-20KB chunks.

      Reasons:  to prevent sounds of gagging mailers from resounding through-
      out the land.  To be relatively efficient in the binary->ASCII conver-
      sion.  (Yeah, yeah, I know, there's better conversions out there.  But
      not as widely known, and they often break on BITNET gateways.)

      Related utilities:  ship, uuencode, uudecode, uuxfer20, quux, others.
      Just make sure they don't leave embedded or trailing spaces (that is,
      they should use the "`" character in place of ASCII 32).  Otherwise
      mailers are prone to truncate or whatever.


Greg Roelofs (a.k.a. Cave Newt)
Info-ZIP UnZip guy

David Kirschbaum
former Info-ZIP Coordinator