grimshot: Add a man page

3 files changed, 168 insertions, 7 deletions

diff --git a/contrib/grimshot b/contrib/grimshot
index ed32334b..08a5fd1b 100755
--- a/contrib/grimshot
+++ b/contrib/grimshot
@@ -11,13 +11,7 @@
 ##  - `mktemp`: to create a temporary file
 ## Those are needed to be installed, if unsure, run `grimshot check`
 ##
-## Examples:
-## `grimshot copy win` - to copy current window
-## `grimshot save area` - to select area and save it to default file (Pictures/Grimshot-$datetime.png)
-## `grimshot save screen ~/screenshot.png` - to save screenshot under ~/screenshot.png
-## `grimshot save output ~/screenshot.png` - to save screenshot under ~/screenshot.png
-## `grimshot` - usage
-## `grimshot check` - verify if tools are installed
+## See `man 1 grimshot` or `grimshot usage` for further details.
 
 getTargetDirectory() {
   test -f ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs && \
diff --git a/contrib/grimshot.1 b/contrib/grimshot.1
new file mode 100644
index 00000000..6e764007
--- /dev/null
+++ b/contrib/grimshot.1
@@ -0,0 +1,96 @@
+.\" Generated by scdoc 1.10.1
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "grimshot" "1" "2020-05-05"
+.P
+.SH NAME
+.P
+grimshot - a helper for screenshots within sway
+.P
+.SH DESCRIPTION
+.P
+grimshot [--notify] (copy|save) [TARGET] [FILE]
+grimshot check
+grimshot usage
+.P
+\fB--notify\fR
+.RS 4
+Show notifications to the user that a screenshot has been taken.
+.P
+.RE
+\fBsave\fR
+.RS 4
+Save the screenshot into a regular file. Grimshot will write images
+files to \fB$XDG_SCREENSHOTS_DIR\fR if this is set (or defined
+in `user-dirs.dir`), or otherwise fall back to `$XDG_PICTURES_DIR`
+.P
+.RE
+\fBcopy\fR
+.RS 4
+Copy the screenshot data (as image/png) into the clipboard.
+.P
+.RE
+.SH SYNOPSIS
+.P
+Grimshot is an easy to use screenshot tool for sway. It relies on grim, slurp
+and jq to do the heavy lifting, and mostly provides an easy to use interface.
+.P
+A recommended usage pattern is to just bind this to Super+P via sway:
+.P
+.nf
+.RS 4
+# Screenshots:
+# Cmd+P: Current window
+# Cmd+Shift+p: Select region
+# Cmd+Alt+p Current output
+# Cmd+Ctrl+p Select a window
+
+bindsym Mod4+p       exec grimshot active
+bindsym Mod4+Shift+p exec grimshot region
+bindsym Mod4+Mod1+p  exec grimshot output
+bindsym Mod4+Ctrl+p  exec grimshot window
+.fi
+.RE
+.P
+.SH TARGETS
+.P
+grimshot can capture the following named targets:
+.P
+\fIactive\fR
+.RS 4
+Captures the currently active window.
+.P
+.RE
+\fIscreen\fR
+.RS 4
+Captures the entire screen. This includes all visible outputs.
+.P
+.RE
+\fIregion\fR
+.RS 4
+Allows manually selecting a rectangular region, and captures that.
+.P
+.RE
+\fIwindow\fR
+.RS 4
+Allows manually selecting a single window (by clicking on it), and
+captures it.
+.P
+.RE
+\fIoutput\fR
+.RS 4
+Captures the currently active output.
+.P
+.RE
+.SH OUTPUT
+.P
+Grimshot will always print the filename of the captured screenshot to
+stdout.
+.P
+.SH SEE ALSO
+.P
+\fBgrim\fR(1)
diff --git a/contrib/grimshot.1.scd b/contrib/grimshot.1.scd
new file mode 100644
index 00000000..afc6362e
--- /dev/null
+++ b/contrib/grimshot.1.scd
@@ -0,0 +1,71 @@
+grimshot(1)
+
+# NAME
+
+grimshot - a helper for screenshots within sway
+
+# DESCRIPTION
+
+grimshot [--notify] (copy|save) [TARGET] [FILE]
+grimshot check
+grimshot usage
+
+*--notify*
+	Show notifications to the user that a screenshot has been taken.
+
+*save*
+	Save the screenshot into a regular file. Grimshot will write images
+	files to *$XDG_SCREENSHOTS_DIR* if this is set (or defined
+	in `user-dirs.dir`), or otherwise fall back to `$XDG_PICTURES_DIR`
+
+*copy*
+	Copy the screenshot data (as image/png) into the clipboard.
+
+# SYNOPSIS
+
+Grimshot is an easy to use screenshot tool for sway. It relies on grim, slurp
+and jq to do the heavy lifting, and mostly provides an easy to use interface.
+
+A recommended usage pattern is to just bind this to Super+P via sway:
+
+```
+# Screenshots:
+# Cmd+P: Current window
+# Cmd+Shift+p: Select region
+# Cmd+Alt+p Current output
+# Cmd+Ctrl+p Select a window
+
+bindsym Mod4+p       exec grimshot active
+bindsym Mod4+Shift+p exec grimshot region
+bindsym Mod4+Mod1+p  exec grimshot output
+bindsym Mod4+Ctrl+p  exec grimshot window
+```
+
+# TARGETS
+
+grimshot can capture the following named targets:
+
+_active_
+	Captures the currently active window.
+
+_screen_
+	Captures the entire screen. This includes all visible outputs.
+
+_region_
+	Allows manually selecting a rectangular region, and captures that.
+
+_window_
+	Allows manually selecting a single window (by clicking on it), and
+	captures it.
+
+_output_
+	Captures the currently active output.
+
+# OUTPUT
+
+Grimshot will always print the filename of the captured screenshot to
+stdout.
+
+# SEE ALSO
+
+*grim*(1)