Better documentation: usage instructions

[denilsonsa]

The basic zip tool works likes this (extracted from the manpage):

zip […]  [zipfile [file ...]]  [-xi list]

The trrntzip tool says:

Usage: trrntzip [-dfghqsv] [-e[FILE]] [-l[DIR]] [PATH/ZIP FILE]

So… Huh… What order do we pass each file? Does it work just like the standard zip command? How about…

# Can we do this?
trrntzip foobar.zip foo.txt bar/

Does it work like an almost drop-in replacement for the basic zip tool?

I think it needs slightly better documentation on how to use it. The “PATH/ZIP FILE” sounds ambiguous, sounds like I can pass either a path or a zip file, or maybe a mix of both. But maybe it's just because I don't understand it yet.

---

After a few more minutes reading the README, it looks like it requires an already existing ZIP file, instead of creating one based on a list of plain uncompressed files.

So, I have a couple of suggestions:

• Improve the -h to better describe the positional parameter(s).
• Improve the -h to actually say what the tool does. If it said something like "Modifies ZIP files in-place for reproducibility", then its purpose and behavior would be clear. But right now it says nothing.
• Add --help (and maybe -help) as optional ways to printing the help message.
• Add example usage either to the help message or to the README. It could show all the steps required from raw files to reproducible zip files. It could even show why using plain zip is troublesome, by generating the same zip file twice using both tools and comparing the results. In other words, please add a tutorial text to guide new users.