Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 331 insertions, 0 deletions

diff --git a/upstream/opensuse-tumbleweed/man5/pam.5 b/upstream/opensuse-tumbleweed/man5/pam.5
new file mode 100644
index 00000000..f927accd
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man5/pam.5
@@ -0,0 +1,331 @@
+\
+.\" 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 "PAM format specification" 5 "27 November 2013" "netpbm documentation"
+
+.SH NAME
+pam - Netpbm common 2-dimensional bitmap format
+
+.UN general
+.SH GENERAL
+.PP
+The PAM image format is a lowest common denominator 2 dimensional map
+format.
+.PP
+It is designed to be used for any of myriad kinds of graphics, but can
+theoretically be used for any kind of data that is arranged as a two
+dimensional rectangular array.  Actually, from another perspective it
+can be seen as a format for data arranged as a three dimensional
+array.
+.PP
+The name "PAM" is an acronym derived from "Portable
+Arbitrary Map." This derivation makes more sense if you consider
+it in the context of the other Netpbm format names: PBM, PGM, and PPM.
+.PP
+This format does not define the meaning of the data at any particular
+point in the array.  It could be red, green, and blue light
+intensities such that the array represents a visual image, or it could
+be the same red, green, and blue components plus a transparency
+component, or it could contain annual rainfalls for places on the
+surface of the Earth.  Any process that uses the PAM format must 
+further define the format to specify the meanings of the data.
+.PP
+A PAM image describes a two dimensional grid of tuples.  The tuples are
+arranged in rows and columns.  The width of the image is the number of
+columns.  The height of the image is the number of rows.  All rows are the
+same width and all columns are the same height.  The tuples may have any
+degree, but all tuples have the same degree.  The degree of the tuples is
+called the depth of the image.  Each member of a tuple is called a sample.  A
+sample is an unsigned integer which represents a locus along a scale which
+starts at zero and ends at a certain maximum value called the maxval.  The
+maxval is the same for every sample in the image.  The two dimensional array
+of all the Nth samples of each tuple is called the Nth plane or Nth channel of
+the image.
+.PP
+Though the basic format does not assign any meaning to the tuple values, it
+does include an optional string that describes that meaning.  The
+contents of this string, called the tuple type, are arbitrary from the
+point of view of the basic PAM format, but users of the format may assign
+meaning to it by convention so they can identify their particular
+implementations of the PAM format.  Some tuple types are defined as
+official subformats of PAM.  See 
+.UR #tupletype
+Defined Tuple Types
+.UE
+\&.
+
+.UN format_universe
+.SH The Confusing Universe of Netpbm Formats
+.PP
+It is easy to get confused about the relationship between the PAM
+format and PBM, PGM, PPM, and PNM.  Here is a little enlightenment:
+.PP
+"PNM" is not really a format.  It is a shorthand for the PBM, PGM,
+and PPM formats collectively.  It is also the name of a group of
+library functions that can each handle all three of those formats.
+.PP
+"PAM" is in fact a fourth format.  But it is so general
+that you can represent the same information in a PAM image as you can
+in a PBM, PGM, or PPM image.  And in fact a program that is designed
+to read PBM, PGM, or PPM and does so with a recent version of the
+Netpbm library will read an equivalent PAM image just fine and the
+program will never know the difference.
+.PP
+To confuse things more, there is a collection of library routines
+called the "pam" functions that read and write the PAM
+format, but also read and write the PBM, PGM, and PPM formats.  They
+do this because the latter formats are much older and more popular, so
+even a new program must work with them.  Having the library handle all
+the formats makes it convenient to write programs that use the newer
+PAM format as well.
+
+.UN layout
+.SH THE LAYOUT
+.PP
+A convenient way to read and write the PAM format accurately is via the
+.BR "libnetpbm" (3)\c
+\& C subroutine library.
+.PP
+A PAM file consists of a sequence of one or more PAM images.  There are
+no data, delimiters, or padding before, after, or between images.
+.PP
+Each PAM image consists of a header followed immediately by a raster.
+.PP
+Here is an example header:
+
+.nf
+
+P7
+WIDTH 227
+HEIGHT 149
+DEPTH 3
+MAXVAL 255
+TUPLTYPE RGB
+ENDHDR
+
+
+.fi
+.PP
+The header begins with the ASCII characters "P7" followed
+by newline.  This is the magic number.
+.PP
+Note: \fBxv\fP thumbnail images also start with the "P7" magic number.
+(This and PAM were independent extensions to the Netpbm formats).  The rest
+of the format makes it easy to distinguish PAM from that format, though).
+.PP
+The header continues with an arbitrary number of lines of ASCII
+text.  Each line ends with and is delimited by a newline character.
+.PP
+Each header line consists of zero or more whitespace-delimited
+tokens or begins with "#".  If it begins with "#"
+it is a comment and the rest of this specification does not apply to
+it.
+.PP
+A header line which has zero tokens is valid but has no meaning.
+.PP
+The type of header line is identified by its first token, which is
+8 characters or less:
+
+
+.TP
+\fBENDHDR  \fP
+This is the last line in the header.  The header must contain
+exactly one of these header lines.
+
+.TP
+\fBHEIGHT  \fP
+The second token is a decimal number representing the height
+of the image (number of rows).  The header must contain exactly one
+of these header lines.
+
+.TP
+\fBWIDTH\fP
+The second token is a decimal number representing the width of the
+image (number of columns).  The header must contain exactly one of
+these header lines.
+
+.TP
+\fBDEPTH\fP
+The second token is a decimal number representing the depth of the
+image (number of planes or channels).  The header must contain exactly
+one of these header lines.
+
+.TP
+\fBMAXVAL\fP
+The second token is a decimal number representing the maxval of the image.
+The header must contain exactly one of these header lines.
+
+.TP
+\fBTUPLTYPE\fP
+The header may contain any number of these header lines, including
+zero.  The rest of the line is part of the tuple type.  The rest of
+the line is not tokenized, but the tuple type does not include any
+white space immediately following \fBTUPLTYPE \fP or at the very end
+of the line.  It does not include a newline.  There must be something
+other than white space after the \fBTUPLTYPE\fP token.
+.sp
+If there are multiple \fBTUPLTYPE\fP header lines, the tuple type
+is the concatenation of the values from each of them, separated by a
+single blank, in the order in which they appear in the header.  If
+there are no \fBTUPLTYPE\fP header lines the tuple type is the null
+string.
+
+
+.PP
+The raster consists of each row of the image, in order from top to bottom,
+consecutive with no delimiter of any kind between, before, or after, rows.
+.PP
+Each row consists of every tuple in the row, in order from left to
+right, consecutive with no delimiter of any kind between, before, or
+after, tuples.
+.PP
+Each tuple consists of every sample in the tuple, in order,
+consecutive with no delimiter of any kind between, before, or after,
+samples.
+.PP
+Each sample consists of an unsigned integer in pure binary format,
+with the most significant byte first.  The number of bytes is the
+minimum number of bytes required to represent the maxval of the image.
+.PP
+The character referred to as "newline" herein is the
+character known in ASCII as Line Feed or LF.
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+Height, width, depth, and maxval are at least 1.
+.PP
+Height, width, and depth have no defined maximum, but processors and
+generators of images usually have their own limitations.
+.PP
+The maxval of an image is never greater than 65535.  (The reason it is
+limited is to make it easier to build an image processor, in which
+intermediate arithmetic values often have to fit within 31 or 32 bits).
+There was no specified limitation before October, 2005, but essentially
+all implementations have always observed it.
+
+.UN tupletype
+.SH DEFINED TUPLE TYPES
+.PP
+Some tuple types are defined in this specification to specify
+official subformats of PAM for especially popular applications of the
+format.  Users of the format may also define their own tuple types,
+and thus their own subformats.
+.PP
+Tuple type affects \fIonly\fP the meanings of the samples (which are
+unsigned integers) in the tuples of the image.  It does not affect how the
+samples or tuples are encoded.  Tuple type may affect the meaning of a tuple's
+position in the array (e.g. it may indicate in a visual image that a tuple
+in Row 1 is one at the top of the image rather than the bottom).
+.PP
+Tuple type never determines how many samples are in a tuple (that is
+instead determined by the DEPTH header line).  Tuple type could be said to
+imply a depth (number of samples per tuple) because certain tuple types are
+valid only in combination with certain DEPTH values, but it is good
+programming practice to use DEPTH for the depth when decoding the raster and
+separately validate that the depth is consistent with the tuple type.  Also,
+it is good practice to accept a depth that is too great and just ignore the
+higher numbered planes.
+  
+.UN visual
+.SS PAM Used For Visual Images
+.PP
+A common use of PAM images is to represent visual images such
+as are typically represented by images in the older and more concrete
+PBM, PGM, and PPM formats.
+
+.B Black And White
+.PP
+A black and white image, such as would alternatively be represented by a
+PBM image, has a tuple type of "BLACKANDWHITE".  Such a PAM image has a depth
+of 1 and maxval 1 where the one sample in each tuple is 0 to represent a black
+pixel and 1 to represent a white one.  The maxval, height, width, and order of
+tuples in the raster bear the obvious relationship to those of the equivalent
+PGM image.
+.PP
+Note that in the PBM format, a sample value of zero means white, but in
+PAM, zero means black.
+
+.B Grayscale
+.PP
+A grayscale image, such as would alternatively be represented by a PGM
+image, has a tuple type of "GRAYSCALE".  Such a PAM image has a depth of 1.
+The maxval, height, width, and raster bear the obvious relationship to those
+of the equivalent PGM image.
+
+.B Color
+.PP
+A color image, such as would alternatively be represented by a PPM image,
+has a tuple type of "RGB".  Such a PAM image has a depth of 3.  The maxval,
+height, width, and raster bear the obvious relationship to those of the PPM
+image.  The first plane represents red, the second green, and the third blue.
+
+.B Transparent
+.PP
+Each of the visual image formats mentioned above has a variation that
+contains transparency information.  In that variation, the tuple type
+has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one
+more plane.  The highest numbered plane is the opacity plane (sometimes
+called an alpha plane or transparency plane).
+.PP
+In this kind of image, the color represented by a pixel is actually
+a combination of an explicitly specified foreground color and a background
+color to be identified later.
+.PP
+The planes other than the opacity plane describe the foreground
+color.  A sample in the opacity plane tells how opaque the pixel is, by
+telling what fraction of the pixel's light comes from the foreground
+color.  The rest of the pixel's light comes from the (unspecified)
+background color.
+.PP
+For example, in a GRAYSCALE_ALPHA image, assume Plane 0 indicates
+a gray tone 60% of white and Plane 1 indicates opacity 25%.  The
+foreground color is the 60% gray, and 25% of that contributes to the
+ultimate color of the pixel.  The other 75% comes from some background
+color.  So let's assume further that the background color of the pixel
+is full white.  Then the color of the pixel is 90% of white:  25% of
+the foreground 60%, plus 75% of the background 100%.
+.PP
+The sample value is the opacity fraction just described, as a fraction
+of the maxval.  Note that it is \fInot\fP gamma-adjusted like the
+foreground color samples.
+
+
+.UN internetmediatype
+.SH INTERNET MEDIA TYPE
+.PP
+No Internet Media Type (aka MIME type, content type) for PBM has been
+registered with IANA, but the unofficial value
+image/x-portable-arbitrarymap is
+assigned by this specification, to be consistent with conventional values for
+the older Netpbm formats.
+
+.UN filename
+.SH FILE NAME
+.PP
+The conventional suffix for the name of a PAM file is ".pam".
+But this is not required.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "Netpbm" (1)\c
+\&,
+.BR "pbm" (5)\c
+\&,
+.BR "pgm" (5)\c
+\&,
+.BR "ppm" (5)\c
+\&,
+.BR "pnm" (5)\c
+\&,
+.BR "libnetpbm" (3)\c
+\&
+.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/pam.html
+.PP
\ No newline at end of file