Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 354 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/tifftopnm.1 b/upstream/mageia-cauldron/man1/tifftopnm.1
new file mode 100644
index 00000000..064840b6
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/tifftopnm.1
@@ -0,0 +1,354 @@
+\
+.\" 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 "Tifftopnm User Manual" 0 "02 January 2015" "netpbm documentation"
+
+.SH NAME
+
+tifftopnm - convert a TIFF file into a PNM image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBtifftopnm\fP
+
+[\fB-alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
+[\fB-headerdump\fP]
+[\fB-verbose\fP]
+[\fB-respectfillorder\fP]
+[\fB-byrow\fP]
+[\fB-orientraw\fP]
+[\fItiff-filename\fP]
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBtifftopnm\fP reads a TIFF file as input and produces a PNM image as
+output.  The type of the output file depends on the input file - if it's black
+and white, \fBtifftopnm\fP generates a PBM image; if it's grayscale, it
+generates a PGM image; otherwise, the output is PPM.  The program tells you
+which type it is writing.
+.PP
+If the TIFF file contains multiple images (multiple
+"directories"), \fBtifftopnm\fP generates a multi-image PNM
+output stream.  Before Netpbm 10.27 (March 2005), however, it would
+just ignore all but the first input image.
+.PP
+The \fItiff-filename\fP argument names the file that contains the Tiff
+image.  If you specify "-" or don't specify this
+argument, \fBtifftopnm\fP uses Standard Input.
+.PP
+In either case, before Netpbm 10.70 (March 2015), the file must be
+seekable.  That means no pipe, but any regular file is fine.  In current
+Netpbm, the file need not be seekable, but if it isn't, \fBtifftopnm\fP
+creates a temporary regular file containing the entire image, so you must have
+resources for that (and it may defeat your reason for using a pipe).
+
+.UN library
+.SS TIFF Capability
+.PP
+\fBpamtotiff\fP uses the Libtiff.org TIFF library (or whatever
+equivalent you provide) to interpret the TIFF input.  So the set of files
+it is able to interpret is determined mostly by that library.
+.PP
+This program cannot read every possible TIFF file -- there are
+myriad variations of the TIFF format.  However, it does understand
+monochrome and gray scale, RGB, RGBA (red/green/blue with transparency
+channel), CMYK (Cyan-Magenta-Yellow-Black ink color separation), and
+color palette TIFF files.  An RGB file can have either single plane
+(interleaved) color or multiple plane format.  The program reads 1-8
+and 16 bit-per-sample input, the latter in either bigendian or
+littlendian encoding.  Tiff directory information may also be either
+bigendian or littlendian.
+.PP
+There are many TIFF formats that \fBtifftopnm\fP can read only if
+the image is small enough to fit in memory.  \fBtifftopnm\fP uses the
+TIFF library's TIFFRGBAImageGet() function to process the TIFF image
+if it can get enough memory for TIFFRGBAImageGet() to store the whole
+image in memory at once (that's what TIFFRGBAImageGet() does).  If
+not, \fBtifftopnm\fP uses a more primitive row-by-row conversion
+strategy using the raw data returned by TIFFReadScanLine() and native
+intelligence.  That native intelligence does not know as many formats
+as TIFFRGBAImageGet() does.  And certain compressed formats simply
+cannot be read with TIFFReadScanLine().
+.PP
+Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP never used
+TIFFRGBAImageGet(), so it could not interpret many of the formats it
+can interpret today.
+.PP
+There is no fundamental reason that this program could not read
+other kinds of TIFF files even when they don't fit in memory all at
+once.  The existing limitations are mainly because no one has asked
+for more.
+
+.UN output
+.SS Output Image
+.PP
+The PNM output has the same maxval as the Tiff input, except that
+if the Tiff input is colormapped (which implies a maxval of 65535) the
+PNM output has a maxval of 255.  Though this may result in lost
+information, such input images hardly ever actually have more color
+resolution than a maxval of 255 provides and people often cannot deal
+with PNM files that have maxval > 255.  By contrast, a
+non-colormapped Tiff image that doesn't need a maxval > 255 doesn't
+\fIhave\fP a maxval > 255, so when \fBtifftopnm\fP sees a
+non-colormapped maxval > 255, it takes it seriously and produces a
+matching output maxval.
+.PP
+Another exception is where the TIFF maxval is greater than 65535,
+which is the maximum allowed by the Netpbm formats.  In that case,
+\fBtifftopnm\fP uses a maxval of 65535, and you lose some information
+in the conversion.
+
+.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
+\&), \fBtifftopnm\fP recognizes the following
+command line options:
+.PP
+You may abbreviate any option to its shortest unique prefix.  You may use
+two hyphens instead of one in options.  You may separate an option and
+its value either by an equals sign or white space.
+
+
+.TP
+\fB-alphaout=\fP\fIalpha-filename\fP
+\fBtifftopnm \fPcreates a PGM file containing the alpha channel
+values in the input image.  If the input image doesn't contain a
+transparency channel, the \fIalpha-filename\fP file contains all zero
+(transparent) transparency values.  If you don't specify \fB-alphaout\fP,
+
+\fBtifftopnm\fP does not generate a transparency file, and if the input
+image has an transparency channel, \fBtifftopnm\fP simply discards it.
+.sp
+If you specify \fB-\fP as the filename, \fBtifftopnm\fP
+writes the transparency output to Standard Output and discards the image.
+.sp
+See
+.BR "pamcomp" (1)\c
+\& for one way to use
+the transparency output file.
+
+.TP
+\fB-respectfillorder\fP
+By default, \fBtifftopnm \fP ignores the "fillorder"
+tag in the TIFF input, which means it may incorrectly interpret the
+image.  To make it follow the spec, use this option.  For a lengthy
+but engaging discussion of why \fBtifftopnm\fP works this way and how
+to use the \fB-respectfillorder\fP option, see the note on fillorder
+below.  
+
+.TP
+\fB-byrow\fP
+This option can make \fBtifftopnm\fP run faster.
+.sp
+\fBtifftopnm\fP has two ways to do the conversion from Tiff to PNM, using
+respectively two facilities of the TIFF library:
+
+
+
+.TP
+Whole Image
+Decode the entire image into memory at once, using
+\fBTIFFRGBAImageGet()\fP, then convert to PNM and output row by row.
+   
+.TP
+Row By Row
+Read, convert, and output one row at a time
+using \fBTIFFReadScanline()\fP
+
+
+.sp
+Whole Image is preferable because the Tiff library does more of the
+work, which means it understands more of the Tiff format possibilities
+now and in the future.  Also, some compressed TIFF formats don't allow
+you to extract an individual row.
+.sp
+Row By Row uses far less memory, which means with large images, it
+can run in environments where Whole Image cannot and may also run
+faster.  And because Netpbm code does more of the work, it's possible
+that it can be more flexible or at least give better diagnostic
+information if there's something wrong with the TIFF.
+.sp
+The Netpbm native code may do something correctly that the TIFF
+library does incorrectly, or vice versa.
+.sp
+In Netpbm, we stress function over performance, so by default we
+try Whole Image first, and if we can't get enough memory for the
+decoded image or \fBTIFFRGBAImageGet()\fP fails, we fall back to Row By Row.
+But if you specify the \fB-byrow\fP option, \fBtifftopnm\fP will not
+attempt Whole Image.  If Row By Row does not work, it simply fails.
+.sp
+See 
+.UR #cmyk
+Color Separation (CMYK) TIFFs
+.UE
+\& for a
+description of one way Row By Row makes a significant difference in
+your results.
+.sp
+Whole Image costs you precision when your TIFF image uses more than
+8 bits per sample.  \fBTIFFRGBAImageGet()\fP converts the samples to 8 bits.
+\fBtifftopnm\fP then scales them back to maxval 65535, but the lower
+8 bits of information is gone.
+.sp
+In many versions of the TIFF library, \fBTIFFRGBAImageGet()\fP does not
+correctly interpret TIFF files in which the raster orientation is
+column-major (i.e. a row of the raster is a column of the image).
+With such a TIFF library and file, you must use \fB-byrow\fP to get
+correct output.
+.sp
+Before Netpbm 10.11 (October 2002), \fBtifftopnm\fP always did Row
+By Row.  Netpbm 10.12 always tried Whole Image first.  \fB-byrow\fP
+came in with Netpbm 10.13 (January 2003).
+
+.TP
+\fB-orientraw\fP
+A TIFF stream contains raster data which can be arranged in the
+stream various ways.  Most commonly, it is arranged by rows, with the
+top row first, and the pixels left to right within each row, but many
+other orientations are possible.
+.sp
+The common orientation is the same one the Netpbm formats use, so
+\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
+is oriented that way.
+.sp
+But if the TIFF raster is oriented any other way, it can take a
+considerable amount of processing for \fBtifftopnm\fP to convert it to
+Netpbm format.
+.sp
+\fB-orientraw\fP says to produce an output image that represents the raw
+raster in the TIFF stream rather than the image the TIFF stream is supposed to
+represent.  In the output, the top left corner corresponds to the start of the
+TIFF raster, the next pixel to the right is the next pixel in the TIFF raster,
+etc.  \fBtifftopnm\fP can do this easily, but you don't get the right image
+out.  You can use \fBpamflip\fP to turn the output into the image the TIFF
+stream represents (but if you do that, you pretty much lose the benefit of
+\fB-orientraw\fP).
+.sp
+With this option, \fBtifftopnm\fP always uses the Row By Row method
+(see \fB-byrow\fP).
+.sp
+This option was new in Netpbm 10.42 (March 2008).  Before that,
+\fBtifftopnm\fP generally produces arbitrary results with TIFF images
+that have an orientation other than the common one.
+
+.TP
+\fB-verbose\fP
+Print extra messages to Standard Error about the conversion.
+
+.TP
+\fB-headerdump\fP
+Dump TIFF file information to stderr.  This information may be useful 
+in debugging TIFF file conversion problems.  
+
+
+
+.UN notes
+.SH NOTES
+
+.UN fillorder
+.SS Fillorder
+.PP
+There is a piece of information in the header of a TIFF image called
+"fillorder." The TIFF specification quite clearly states
+that this value tells the order in which bits are arranged in a byte
+in the description of the image's pixels.  There are two options,
+assuming that the image has a format where more than one pixel can be
+represented by a single byte: 1) the byte is filled from most
+significant bit to least significant bit going left to right in the
+image; and 2) the opposite.
+.PP
+However, there is confusion in the world as to the meaning of
+fillorder.  Evidence shows that some people believe it has to do with
+byte order when a single value is represented by two bytes.
+.PP
+These people cause TIFF images to be created that, while they use a 
+MSB-to-LSB fillorder, have a fillorder tag that says they used LSB-to-MSB.
+A program that properly interprets a TIFF image will not end up with the
+image that the author intended in this case.
+.PP
+For a long time, \fBtifftopnm\fP did not understand fillorder itself
+and assumed the fillorder was MSB-to-LSB regardless of the fillorder
+tag in the TIFF header.  And as far as I know, there is no legitimate
+reason to use a fillorder other than MSB-to-LSB.  So users of
+\fBtifftopnm\fP were happily using those TIFF images that had
+incorrect fillorder tags.
+.PP
+So that those users can continue to be happy, \fBtifftopnm\fP today
+continues to ignore the fillorder tag unless you tell it not to.  (It
+does, however, warn you when the fillorder tag does not say MSB-to-LSB
+that the tag is being ignored).
+.PP
+If for some reason you have a TIFF image that actually has LSB-to-MSB
+fillorder, and its fillorder tag correctly indicates that, you must
+use the \fB-respectfillorder\fP option on \fBtifftopnm\fP to get
+proper results.
+.PP
+Examples of incorrect TIFF images are at 
+.UR ftp://weather.noaa.gov.
+ftp://weather.noaa.gov.
+.UE
+\& They are
+apparently created by a program called \fBfaxtotiff\fP.
+.PP
+This note was written on January 1, 2002.
+
+
+.UN cmyk
+.SS Color Separation (CMYK) TIFFs
+.PP
+Some TIFF images contain color information in CMYK form, whereas PNM
+images use RGB.  There are various formulas for converting between these
+two forms, and \fBtifftopnm\fP can use either of two.
+.PP
+The TIFF library (Version 3.5.4 from libtiff.org) uses
+Y=(1-K)*(1-B) (similar for R and G) in its TIFFRGBAImageGet() service.
+When \fBtifftopnm\fP works in Whole Image mode, it uses that service,
+so that's the conversion you get.
+.PP
+But when \fBtifftopnm\fP runs in Row By Row mode, it does not use
+TIFFRGBAImageGet(), and you get what appears to be more useful:
+Y=1-(B+K).  This is the inverse of what \fBpnmtotiffcmyk\fP does.
+.PP
+See the \fB-byrow\fP option for more information on Whole Image versus
+Row By Row mode.
+.PP
+Before Netpbm 10.21 (March 2004), \fBtifftopnm\fP used the
+Y=(1-K)*(1-B) formula always.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pnmtotiff" (1)\c
+\&,
+.BR "pnmtotiffcmyk" (1)\c
+\&,
+.BR "pamcomp" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN author
+.SH AUTHOR
+.PP
+Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c)
+1990 by Sun Microsystems, Inc.  Author: Patrick J. Naughton (\fInaughton@wind.sun.com\fP).
+.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/tifftopnm.html
+.PP
\ No newline at end of file