[Pkg-gmagick-im-team] Bug#1100665: import-im7.q16.1: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sun Mar 16 22:14:55 GMT 2025
Package: imagemagick-7.q16
Version: 8:7.1.1.43+dfsg1-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:13: style: 2 leading space(s) on input line
[...]
troff:<stdin>:54: warning: trailing space in the line
[...]
troff:<stdin>:78: warning: trailing space in the line
[...]
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.17-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages imagemagick-7.q16 depends on:
ii hicolor-icon-theme 0.18-2
ii libc6 2.41-4
ii libmagickcore-7.q16-10 8:7.1.1.43+dfsg1-1
ii libmagickwand-7.q16-10 8:7.1.1.43+dfsg1-1
Versions of packages imagemagick-7.q16 recommends:
ii ghostscript 10.04.0~dfsg-2+b1
pn libmagickcore-7.q16-10-extra <none>
ii netpbm 2:11.09.03-1
Versions of packages imagemagick-7.q16 suggests:
pn autotrace <none>
pn cups-bsd | lpr | lprng <none>
ii curl 8.12.1-3
pn enscript <none>
pn ffmpeg <none>
pn gimp <none>
pn gnuplot <none>
pn grads <none>
pn graphviz <none>
ii groff-base 1.23.0-7
pn hp2xx <none>
pn html2ps <none>
pn imagemagick-7-doc <none>
pn libraw-bin <none>
pn libwmf-bin <none>
pn mplayer <none>
pn povray <none>
pn radiance <none>
pn sane-utils <none>
ii texlive-binaries [texlive-base-bin] 2024.20240313.70630+ds-5+b1
pn transfig <none>
ii xdg-utils 1.2.1-2
-- no debconf information
-------------- next part --------------
A non-text attachment was scrubbed...
Name: chk_man.err.import-im7.q16.1
Type: application/javascript
Size: 35616 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/pkg-gmagick-im-team/attachments/20250316/5242d668/attachment-0001.js>
-------------- next part --------------
--- import-im7.q16.1 2025-03-15 21:43:31.959790889 +0000
+++ import-im7.q16.1.new 2025-03-16 13:11:19.333450074 +0000
@@ -1,101 +1,157 @@
-.TH import-im7.q16 1 "Date: 2009/01/10 01:00:00" "ImageMagick"
+.TH import-im7.q16 1 "Date: 2009/01/10 01:00:00" ImageMagick
.SH NAME
-import \- saves any visible window on an X server and outputs it as an image file. You can capture a single window, the entire screen, or any rectangular portion of the screen. The window to capture is selected by clicking the desired window or a program option.
+import \- saves any visible window on an X server and outputs it as an
+image file.
+You can capture a single window,
+the entire screen,
+or any rectangular portion of the screen.
+The window to capture is selected by clicking the desired window
+or a program option.
.SH SYNOPSIS
.TP
\fBmagick-im7.q16 import\fP [\fIoptions\fP] \fIoutput-file\fP
.SH OVERVIEW
-The \fBimport-im7.q16\fP program is a member of the ImageMagick-ims7.q16(1) suite of tools. Use it to capture some or all of an X server screen and save the image to a file.
-
-For more information about the import command, point your browser to file:///usr/share/doc/imagemagick-7-common/html/www/import.html (on debian system you may install the imagemagick-7 package) or https://www.imagemagick.org/script/import.php.
+The \fBimport-im7.q16\fP program is a member of the
+.BR ImageMagick-ims7.q16 (1)
+suite of tools.
+Use it to capture some
+or all of an X server screen
+and save the image to a file.
+
+For more information about the import command,
+point your browser to
+.br
+file:///usr/share/doc/imagemagick\-7\-common/html/www/import.html
+(on debian system you may install the imagemagick-7 package)
+or
+https://www.imagemagick.org/script/import.php.
.SH DESCRIPTION
-Image Settings:
- \-adjoin join images into a single multi-image file
- \-border include window border in the output image
- \-colorspace type alternate image colorspace
- \-comment string annotate image with comment
- \-compress type type of pixel compression when writing the image
- \-define format:option
- define one or more image format options
- \-density geometry horizontal and vertical density of the image
- \-depth value image depth
- \-descend obtain image by descending window hierarchy
- \-display server X server to contact
- \-dispose method layer disposal method
- \-dither method apply error diffusion to image
- \-delay centiseconds display the next image after pausing
- \-encipher filename convert plain pixels to cipher pixels
- \-endian type endianness (MSB or LSB) of the image
- \-encoding type text encoding type
- \-filter type use this filter when resizing an image
- \-format "string" output formatted image characteristics
- \-frame include window manager frame
- \-gravity direction which direction to gravitate towards
- \-identify identify the format and characteristics of the image
- \-interlace type None, Line, Plane, or Partition
- \-interpolate method pixel color interpolation method
- \-label string assign a label to an image
- \-limit type value Area, Disk, Map, or Memory resource limit
- \-monitor monitor progress
- \-page geometry size and location of an image canvas
- \-pause seconds seconds delay between snapshots
- \-pointsize value font point size
- \-quality value JPEG/MIFF/PNG compression level
- \-quiet suppress all warning messages
- \-regard-warnings pay attention to warning messages
- \-repage geometry size and location of an image canvas
- \-respect-parentheses settings remain in effect until parenthesis boundary
- \-sampling-factor geometry
- horizontal and vertical sampling factor
- \-scene value image scene number
- \-screen select image from root window
- \-seed value seed a new sequence of pseudo-random numbers
- \-set property value set an image property
- \-silent operate silently, i.e. don't ring any bells
- \-snaps value number of screen snapshots
- \-support factor resize support: > 1.0 is blurry, < 1.0 is sharp
- \-synchronize synchronize image to storage device
- \-taint declare the image as modified
- \-transparent-color color
- transparent color
- \-treedepth value color tree depth
- \-verbose print detailed information about the image
- \-virtual-pixel method
- Constant, Edge, Mirror, or Tile
- \-window id select window with this id or name
- root selects the whole screen
-
-Image Operators:
- \-annotate geometry text
- annotate the image with text
- \-channel mask set the image channel mask
- \-colors value preferred number of colors in the image
- \-crop geometry preferred size and location of the cropped image
- \-extent geometry set the image size
- \-geometry geometry preferred size or location of the image
- \-help print program options
- \-monochrome transform image to black and white
- \-negate replace each pixel with its complementary color
- \-quantize colorspace reduce colors in this colorspace
- \-resize geometry resize the image
- \-rotate degrees apply Paeth rotation to the image
- \-strip strip image of all profiles and comments
- \-thumbnail geometry create a thumbnail of the image
- \-transparent color make this color transparent within the image
- \-trim trim image edges
- \-type type image type
-
+.TS
+l l .
+Image Settings: \&
+\-adjoin join images into a single multi-image file
+\-border include window border in the output image
+\-colorspace type alternate image colorspace
+\-comment string annotate image with comment
+\-compress type type of pixel compression when writing the image
+\-define format:option define one or more image format options
+\-density geometry horizontal and vertical density of the image
+\-depth value image depth
+\-descend obtain image by descending window hierarchy
+\-display server X server to contact
+\-dispose method layer disposal method
+\-dither method apply error diffusion to image
+\-delay centiseconds display the next image after pausing
+\-encipher filename convert plain pixels to cipher pixels
+\-endian type endianness (MSB or LSB) of the image
+\-encoding type text encoding type
+\-filter type use this filter when resizing an image
+\-format "string" output formatted image characteristics
+\-frame include window manager frame
+\-gravity direction which direction to gravitate towards
+\-identify T{
+identify the format and characteristics of the image
+T}
+\-interlace type None, Line, Plane, or Partition
+\-interpolate method pixel color interpolation method
+\-label string assign a label to an image
+\-limit type value Area, Disk, Map, or Memory resource limit
+\-monitor monitor progress
+\-page geometry size and location of an image canvas
+\-pause seconds seconds delay between snapshots
+\-pointsize value font type size
+\-quality value JPEG/MIFF/PNG compression level
+\-quiet suppress all warning messages
+\-regard-warnings pay attention to warning messages
+\-repage geometry size and location of an image canvas
+\-respect-parentheses T{
+settings remain in effect until parenthesis boundary
+T}
+.TE
+.TS
+l l .
+\-sampling-factor geometry horizontal and vertical sampling factor
+.TE
+.TS
+l l .
+\-scene value image scene number
+\-screen select image from root window
+\-seed value seed a new sequence of pseudo-random numbers
+\-set property value set an image property
+\-silent operate silently, i.e.\& don't ring any bells
+\-snaps value number of screen snapshots
+\-support factor resize support: > 1.0 is blurry, < 1.0 is sharp
+\-synchronize synchronize image to storage device
+\-taint declare the image as modified
+.TE
+.TS
+l l .
+\-transparent-color color transparent color
+.TE
+.TS
+l l .
+\-treedepth value color tree depth
+\-verbose print detailed information about the image
+\-virtual-pixel method Constant, Edge, Mirror, or Tile
+\-window id T{
+select window with this id or name root selects the whole screen
+T}
+.TE
+
+.TS
+l l .
+Image Operators: \&
+\-annotate geometry text annotate the image with text
+.TE
+.TS
+l l .
+\-channel mask set the image channel mask
+\-colors value preferred number of colors in the image
+\-crop geometry preferred size and location of the cropped image
+\-extent geometry set the image size
+\-geometry geometry preferred size or location of the image
+\-help print program options
+\-monochrome transform image to black and white
+\-negate replace each pixel with its complementary color
+\-quantize colorspace reduce colors in this colorspace
+\-resize geometry resize the image
+\-rotate degrees apply Paeth rotation to the image
+\-strip strip image of all profiles and comments
+\-thumbnail geometry create a thumbnail of the image
+\-transparent color make this color transparent within the image
+\-trim trim image edges
+\-type type image type
+.TE
+
+.TS
+l s
+l l .
Miscellaneous Options:
- \-debug events display copious debugging information
- \-help print program options
- \-log format format of debugging information
- \-list type print a list of supported option arguments
- \-version print version information
-
-By default, 'file' is written in the Postscript image format. To specify a particular image format, precede the filename with an image format name and a colon (i.e. ps:image) or specify the image type as the filename suffix (i.e. image.ps). Specify 'file' as '-' for standard input or output.
+\-debug events display copious debugging information
+\-help print program options
+\-log format format of debugging information
+\-list type print a list of supported option arguments
+\-version print version information
+.TE
+
+By default, 'file' is written in the Postscript image format.
+To specify a particular image format,
+precede the filename with an image format name
+and a colon
+(i.e.\& ps:image)
+or specify the image type as the filename suffix
+(i.e.\& image.ps).
+Specify 'file' as '\-' for standard input or output.
.SH SEE ALSO
-ImageMagick-im7.q16(1)
+.BR ImageMagick-im7.q16 (1)
.SH COPYRIGHT
-
-\fBCopyright (C) 1999-2021 ImageMagick Studio LLC. Additional copyrights and licenses apply to this software, see file:///usr/share/doc/imagemagick-7-common/html/www/license.html (on debian system you may install the imagemagick-7 package) or https://www.imagemagick.org/script/license.php\fP
+\fBCopyright (C) 1999\(en2021 ImageMagick Studio LLC.
+Additional copyrights
+and licenses apply to this software,
+see
+.br
+file:///usr/share/doc/imagemagick\-7\-common/html/www/license.html (on
+debian system you may install the imagemagick-7 package) or
+.br
+https://www.imagemagick.org/script/license.php\fP
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
More information about the Pkg-gmagick-im-team
mailing list