commit a67eb3e9010ebafadb4553d430cd91a8a42ae8e7
parent 177d19e34a76175f72efec0315978c0932cf2cb1
Author: lumidify <nobody@lumidify.org>
Date: Sat, 6 Mar 2021 20:19:17 +0100
Add examples to man page
Diffstat:
3 files changed, 67 insertions(+), 26 deletions(-)
diff --git a/CHANGELOG b/CHANGELOG
@@ -2,6 +2,7 @@
* Rewrite using Xlib and Imlib2
* Add command-line options and man pages
* Add automatic resizing of image when resizing window
+* Add croptool_crop
1.0 -> 1.1
* Allow two different selection box colors
diff --git a/croptool.1 b/croptool.1
@@ -1,4 +1,4 @@
-.Dd March 5, 2021
+.Dd March 6, 2021
.Dt CROPTOOL 1
.Os
.Sh NAME
@@ -16,8 +16,8 @@
.Sh DESCRIPTION
.Nm
shows each of the given images and allows a cropping rectangle to be drawn.
-On exit, the cropping command is printed out for each of the files. If a file
-was skipped, nothing is printed out for it.
+On exit, the cropping command is printed out for each of the files.
+If a file was skipped, nothing is printed out for it.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl m
@@ -25,9 +25,9 @@ Disable automatic redrawing when the window is resized (the
.Fl m
stands for 'manual').
This may be useful on older machines that start accelerating global
-warming when the image is redrawn constantly while resizing. Note that
-this also disables exposure events, so the window has to be manually
-redrawn when switching back to it from another window.
+warming when the image is redrawn constantly while resizing.
+Note that this also disables exposure events, so the window has to be
+manually redrawn when switching back to it from another window.
.It Fl r
Disable automatic redrawing while the cropping box is being dragged or
resized, for the same reason as
@@ -36,15 +36,19 @@ resized, for the same reason as
Set the format to be used when the cropping commands are output.
See OUTPUT FORMAT for details.
.It Fl w Ar width
-Set the line width of the cropping rectangle in pixels. Default: 2.
+Set the line width of the cropping rectangle in pixels.
+Default: 2.
.It Fl c Ar padding
-Set the amount of padding used for collision with the mouse in pixels. This
-determines how far away the mouse pointer has to be from an edge or corner
-of the cropping rectangle to collide with it. Default: 10.
+Set the amount of padding used for collision with the mouse in pixels.
+This determines how far away the mouse pointer has to be from an edge
+or corner of the cropping rectangle to collide with it.
+Default: 10.
.It Fl p Ar color
-Set the primary color for the cropping rectangle. Default: #000000.
+Set the primary color for the cropping rectangle.
+Default: #000000.
.It Fl s Ar color
-Set the secondary color for the cropping rectangle. Default: #FFFFFF.
+Set the secondary color for the cropping rectangle.
+Default: #FFFFFF.
.El
.Sh OUTPUT FORMAT
The cropping commands for each image are output using the format given by
@@ -69,8 +73,9 @@ Print the location of the top side of the cropping rectangle in pixels.
.It %b
Print the location of the bottom side of the cropping rectangle in pixels.
.It %f
-Print the filename of the image. Warning: This is printed out as is,
-without any escaping. Yes, this should be fixed.
+Print the filename of the image.
+Warning: This is printed out as is, without any escaping.
+Yes, this should be fixed.
.El
.Pp
If an unknown substitution is encountered, a warning is printed to
@@ -88,31 +93,65 @@ Switch the color of the cropping rectangle between the primary and secondary col
.It DELETE
Delete the cropping rectangle of the current image.
.It SPACE
-Redraw the window. This is useful when automatic redrawing is disabled with
+Redraw the window.
+This is useful when automatic redrawing is disabled with
.Fl m .
.El
.Sh MOUSE ACTIONS
.Bl -tag -width Ds
.It LEFT-CLICK
-When inside an existing cropping rectangle, drag it around. When on one of the
-edges, resize the rectangle, locking it to that dimension. When on one of
-the corners, resize the rectangle regardless of dimension. When outside an
-existing cropping rectangle, start a new cropping rectangle.
+When inside an existing cropping rectangle, drag it around.
+When on one of the edges, resize the rectangle, locking it to that dimension.
+When on one of the corners, resize the rectangle regardless of dimension.
+When outside an existing cropping rectangle, start a new cropping rectangle.
.El
.Sh EXIT STATUS
.Ex -std
+.Sh EXAMPLES
+Normal usage:
+.Bd -literal
+$ croptool *.jpg > tmp.sh
+$ sh tmp.sh
+.Ed
+.Pp
+Or, if you're brave:
+.Bd -literal
+$ croptool *.jpg | sh
+.Ed
+.Pp
+It is also possible to do more advanced things.
+For instance, to put cropped images into a separate directory instead of
+overwriting the original images, something like this can be done:
+.Bd -literal
+$ croptool -f "croptool_crop %wx%h+%l+%t '%f' '/path/to/cropped/%f'" *.jpg | sh
+.Ed
+.Pp
+If more advanced features are needed for the actual cropping (e.g. a
+different output format), other tools such as
+.Xr convert 1
+can be used:
+.Bd -literal
+$ croptool -f 'convert -crop %wx%h+%l+%t "%f" "$(basename "%f" .jpg).png"' *.jpg | sh
+.Ed
+.Pp
+Note that no great care has been taken to deal with filenames containing
+single or double quotes.
+That is left as an exercise to the reader (hint: just don't have
+filenames containing quotes).
.Sh SEE ALSO
+.Xr convert 1 ,
.Xr croptool_crop 1 ,
.Xr mogrify 1
.Sh AUTHORS
.An lumidify Aq Mt nobody@lumidify.org
.Sh BUGS
-The filenames are printed out without any escaping, so filenames with quotes
-may cause issues depending on the output format.
+The filenames are printed out without any escaping, so filenames with
+quotes may cause issues depending on the output format.
.Pp
-Transparent portions of images should probably be shown differently, but I'm
-too lazy to fix that and don't really care at the moment.
+Transparent portions of images should probably be shown differently,
+but I'm too lazy to fix that and don't really care at the moment.
.Pp
-Since the coordinates of the cropping rectangle are stored as integers, they
-will become skewed while resizing. If this becomes a real problem, though,
-you're probably doing something wrong anyways.
+Since the coordinates of the cropping rectangle are stored as integers,
+they will become skewed while resizing.
+If this becomes a real problem, though, you're probably doing something
+wrong anyways.
diff --git a/croptool_crop.1 b/croptool_crop.1
@@ -31,6 +31,7 @@ This program is meant primarily as a companion to
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
+.Xr convert 1 ,
.Xr croptool 1 ,
.Xr mogrify 1
.Sh AUTHORS
