From 85cb8d944b636196c424a0773272754e9992745e Mon Sep 17 00:00:00 2001 From: "Benjamin A. Beasley" Date: Sat, 16 Mar 2024 11:04:20 -0400 Subject: [PATCH] Add a man page --- oxipng-fix-metadata-auto.diff | 2 +- oxipng-fix-metadata.diff | 2 +- oxipng.1 | 284 ++++++++++++++++++++++++++++++++++ rust-oxipng.spec | 7 + rust2rpm.toml | 12 ++ 5 files changed, 305 insertions(+), 2 deletions(-) create mode 100644 oxipng.1 diff --git a/oxipng-fix-metadata-auto.diff b/oxipng-fix-metadata-auto.diff index 0578c3a..b9e34c7 100644 --- a/oxipng-fix-metadata-auto.diff +++ b/oxipng-fix-metadata-auto.diff @@ -1,5 +1,5 @@ --- oxipng-9.0.0/Cargo.toml 1970-01-01T00:00:01+00:00 -+++ oxipng-9.0.0/Cargo.toml 2024-03-15T14:15:12.955385+00:00 ++++ oxipng-9.0.0/Cargo.toml 2024-03-16T15:10:42.961579+00:00 @@ -116,7 +116,6 @@ [features] binary = [ diff --git a/oxipng-fix-metadata.diff b/oxipng-fix-metadata.diff index 154c408..1be68c3 100644 --- a/oxipng-fix-metadata.diff +++ b/oxipng-fix-metadata.diff @@ -1,5 +1,5 @@ --- oxipng-9.0.0/Cargo.toml 1970-01-01T00:00:01+00:00 -+++ oxipng-9.0.0/Cargo.toml 2024-03-15T14:15:24.992553+00:00 ++++ oxipng-9.0.0/Cargo.toml 2024-03-16T15:11:05.137897+00:00 @@ -16,8 +16,15 @@ version = "9.0.0" authors = ["Joshua Holmer "] diff --git a/oxipng.1 b/oxipng.1 new file mode 100644 index 0000000..5971fd6 --- /dev/null +++ b/oxipng.1 @@ -0,0 +1,284 @@ +.TH OXIPNG "1" "March 2024" "" "User Commands" +.SH NAME +.B oxipng +\(en Losslessly improve compression of PNG files +.SH SYNOPSIS +.B oxipng +.RI [ OPTIONS ] +.IR files ... +.SH OPTIONS +.SS ARGUMENTS +.TP +.IR files ... +File(s) to compress (use +.RB \(oq \- \(cq +for stdin) +.SS OPTIONS +.TP +.BR \-o ,\ \-\-opt\ \fIlevel +Set the optimization level preset. +The default level +.B 2 +is quite fast and provides good compression. +Lower levels are faster, higher levels provide better compression, +though with increasingly diminishing returns. +.RS +.TP +.B 0\ \[rA] \-\-zc\ 5\ \-\-fast +(1 trial, determined heuristically) +.TP +.B 1\ \[rA] \-\-zc\ 10\ \-\-fast +(1 trial, determined heuristically) +.TP +.B 2\ \[rA] \-\-zc\ 11\ \-f\ 0,1,6,7\ \-\-fast +(4 fast trials, 1 main trial) +.TP +.B 3\ \[rA] \-\-zc\ 11\ \-f\ 0,7,8,9 +(4 trials) +.TP +.B 4\ \[rA] \-\-zc\ 12\ \-f\ 0,7,8,9 +(4 trials) +.TP +.B 5\ \[rA] \-\-zc\ 12\ \-f\ 0,1,2,5,6,7,8,9 +(8 trials) +.TP +.B 6\ \[rA] \-\-zc\ 12\ \-f\ 0-9 +(10 trials) +.TP +.B max\ \[rA] +(stable alias for the max level) +.RE +.IP +Manually specifying a compression option +.RB ( zc , +.BR f , +etc.) will override the optimization preset, +regardless of the order you write the arguments. +.IP +[default: +.BR 2 ] +.TP +.BR \-r ,\ \-\-recursive +When directories are given as input, +traverse the directory trees and optimize all PNG files found +(files with \(lq.png\(rq or \(lq.apng\(rq extension). +.TP +.B \-\-dir\ \fIdirectory +Write output file(s) to +.IR directory . +If the directory does not exist, it will be created. +Note that this will not preserve the directory structure +of the input files when used with +.BR \-\-recursive . +.TP +.B \-\-out\ \fIfile +Write output file to +.I file +.TP +.B \-\-stdout +Write output to stdout +.TP +.BR \-p ,\ \-\-preserve +Preserve file permissions and timestamps if possible +.TP +.BR \-P ,\ \-\-pretend +Do not write any files, only show compression results +.TP +.B \-s +Strip safely-removable chunks, same as +.B \-\-strip\ safe +.TP +.BR \-\-strip\ \fImode +Strip metadata chunks, where +.I mode +is one of: +.RS +.TP +.B safe +Strip all non-critical chunks, except for the following: +cICP, iCCP, sRGB, pHYs, acTL, fcTL, fdAT +.TP +.B all +Strip all non-critical chunks +.TP +.I list +Strip chunks in the comma-separated list, e.g.\: +.B bKGD,cHRM +.RE +.IP +.IR CAUTION : +.B all +will convert APNGs to standard PNGs. +.IP +Note that +.BR bKGD , +.B sBIT +and +.B hIST +will be forcibly stripped if the color type or bit depth is changed, +regardless of any options set. +.TP +.BR \-\-keep\ \fIlist +Strip all metadata except in the comma-separated list +.TP +.BR \-a ,\ \-\-alpha +Perform additional optimization on images with an alpha channel, +by altering the color values of fully transparent pixels. +This is generally recommended for better compression, +but take care as while this is \(lqvisually lossless\(rq, +it is technically a lossy transformation +and may be unsuitable for some applications. +.TP +.BR \-i ,\ \-\-interlace\ \fItype +Set the PNG interlacing type, where +.I type +is one of: +.RS +.TP +.B 0 +Remove interlacing from all images that are processed +.TP +.B 1 +Apply Adam7 interlacing on all images that are processed +.TP +.B keep +Keep the existing interlacing type of each image +.RE +.IP +Note that interlacing can add 25-50% to the size of an optimized image. +Only use it if you believe the benefits outweigh the costs for your use case. +.IP +[default: +.BR 0 ] +.TP +.B \-\-scale16 +Forcibly reduce images with 16 bits per channel to 8 bits per channel. +This is a lossy operation but can provide significant savings +when you have no need for higher depth. +Reduction is performed by scaling the values such that, +e.g. 0x00FF is reduced to 0x01 rather than 0x00. +.IP +Without this flag, 16-bit images will only be reduced in depth +if it can be done losslessly. +.TP +.BR \-v ,\ \-\-verbose ... +Run in verbose mode (use twice to increase verbosity) +.TP +.BR \-q ,\ \-\-quiet +Run in quiet mode +.TP +.BR \-f ,\ \-\-filers\ \fIlist +Perform compression trials with each of the given filter types. +You can specify a comma-separated list, or a range of values. +E.g.\: +.B \-f\ 0\-3 +is the same as +.BR \-f\ 0,1,2,3 . +.IP +PNG delta filters (apply the same filter to every line) +.RS +.TP +.B 0\ \[rA] None +(recommended to always include this filter) +.TP +.B 1\ \[rA] Sub +.TP +.B 2\ \[rA] Up +.TP +.B 3\ \[rA] Average +.TP +.B 4\ \[rA] Paeth +.RE +.IP +Heuristic strategies (try to find the best delta filter for each line) +.RS +.TP +.B 5\ \[rA] MinSum +Minimum sum of absolute differences +.TP +.B 6\ \[rA] Entropy +Highest Shannon entropy +.TP +.B 7\ \[rA] Bigrams +Lowest count of distinct bigrams +.TP +.B 8\ \[rA] BigEnt +Highest Shannon entropy of bigrams +.TP +.B 9\ \[rA] Brute +Smallest compressed size (slow) +.RE +.IP +The default value depends on the optimization level preset. +.TP +.B \-\-fast +Perform a fast compression evaluation of each enabled filter, +followed by a single main compression trial of the best result. +Recommended if you have more filters enabled than CPU cores. +.TP +.B \-\-zc\ \fIlevel +Deflate compression level (1\-12) for main compression trials. +The levels here are defined by the libdeflate compression library. +.IP +The default value depends on the optimization level preset. +.TP +.B \-\-nb +Do not change bit depth +.TP +.B \-\-nc +Do not change color type +.TP +.B \-\-np +Do not change color palette +.TP +.B \-\-ng +Do not change to or from grayscale +.TP +.B \-\-nx +Do not perform any transformations and do not deinterlace by default. +.TP +.B \-\-nz +Do not recompress IDAT unless required due to transformations. +Recompression of other compressed chunks (such as iCCP) will also be disabled. +Note that the combination of +.B \-\-nx +and +.B \-\-nz +will fully disable all optimization. +.TP +.B \-\-fix +Do not perform checksum validation of PNG chunks. +This may allow some files with errors to be processed successfully. +.TP +.B \-\-force +Write the output even if it is larger than the input +.TP +.BR \-Z ,\ \-\-zopfli +Use the much slower but stronger Zopfli compressor +for main compression trials. +Recommended use is with +.B \-o\ max +and +.BR \-\-fast . +.TP +.B \-\-timeout\ \fIsecs +Maximum amount of time, in seconds, to spend on optimizations. +Oxipng will check the timeout +before each transformation or compression trial, +and will stop trying to optimize the file if the timeout is exceeded. +Note that this does not cut short any operations that are already in progress, +so it is currently of limited effectiveness +for large files with high compression levels. +.TP +.BR \-t ,\ \-\-threads\ \fInum +Set number of threads to use +[default: num CPU cores] +.TP +.BR \-h ,\ \-\-help +Print help (see a summary with +.BR \-h ) +.TP +.BR \-V ,\ \-\-version +Print version +.SH "SEE ALSO" +.BR OPTIPNG (1) diff --git a/rust-oxipng.spec b/rust-oxipng.spec index 5518a7a..9e2f3b3 100644 --- a/rust-oxipng.spec +++ b/rust-oxipng.spec @@ -11,6 +11,11 @@ Summary: Lossless PNG compression optimizer License: MIT URL: https://crates.io/crates/oxipng Source: %{crates_source} +# # * Man page hand-written for Fedora in groff_man(7) format based on --help +# # * See “Add man page for the command-line utility” +# # https://github.com/shssoichiro/oxipng/issues/526, and particularly +# # https://github.com/shssoichiro/oxipng/issues/526#issuecomment-2002014746. +Source10: oxipng.1 # Automatically generated patch to strip dependencies and normalize metadata Patch: oxipng-fix-metadata-auto.diff # Manually created patch for downstream crate metadata changes @@ -53,6 +58,7 @@ License: %{shrink: %doc MANUAL.txt %doc README.md %{_bindir}/oxipng +%{_mandir}/man1/oxipng.1* %package devel Summary: %{summary} @@ -228,6 +234,7 @@ use the "zopfli" feature of the "%{crate}" crate. %install %cargo_install +install -t %{buildroot}%{_mandir}/man1 -D -p -m 0644 '%{SOURCE10}' %if %{with check} %check diff --git a/rust2rpm.toml b/rust2rpm.toml index acc3361..199a5be 100644 --- a/rust2rpm.toml +++ b/rust2rpm.toml @@ -2,3 +2,15 @@ cargo-toml-patch-comments = [ "Omit unnecessary files from the crate, as in “Exclude more files from the published crate” https://github.com/shssoichiro/oxipng/pull/591", ] +extra-files = ["%{_mandir}/man1/oxipng.1*"] + +[[package.extra-sources]] +number = 10 +file = "oxipng.1" +comments = [ + "Man page hand-written for Fedora in groff_man(7) format based on --help", + "See “Add man page for the command-line utility” https://github.com/shssoichiro/oxipng/issues/526, and particularly https://github.com/shssoichiro/oxipng/issues/526#issuecomment-2002014746.", +] + +[scripts.install] +post = ["install -t %{buildroot}%{_mandir}/man1 -D -p -m 0644 '%{SOURCE10}'"]