1__________________________________________________________________________ 2 3 This is the Info-ZIP file ZipPorts, last updated on 17 February 1996. 4__________________________________________________________________________ 5 6 7This document defines a set of rules and guidelines for those who wish to 8contribute patches to Zip and UnZip (or even entire ports to new operating 9systems). The list below is something between a style sheet and a "Miss 10Manners" etiquette guide. While Info-ZIP encourages contributions and 11fixes from anyone who finds something worth changing, we are also aware 12of the fact that no two programmers have the programming style and that 13unrestrained changes by a few dozen contributors would result in hideously 14ugly (and unmaintainable) Frankenstein code. So consider the following an 15attempt 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- 19tion with Mark Adler, Cave McNewt and others. The current incarnation 20expands upon the original with insights gained from a few more years of 21happy hacking...) 22 23 24Summary: 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 40Explanations: 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 281Greg Roelofs (a.k.a. Cave Newt) 282Info-ZIP UnZip maintainer 283 284David Kirschbaum 285former Info-ZIP Coordinator 286