--- OLD/pnm/pnmscale.1	Thu Jan  1 00:00:00 1970
+++ NEW/pnm/pnmscale.1	Thu Jan  1 00:00:00 1970
@@ -1,78 +1,140 @@
-.TH pnmscale 1 "12 January 1991"
-.IX pnmscale
-.SH NAME
-pnmscale - scale a portable anymap
-.SH SYNOPSIS
-.B pnmscale
-.I s
-.RI [ pnmfile ]
+.\" As its sole author, I explicitly place this file in the public domain.
+.\" It may be used by anyone in any way for any purpose, though I would
+.\" appreciate credit where it's due.
+.\"		der Mouse, mouse@rodents.montreal.qc.ca, 2004-03-14
+.Dd March 14, 2004
+.Dt PNMSCALE 1
+.Os NetBSD 1.4
+.Sh NAME
+.Nm pnmscale
+.Nd scale a portable anymap
+.Sh SYNOPSIS
+.Nm
+.Op "shift/bg options"
+.Ar s
+.Op Ar pnmfile
 .br
-.B pnmscale
-.BR -xsize | -width | -ysize |
-.BR -height
-.I s
-.RI [ pnmfile ]
+.Nm
+.Op "shift/bg options"
+.Fl xysize
+.Ar NX
+.Ar NY
+.Op Ar pnmfile
 .br
-.B pnmscale
-.BR -xscale | -yscale
-.I s
-.RI [ pnmfile ]
+.Nm
+.Op "shift/bg options"
+.Fl xyshrink
+.Ar NX
+.Ar NY
+.Op Ar pnmfile
 .br
-.B pnmscale
-.BR -xscale | -xsize | -width
-.I s
-.BR -yscale | -ysize | -height
-.I s
-.RI [ pnmfile ]
+.Nm
+.Op "shift/bg options"
+.Fl pixels
+.Ar N
+.Op Ar pnmfile
 .br
-.B pnmscale -xysize
-.I x y
-.RI [ pnmfile ]
-.br
-.B pnmscale \-pixels
-.I n
-.RI [ pnmfile ]
-.SH DESCRIPTION
-Reads a portable anymap as input.
-Scales it by the specified factor or factors and produces a portable
-anymap as output.
-.IX shrinking
-.IX enlarging
-If the input file is in color, the output will be too,
-otherwise it will be grayscale.
-You can both enlarge (scale factor > 1) and reduce (scale factor < 1).
-.PP
-You can specify one dimension as a pixel size, and the other dimension
-will be scaled correspondingly.
-.PP
-You can specify one dimension as a scale, and the other dimension
-will not be scaled.
-.PP
-You can specify different sizes or scales for each axis.
-.PP
-You can use the special
-.B -xysize
-flag, which fits the image into
-the specified size without changing the aspect ratio.
-.PP
-Or, you can use the
-.B \-pixels
-flag, which fits the image into the specified number of
-pixels without changing the aspect ratio.
-.PP
-All flags can be abbreviated to their shortest unique prefix.
-.PP
-If you enlarge by a factor of 3 or more, you should probably add a
-.I pnmsmooth
-.IX pnmsmooth
-step; otherwise, you can see the original pixels in the resulting image.
-.SH "SEE ALSO"
-pbmreduce(1), pnmenlarge(1), pnmsmooth(1), pnm(5)
-.SH AUTHOR
-Copyright (C) 1989, 1991 by Jef Poskanzer.
-.\" Permission to use, copy, modify, and distribute this software and its
-.\" documentation for any purpose and without fee is hereby granted, provided
-.\" that the above copyright notice appear in all copies and that both that
-.\" copyright notice and this permission notice appear in supporting
-.\" documentation.  This software is provided "as is" without express or
-.\" implied warranty.
+.Nm
+.Op "shift/bg options"
+.Op "scaling options"
+.Op Ar pnmfile
+.Sh DESCRIPTION
+.Nm
+is a tool to scale anymaps.  It can both enlarge and shrink, along one
+or both axes.  You can simply specify a scaling factor,
+.Ar s ,
+one of the special forms
+.D1 Fl xysize Ar NX Ar NY
+.D1 Fl xyshrink Ar NX Ar NY
+.D1 Fl pixels Ar N
+or the more general form, where you can specify a scaling factor or a
+new size for one or both dimensions.
+.Pp
+You can also specify options to shift the image by sub-pixel amounts or
+specify a background colour to be used when an output pixel is not
+entirely covered by the input image.
+.Pp
+If a single scaling factor is supplied, it's used for both dimensions.
+(If this syntax is used, it must be after all other options.)
+Using
+.Fl xysize
+scales the image by the largest factor possible without allowing it to
+exceed the given dimensions; this can either shrink or enlarge the
+image, depending on how the specified size compares to the original
+size.
+.Fl xyshrink
+is the same as
+.Fl xysize
+except that it never enlarges the image.
+.Fl pixels
+scales by the largest factor possible that does not cause it to exceed
+the given number of pixels, except that it never enlarges the image; if
+the pixel count given is larger than the number of pixels in the
+original image, no scaling is done.
+.Pp
+The more general forms consist of the options
+.Fl xsize ,
+.Fl ysize ,
+.Fl xscale ,
+and
+.Fl yscale ,
+with the aliases
+.Fl width
+and
+.Fl height
+available for
+.Fl xsize
+and
+.Fl ysize .
+Specifying a size is equivalent to specifying a scaling factor equal to
+the new size divided by the old size, except as noted below for how it
+affects the other dimension.  Scaling factors can be simple numbers
+(possibly floating-point), with an optional \&% appended to indicate
+division by 100, or a fraction written as two integers with a slash
+between them.  Fractions are obeyed exactly, even when they are not
+representible exactly in machine floating-point.
+.Pp
+When altering one dimension without specifying anything for the other,
+the unspecified dimension is not affected if a scale factor is
+specified, but is scaled by the same factor as the specified dimension
+if a new size is given.  For exmaple, scaling a 200x300 image with
+.Fl xsize Ar 100
+will result in a 100x150 image, whereas using
+.Fl xscale Ar 1/2
+will result in a 100x300 image.  In either case, an explicit mention of
+the other dimension, whether by specifying size or scaling factor,
+overrides this default.
+.Pp
+By default, if the ideal scaled image's size is not an integer number
+of pixels, the effect is as though both images' (0,0) points coincided,
+with an infinite black surround implicitly provided.  This can be
+altered by specifying
+.Fl xshift
+and/or
+.Fl yshift
+to offset the images with respect to one another; the argument to
+either is either an integer/integer fraction or a floating point
+number, either of which may specify any value not less than zero but
+less than one; these specify the position of the input image's (0,0)
+point in the output image's coordinate system.  You can also specify a
+background colour with
+.Fl bg ,
+which takes as argument either as an X11-style hexadecimal colour with
+a
+.Sq \&#
+prefix or as three floating-point numbers from 0 to 1 separated by
+slashes.  Either colour spec may be followed by a slash and a
+floating-point number to specify a transparency value.  This specifies
+the colour of the infinite surround used when an output pixel does not
+fall wholly within the input image.  (Note that most of the netpbm
+tools do not support transparencies; using nonzero transparency will
+produce a nonstandard output file.)
+.Pp
+If the input file is a PBM file, the output file will be PBM or PGM,
+depending on whether any non-integer scaling is involved (if PGM is
+used, the maxval of the generated image is 255).  If the input is PGM
+or PPM, the output is too (the output maxval is the larger of 255 and
+the input maxval).
+.Sh AUTHOR
+der Mouse,
+.Aq mouse@rodents.montreal.qc.ca .