Skip to content

Commit b3ef1ab

Browse files
bhepplebhepple
authored
Document new options (#1)
1 parent eb7cced commit b3ef1ab

File tree

1 file changed

+154
-44
lines changed

1 file changed

+154
-44
lines changed

‎docs/clipman.1

Lines changed: 154 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,36 @@
1-
.TH clipman 1 1.6.2 ""
1+
'\" t
2+
.TH clipman 1
23
.SH "NAME"
3-
clipman
4+
clipman \- a clipboard manager for Wayland
45
.SH "SYNOPSIS"
5-
.TP
6-
\fBclipman [<flags>] <command> [<args> ...]\fR
7-
6+
.B clipman
7+
[<options>] <command> [<args> ...]
88
.SH "DESCRIPTION"
9-
A clipboard manager for Wayland
9+
A basic clipboard manager for Wayland, with support for persisting copy buffers after an application exits.
1010
.SH "OPTIONS"
1111
.TP
12-
\fB-h, --help\fR
13-
Show context-sensitive help (also try --help-long and --help-man).
12+
\fB\-h\fR, \fB\-\-help\fR
13+
Show context\-sensitive help (also try
14+
.B \-\-help\-long
15+
and
16+
.BR \-\-help\-man ).
1417
.TP
15-
\fB--histpath="~/.local/share/clipman.json"\fR
18+
\fB\-\-histpath="~/.local/share/clipman.json"\fR
1619
Path of history file
1720
.TP
18-
\fB--primary\fR
19-
Serve item to the primary clipboard. Default: --no-primary
21+
\fB\-\-primary\fR
22+
Serve item to the primary clipboard. Default: \-\-no\-primary
2023
.TP
21-
\fB--notify\fR
24+
\fB\-\-notify\fR
2225
Send desktop notifications on errors
2326
.TP
24-
\fB-v, --version\fR
27+
\fB\-\-err\-on\-no\-selection\fR
28+
exit with an exit 1 when no selection is made in the picker.
29+
.TP
30+
\fB\-\-min\-char\fR
31+
minimum number of characters before storing
32+
.TP
33+
\fB\-v, \-\-version\fR
2534
Show application version.
2635
.SH "COMMANDS"
2736
.SS
@@ -31,79 +40,180 @@ Show help.
3140
.SS
3241
\fBstore [<flags>]\fR
3342
.PP
34-
Record clipboard events (run as argument to `wl-paste --watch`)
43+
Record clipboard events (run as argument to `wl\-paste \-\-watch`)
3544
.TP
36-
\fB--max-items=15\fR
45+
\fB\-\-max\-items=15\fR
3746
history size
3847
.TP
39-
\fB-P, --no-persist\fR
48+
\fB\-P, \-\-no\-persist\fR
4049
Don't persist a copy buffer after a program exits
4150
.TP
42-
\fB--unix\fR
51+
\fB\-\-unix\fR
4352
Normalize line endings to LF
4453
.SS
45-
\fBpick --tool=TOOL [<flags>]\fR
54+
\fBpick \-\-tool=TOOL [<flags>]\fR
4655
.PP
4756
Pick an item from clipboard history
4857
.TP
49-
\fB--max-items=15\fR
58+
\fB\-\-max\-items=15\fR
5059
scrollview length
5160
.TP
52-
\fB-t, --tool=TOOL\fR
61+
\fB\-t, \-\-tool=TOOL\fR
5362
Which selector to use: wofi/bemenu/CUSTOM/STDOUT
5463
.TP
55-
\fB-T, --tool-args=""\fR
56-
Extra arguments to pass to the --tool
64+
\fB\-T, \-\-tool\-args=""\fR
65+
Extra arguments to pass to the \-\-tool
5766
.TP
58-
\fB--print0\fR
59-
Separate items using NULL; recommended if your tool supports --read0 or similar
67+
\fB\-\-print0\fR
68+
Separate items using NULL; recommended if your tool supports \-\-read0 or similar
6069
.SS
6170
\fBclear [<flags>]\fR
6271
.PP
6372
Remove item/s from history
6473
.TP
65-
\fB--max-items=15\fR
74+
\fB\-\-max\-items=15\fR
6675
scrollview length
6776
.TP
68-
\fB-t, --tool=TOOL\fR
77+
\fB\-t, \-\-tool=TOOL\fR
6978
Which selector to use: wofi/bemenu/CUSTOM/STDOUT
7079
.TP
71-
\fB-T, --tool-args=""\fR
72-
Extra arguments to pass to the --tool
80+
\fB\-T, \-\-tool\-args=""\fR
81+
Extra arguments to pass to the
82+
.B \-\-tool
7383
.TP
74-
\fB-a, --all\fR
84+
\fB\-a, \-\-all\fR
7585
Remove all items
7686
.TP
77-
\fB--print0\fR
78-
Separate items using NULL; recommended if your tool supports --read0 or similar
87+
\fB\-\-print0\fR
88+
Separate items using NULL; recommended if your tool supports
89+
.B \-\-read0
90+
or similar
7991
.SS
8092
\fBrestore\fR
8193
.PP
8294
Serve the last recorded item from history
83-
\fBshow-history\fR
84-
.PP
95+
.SS
96+
\fBshow\-history\fR
8597
Show all items from history
8698
.SH "USAGE"
87-
Run the binary in your Sway session by adding `exec wl-paste -t text --watch clipman store` (or `exec wl-paste -t text --watch clipman store 1>> PATH/TO/LOGFILE 2>&1 &` to log errors) at the beginning of your config. It is highly recommended that you run clipman with the `--no-persist` option, see Known Issues.
88-
.PP
89-
For primary clipboard support, also add `exec wl-paste -p -t text --watch clipman store -P --histpath="~/.local/share/clipman-primary.json` (note that both the `-p` in wl-paste and the `-P` in clipman are mandatory in this case).
99+
Run the binary in your Sway session by adding to your config:
100+
.nf
101+
\&
102+
.in +4m
103+
.B exec wl\-paste \-t text \-\-watch clipman store
104+
.in
105+
\&
106+
.fi
107+
or to log errors:
108+
.nf
109+
\&
110+
.in +4m
111+
.B exec wl\-paste \-t text \-\-watch clipman store \e
112+
.in +4m
113+
.B 1>> PATH/TO/LOGFILE 2>&1
114+
.in -4m
115+
.in -4m
116+
\&
117+
.fi
118+
It is highly recommended that you run clipman with the
119+
.B \-\-no\-persist
120+
option, see
121+
.BR "KNOWN ISSUES" .
90122
.PP
91-
To query the history and select items, run the binary as `clipman pick -t wofi`. You can assign it to a keybinding: `bindsym $mod+h exec clipman pick -t wofi`.
92-
You can pass additional arguments to the selector like this: `clipman pick --tool wofi -T'--prompt=my-prompt -i'` (both `--prompt` and `-i` are flags of wofi).
93-
You can use a custom selector like this: `clipman pick --print0 --tool=CUSTOM --tool-args="fzf --prompt 'pick > ' --bind 'tab:up' --cycle --read0"`.
123+
For primary clipboard support, also add:
124+
.nf
125+
\&
126+
.in +4m
127+
.B exec wl\-paste \-p \-t text \-\-watch clipman store \-P \e
128+
.in +4m
129+
.B \-\-histpath="~/.local/share/clipman\-primary.json"
130+
.in -4m
131+
.in -4m
132+
\&
133+
.fi
134+
note that both the `\-p` in wl\-paste and the `\-P` in clipman are mandatory in this case.
94135
.PP
95-
To remove items from history, `clipman clear -t wofi` and `clipman clear --all`.
136+
To query the history and select items, run the binary as
137+
.nf
138+
\&
139+
.in +4m
140+
.B clipman pick \-t wofi
141+
.in
142+
\&
143+
.fi
144+
You can assign it to a keybinding:
145+
.nf
146+
\&
147+
.in +4m
148+
.B bindsym $mod+h exec clipman pick \-t wofi
149+
.in
150+
\&
151+
.fi
152+
You can pass additional arguments to the selector like this:
153+
.nf
154+
\&
155+
.in +4m
156+
.B clipman pick \-\-tool wofi \-T'\-\-prompt=my\-prompt \-i'
157+
.in
158+
\&
159+
.fi
160+
both `\-\-prompt` and `\-i` are flags of wofi.
96161
.PP
97-
To serve the last history item at startup, add `exec clipman restore` to your Sway config.
162+
You can use a custom selector like this:
163+
.nf
164+
\&
165+
.in +4m
166+
.B clipman pick \-\-print0 \-\-tool=CUSTOM \-\-tool\-args= \e
167+
.in +4m
168+
\fB"fzf \-\-prompt 'pick > ' \-\-bind 'tab:up' \-\-cycle \-\-read0"\fR
169+
.in -4m
170+
.in -4m
171+
\&
172+
.fi
173+
To only paste if there's something selected:
174+
.nf
175+
\&
176+
.in +4m
177+
\fBbindsym $mod+v exec "clipman pick \-t wofi \-\-err\-on\-no\-selection \e
178+
.in +4m
179+
&& wtype \-M ctrl \-M shift v"\fR
180+
.in -4m
181+
.in -4m
182+
\&
183+
.fi
184+
To remove items from history:
185+
.nf
186+
\&
187+
.in +4m
188+
.B clipman clear \-t wofi
189+
.br
190+
.B clipman clear \-\-all
191+
.in
192+
\&
193+
.fi
194+
To serve the last history item at startup, add this to your Sway config:
195+
.nf
196+
\&
197+
.in +4m
198+
.B exec clipman restore
199+
.in
200+
\&
201+
.fi
98202
.SH "BUGS"
99203
.PP
100-
When you experience a clipboard-related bug, try to see if it still happens without clipman running, as it's more likely to be caused by one of our own known issues rather than wl-clipboard.
204+
When you experience a clipboard\-related bug, try to see if it still happens without clipman running, as it's more likely to be caused by one of our own known issues rather than wl\-clipboard.
101205
.SH "KNOWN ISSUES"
102206
.PP
103207
We only support plain text.
104208
.PP
105209
By default, we continue serving the last copied item even after its owner has exited.
106-
This means that, unless you run with the `--no-persist` option, you'll always immediately lose rich content;
210+
This means that, unless you run with the
211+
.B \-\-no\-persist
212+
option, you'll always immediately lose rich content;
107213
for example: vim's visual block mode breaks; copying images in Firefox breaks; if you copy a bookmark in Firefox, you won't be able to paste it in another bookmark folder; if you copy formatted text inside Libre Office you'll lose all formatting on paste.
108214
.PP
109-
Run `clipman store` with the `--no-persist` option if you are affected. Unfortunately, it seems that there is no way to make them play well together.
215+
Run
216+
.B clipman store
217+
with the
218+
.B \-\-no\-persist
219+
option if you are affected. Unfortunately, it seems that there is no way to make them play well together.

0 commit comments

Comments
 (0)