Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 359 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man1/pamfunc.1 b/upstream/fedora-rawhide/man1/pamfunc.1
new file mode 100644
index 00000000..24f48c2a
--- /dev/null
+++ b/upstream/fedora-rawhide/man1/pamfunc.1
@@ -0,0 +1,359 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamfunc User Manual" 0 "09 September 2020" "netpbm documentation"
+
+.SH NAME
+pamfunc - Apply a simple monadic arithmetic function to a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamfunc\fP
+{
+\fB-multiplier=\fP\fIrealnum\fP |
+\fB-divisor=\fP\fIrealnum\fP |
+\fB-adder=\fP\fIinteger\fP |
+\fB-subtractor=\fP\fIinteger\fP |
+\fB-min=\fP\fIwholenum\fP |
+\fB-max=\fP\fIwholenum\fP
+\fB-andmask=\fP\fIhexmask\fP
+\fB-ormask=\fP\fIhexmask\fP
+\fB-xormask=\fP\fIhexmask\fP
+\fB-not\fP
+\fB-shiftleft=\fP\fIcount\fP
+\fB-shiftright=\fP\fIcount\fP
+[\fB-changemaxval\fP]
+}
+[\fIfilespec\fP]
+.PP
+All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamfunc\fP reads a Netpbm image as input and produces a Netpbm
+image as output, with the same format, and dimensions as the
+input.  \fBpamfunc\fP applies a simple transfer function to each
+sample in the input to generate the corresponding sample in the
+output.  The options determine what function.
+.PP
+The samples involved are PAM samples.  If the input is PBM, PGM, or PPM,
+the output will be that same format, but \fBpamfunc\fP applies the functions
+to the PAM equivalent samples, yielding PAM equivalent samples.  This can
+be nonintuitive in the 
+.UR #pbmoddness
+PBM
+.UE
+\& case.
+  
+.PP
+\fBpamarith\fP is the same thing for binary functions -- it takes
+two images as input and applies a specified simple arithmetic function
+(e.g. addition) on pairs of samples from the two to produce the single
+output image.
+
+
+.UN values
+.SS Values
+.PP
+The functions fall into two categories: arithmetic (such as multiply by 5)
+and bit string (such as and with 01001000).  For the arithmetic functions, the
+function arguments and results are the fraction that a sample is of the
+maxval, i.e. normal interpretation of PAM tuples.  But for the bit string
+functions, the value is the bit string whose value as a binary cipher is
+the sample value, and the maxval indicates the width of the bit string.
+
+.B Arithmetic functions
+.PP
+The arithmetic functions are those selected by the options
+\fB-multiplier\fP, \fB-divisor\fP, \fB-adder\fP, \fB-subtractor\fP,
+\fB-min\fP, and \fB-max\fP.
+.PP
+As an example, consider an image with maxval 100 and a sample value of 10
+and a function of "multiply by 5." The argument to the function is
+10/100 (0.1) and the result is 5 * 0.1 = 0.5.  In the simplest case, the
+maxval of the output is also 100, so the output sample value is 0.5 * 100 =
+50.  As you can see, we could just talk about the sample values themselves
+instead of these fractions and get the same result (10 * 5 = 50), but we
+don't.
+.PP
+Where it makes a practical difference whether we consider the values to be
+the fraction of the maxval or the sample value alone is where \fBpamfunc\fP
+uses a different maxval in the output image than it finds in the input
+image.  See \fB-changemaxval\fP.
+.PP
+So remember in reading the descriptions below that the values are 0.1 and
+0.5 in this example, not 10 and 50.  All arguments and results are in the
+range [0,1].
+
+.B Bit string functions
+.PP
+The bit string functions are those selected by the options
+\fB-andmask\fP, \fB-ormask\fP, \fB-xormask\fP, \fB-not\fP,
+\fB-shiftleft\fP, and \fB-shiftright\fP.
+.PP
+With these functions, the maxval has a very different meaning than in
+normal Netpbm images: it tells how wide (how many bits) the bit string is.
+The maxval must be a full binary count (a power of two minus one, such as
+0xff) and the number of ones in it is the width of the bit string.
+.PP
+As an example, consider an image with maxval 15 and a sample value of 5
+and a function of "and with 0100".  The argument to the function is
+0101 and the result is 0100.
+.PP
+In this example, it doesn't make any practical difference what we consider
+the width of the string to be, as long as it is at least 3.  If the maxval
+were 255, the result would be the same.  But with a bit shift operation,
+it matters.  Consider shifting left by 2 bits.  In the example, where
+the input value is 0101, the result is 0100.  But if the maxval were 255,
+the result would be 00010100.
+.PP
+For a masking function, the mask value you specify must not have
+more significant bits than the width indicated by the maxval.
+.PP
+For a shifting operation, the shift count you specify must not be
+greater than the width indicated by the maxval.
+
+.UN pbmoddness
+.B PBM Oddness
+.PP
+If you're familiar with the PBM format, you may find \fBpamfunc\fP's
+operation on PBM images to be nonintuitive.  Because in PBM black is
+represented as 1 and white as 0 (1.0 and 0.0 normlized), you might be
+expecting adding 1 to white to yield black.
+.PP
+But the PBM format is irrelevant, because \fBpamfunc\fP operates on the
+numbers found in the PAM equivalent (see above).  In a PAM black and white
+image, black is 0 and white is 1 (0.0 and 1.0 normalized).  So white plus 1
+(clipped to the maximum of 1.0) is white.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamfunc\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-multiplier=\fIrealnum\fP\fP
+.sp
+This option makes the transfer function that of multiplying by
+     \fIrealnum\fP.  \fIrealnum\fP must be nonnegative.  If the result
+     is greater than one, it is clipped to one.
+.sp
+Where the input is a PGM or PPM image, this has the effect of
+     dimming or brightening it.  For a different kind of brightening,
+     see
+.BR "\fBpambrighten\fP" (1)\c
+\& and
+.BR "\fBppmflash\fP" (1)\c
+\&
+.sp
+Also, see
+.BR "\fBppmdim\fP" (1)\c
+\&, which does the same
+     thing as \fBpamfunc -multiplier\fP on a PPM image with a multiplier
+     between zero and one, except it uses integer arithmetic, so it may be
+     faster.
+.sp
+And
+.BR "\fBppmfade\fP" (1)\c
+\& can generate a whole
+     sequence of images of brightness declining to black or increasing to
+     white, if that's what you want.
+     
+.TP
+\fB-divisor=\fIrealnum\fP\fP
+.sp
+This option makes the transfer function that of dividing by
+     \fIrealnum\fP.  \fIrealnum\fP must be nonnegative.  If the result
+     is greater than one, it is clipped to one.
+.sp
+This is the same function as you would get with \fB-multiplier\fP,
+     specifying the multiplicative inverse of \fIrealnum\fP.
+     
+.TP
+\fB-adder=\fIinteger\fP\fP
+.sp
+This option makes the transfer function that of adding
+     \fIinteger\fP/\fImaxval\fP.  If the result is greater than one, it is
+     clipped to one.  If it is less than zero, it is clipped to zero.
+.sp
+Note that in mathematics, this entity is called an "addend,"
+     and an "adder" is a snake.  We use "adder" because
+     it makes more sense.
+     
+.TP
+\fB-subtractor=\fIinteger\fP\fP
+.sp
+This option makes the transfer function that of subtracting
+     \fIinteger\fP/\fImaxval\fP.  If the result is greater than one, it is
+     clipped to one.  If it is less than zero, it is clipped to zero.
+.sp
+Note that in mathematics, this entity is called a
+     "subtrahend" rather than a "subtractor." We use
+     "subtractor" because it makes more sense.
+.sp
+This is the same function as you would get with \fB-adder\fP,
+     specifying the negative of \fIinteger\fP.
+     
+.TP
+\fB-min=\fIwholenum\fP\fP
+.sp
+This option makes the transfer function that of taking the maximum of
+     the argument and \fIwholenum\fP/\fImaxval\fP.  I.e the minimum value in
+     the output will be \fIwholenum\fP/\fImaxval\fP.
+
+     If \fIwholenum\fP/\fImaxval\fP is greater than one, though, every value
+     in the output will be one.
+
+.TP
+\fB-max=\fIwholenum\fP\fP
+.sp
+This option makes the transfer function that of taking the minimum of
+     the argument and \fIwholenum\fP/\fImaxval\fP.  I.e the maximum value in
+     the output will be \fIwholenum\fP/\fImaxval\fP.
+
+     If \fIwholenum\fP/\fImaxval\fP is greater than one, the function is
+     idempotent -- the output is identical to the input.
+     
+.TP
+\fB-andmask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise anding
+     with \fIhexmask\fP.
+.sp
+\fIhexmask\fP is in hexadecimal.  Example: \f(CW0f\fP
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-ormask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise
+     inclusive oring with \fIhexmask\fP.
+.sp
+This is analogous to \fB-andmask\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-xormask=\fIhexmask\fP\fP
+.sp
+This option makes the transfer function that of bitwise
+     exclusive oring with \fIhexmask\fP.
+.sp
+This is analogous to \fB-andmask\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-not\fP
+.sp
+This option makes the transfer function that of bitwise logical
+     inversion (e.g. sample value 0xAA becomes 0x55).
+.sp
+\fBpnminvert\fP does the same thing for a bilevel visual image
+     which has maxval 1 or is of PBM type.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-shiftleft=\fIcount\fP\fP
+.sp
+This option makes the transfer function that of bitwise shifting
+     left by \fIcount\fP bits.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-shiftright=\fIcount\fP\fP
+.sp
+This option makes the transfer function that of bitwise shifting
+     right by \fIcount\fP bits.
+.sp
+This is analogous to \fB-shiftleft\fP.
+.sp
+This option was new in Netpbm 10.40 (September 2007).
+
+.TP
+\fB-changemaxval\fP
+.sp
+This option tells \fBpamfunc\fP to use a different maxval in the output
+image than the maxval of the input image, if it helps.  By default, the maxval
+of the output is unchanged from the input and \fBpamfunc\fP modifies the
+sample values as necessary to perform the operation.
+.sp
+But there is one case where \fBpamfunc\fP can achieve the same result just
+by changing the maxval and leaving the sample values unchanged: dividing by a
+number 1 or greater, or multiplying by a number 1 or less.  For example, to
+halve all of the values, \fBpamfunc\fP can just double the maxval.
+.sp
+With \fB-changemaxval\fP, \fBpamfunc\fP will do just that.
+.sp
+As the Netpbm formats have a maximum maxval of 65535, for large divisors,
+\fBpamfunc\fP may not be able to use this method.
+.sp
+An advantage of dividing by changing the maxval is that you don't lose
+precision.  The higher maxval means higher precision.  For example, consider
+an image with a maxval of 100 and sample value of 10.  You divide by 21 and
+then multiply by 21 again.  If \fBpamfunc\fP does this by changing the sample
+values while retaining maxval 100, the division will result in a sample value
+of 0 and the multiplication will also result in zero.  But if \fBpamfunc\fP
+instead keeps the sample value 10 and changes the maxval, the division will
+result in a maxval of 2100 and the multiplication will change it back to 100,
+and the round trip is idempotent.
+.sp
+This option was new in Netpbm 10.65 (December 2013).
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "ppmdim" (1)\c
+\&,
+.BR "pambrighten" (1)\c
+\&,
+.BR "pamdepth" (1)\c
+\&,
+.BR "pamarith" (1)\c
+\&,
+.BR "pamsummcol" (1)\c
+\&,
+.BR "pamsumm" (1)\c
+\&,
+.BR "ppmfade" (1)\c
+\&,
+.BR "pnminvert" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+This program was added to Netpbm in Release 10.3 (June 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamfunc.html
+.PP
\ No newline at end of file