Overhaul help

[andrews05]

This PR brings a big overhaul to oxipng's help, with new long form descriptions of many options.

The full output (--help) is added as a text file MANUAL.txt. Critiques welcome.

The short output (-h) is simplified and appears as follows:

Losslessly improve compression of PNG files

Usage: oxipng [OPTIONS] <files>...

Arguments:
  <files>...  File(s) to compress (use '-' for stdin)

Options:
  -o, --opt <level>       Optimization level (0-6, or max) [default: 2]
  -r, --recursive         Recurse input directories, optimizing all PNG files
      --dir <directory>   Write output file(s) to <directory>
      --out <file>        Write output file to <file>
      --stdout            Write output to stdout
  -p, --preserve          Preserve file permissions and timestamps if possible
  -P, --pretend           Do not write any files, only show compression results
  -s                      Strip safely-removable chunks, same as '--strip safe'
      --strip <mode>      Strip metadata (safe, all, or comma-separated list)
                          CAUTION: 'all' will convert APNGs to standard PNGs
      --keep <list>       Strip all metadata except in the comma-separated list
  -a, --alpha             Perform additional alpha channel optimization
  -i, --interlace <type>  Set PNG interlacing type (0, 1, keep) [default: 0]
      --scale16           Forcibly reduce 16-bit images to 8-bit (lossy)
  -v, --verbose...        Run in verbose mode (use twice to increase verbosity)
  -q, --quiet             Run in quiet mode
  -f, --filters <list>    Filters to try (0-9; see '--help' for details)
      --fast              Use fast filter evaluation
      --zc <level>        Deflate compression level (1-12)
      --nb                Do not change bit depth
      --nc                Do not change color type
      --np                Do not change color palette
      --ng                Do not change to or from grayscale
      --nx                Do not perform any transformations
      --nz                Do not recompress unless transformations occur
      --fix               Disable checksum validation
      --force             Write the output even if it is larger than the input
  -Z, --zopfli            Use the much slower but stronger Zopfli compressor
      --timeout <secs>    Maximum amount of time to spend on optimizations
  -t, --threads <num>     Set number of threads to use [default: num CPU cores]
  -h, --help              Print help (see more with '--help')
  -V, --version           Print version

Run `oxipng --help` to see full details of all options

[ace-dent]

Thanks so much for attending to this! :-)
I'd like to review. Can you wait a couple of days for feedback?

[andrews05]

@ace-dent Sure thing, happy to wait :)

[andrews05]

@AlexTMjugador It might be good for the deploy workflow to include the manual, and maybe even generate and commit the newest version.

[AlexTMjugador]

Okay, I'll try to get the deployment workflow to include the manual file today. But I'm not sure what you mean by "generate and commit the newest version", can you clarify that? Do you want the workflow to run OxiPNG with the --help switch and dump that to the manual file?

[andrews05]

@AlexTMjugador Yeah, exactly.

oxipng -V > MANUAL.txt
oxipng --help >> MANUAL.txt

I've added a shell script to do this which we can run manually, but might be good to automate it during deploy if it's easy enough to do.

[ace-dent]

Fixes #472.
Fixes #526.

Please add:

• Comment on parameters being case sensitive.
• Example of short vs long parameter usage, e.g. -Psavvo6 == --pretend --strip=safe --alpha --verbose --verbose --opt=6.
  This fixes Tolerate lowercase -z parameter #539.

[ace-dent]

@andrews05 - looking good! 🏆

[andrews05]

Thanks for the review @ace-dent!

Please add:

• Comment on parameters being case sensitive.
• Example of short vs long parameter usage, e.g. -Psavvo6 == --pretend --strip=safe --alpha --verbose --verbose --opt=6.
  This fixes Tolerate lowercase -z parameter #539.

I might leave these for the Read Me. The Clap library's help system isn't as well-suited for adding extra information like this (at least if you care about exactly where that info gets inserted).

[AlexTMjugador]

Coming back to life...

I've added a shell script to do this which we can run manually, but might be good to automate it during deploy if it's easy enough to do.

Yeah, this is easy enough to do, I've been pretty busy these days though. Will get to it as soon as I can 😄

[AlexTMjugador]

I've just changed the release workflow to generate the manual and include it in the release archive. I think that automatically generating and committing new manuals to CI can get a bit noisy and cumbersome due to the need to pull or rebase new commits, while release workflows are kind of infrequent to run anyway, so I think it's fine if we don't commit anything automatically for now.

[andrews05]

Thanks @AlexTMjugador! This should be good to merge if you approve.

[AlexTMjugador]

Yeah, I think it's good to go! 🎉