| 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 |