2022-06-18 17:50:57 +02:00
|
|
|
'\" t
|
2022-06-14 10:10:25 +02:00
|
|
|
.ds op \&.\|.\|.\&
|
|
|
|
.
|
|
|
|
.de Sy
|
|
|
|
.SY ctpv
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Ys
|
|
|
|
.YS
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Op
|
|
|
|
.RI [ "\\$1" "]\\$2"
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Om
|
|
|
|
.Op "\\$1" \*(op
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Bsi
|
|
|
|
\&\fB\\$1\fP \fI\\$2\fP\\$3
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Ex
|
2022-06-16 06:12:42 +02:00
|
|
|
.IP
|
2022-06-14 10:10:25 +02:00
|
|
|
.EX
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.de Ee
|
|
|
|
.EE
|
|
|
|
..
|
|
|
|
.
|
|
|
|
.
|
|
|
|
.TH CTPV 1 "June 2022" Linux "User Manuals"
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.SH NAME
|
2022-06-16 06:28:02 +02:00
|
|
|
ctpv \(em terminal previewer
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.
|
|
|
|
.Sy
|
|
|
|
.I file
|
|
|
|
.Op w
|
|
|
|
.Op h
|
|
|
|
.Op x
|
|
|
|
.Op y
|
|
|
|
.Op id
|
|
|
|
.Ys
|
|
|
|
.
|
|
|
|
.Sy
|
|
|
|
.B \-l
|
|
|
|
.Ys
|
|
|
|
.
|
|
|
|
.Sy
|
|
|
|
.B \-m
|
|
|
|
.Om files
|
|
|
|
.Ys
|
|
|
|
.
|
|
|
|
.Sy
|
2022-06-15 20:19:27 +02:00
|
|
|
.RB { \-s | \-c | \-e }
|
2022-06-14 10:10:25 +02:00
|
|
|
.I id
|
|
|
|
.Ys
|
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.
|
|
|
|
.B ctpv
|
|
|
|
is a previewer utility made for integration into other programs.
|
2022-06-14 14:19:18 +02:00
|
|
|
It supports a variety of \(lqpreviews\(rq out of the box,
|
|
|
|
as well as an option to define custom ones.
|
|
|
|
.PP
|
|
|
|
.
|
|
|
|
When
|
|
|
|
.B ctpv
|
2022-06-15 20:19:27 +02:00
|
|
|
is given a file, it determines an appropriate preview for it and
|
|
|
|
runs its script.
|
|
|
|
The script produces preview content and prints it to standard output.
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
2022-06-18 17:50:57 +02:00
|
|
|
.SS Dependencies
|
|
|
|
.
|
|
|
|
All the previews require specific programs to function.
|
|
|
|
If a required program is not found on the system,
|
|
|
|
.B ctpv
|
|
|
|
will try to use another preview.
|
|
|
|
\# This table is auto generated!
|
|
|
|
\# TABLESTART
|
|
|
|
.TS
|
|
|
|
allbox;
|
|
|
|
lb lb
|
|
|
|
l li .
|
|
|
|
File type Programs
|
|
|
|
any T{
|
|
|
|
exiftool cat
|
|
|
|
T}
|
|
|
|
archive T{
|
|
|
|
atool
|
|
|
|
T}
|
|
|
|
diff T{
|
|
|
|
colordiff delta diff-so-fancy
|
|
|
|
T}
|
|
|
|
directory T{
|
|
|
|
ls
|
|
|
|
T}
|
|
|
|
html T{
|
|
|
|
elinks lynx w3m
|
|
|
|
T}
|
|
|
|
image T{
|
|
|
|
ueberzug
|
|
|
|
T}
|
|
|
|
json T{
|
|
|
|
jq
|
|
|
|
T}
|
|
|
|
markdown T{
|
|
|
|
mdcat
|
|
|
|
T}
|
2022-06-18 18:29:15 +02:00
|
|
|
odt T{
|
|
|
|
libreoffice
|
|
|
|
T}
|
2022-06-18 17:50:57 +02:00
|
|
|
pdf T{
|
|
|
|
pdftoppm
|
|
|
|
T}
|
|
|
|
text T{
|
|
|
|
bat cat highlight source-highlight
|
|
|
|
T}
|
|
|
|
torrent T{
|
|
|
|
transmission-show
|
|
|
|
T}
|
|
|
|
video T{
|
|
|
|
ffmpegthumbnailer
|
|
|
|
T}
|
|
|
|
.TE
|
|
|
|
\# TABLEEND
|
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.SS Integration
|
|
|
|
.
|
|
|
|
.TP
|
2022-06-15 20:19:27 +02:00
|
|
|
\fIlf\fP file manager
|
|
|
|
Add this snippet to
|
|
|
|
.I lf
|
|
|
|
configuration file (usually located at
|
|
|
|
.IR \(ti/.config/lf/lfrc ).
|
2022-06-16 00:29:09 +02:00
|
|
|
.PP
|
|
|
|
.
|
2022-06-15 20:19:27 +02:00
|
|
|
.Ex
|
2022-06-14 10:10:25 +02:00
|
|
|
set previewer ctpv
|
|
|
|
set cleaner ctpvclear
|
|
|
|
&ctpv -s $id
|
|
|
|
cmd on-quit $ctpv -e $id
|
2022-06-15 20:19:27 +02:00
|
|
|
.Ee
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
.SS How previews are selected
|
|
|
|
.
|
|
|
|
Initially,
|
|
|
|
.B ctpv
|
|
|
|
retrieves MIME type and extension from
|
|
|
|
.I file
|
2022-06-14 14:19:18 +02:00
|
|
|
passed in the first argument (MIME type is extracted using
|
2022-06-14 10:10:25 +02:00
|
|
|
.BR magic (5)).
|
|
|
|
.PP
|
|
|
|
.
|
|
|
|
Then it creates a list of all previews in a special order,
|
|
|
|
where previews that are more specific appear at the top
|
|
|
|
and more generic ones at the bottom.
|
|
|
|
The list can be viewed by using
|
|
|
|
.B \-l
|
|
|
|
option. The order can be changed, see
|
|
|
|
.IR "Setting priority" .
|
|
|
|
.PP
|
|
|
|
.
|
|
|
|
Finally,
|
|
|
|
.B ctpv
|
|
|
|
goes through the list starting with the first element
|
|
|
|
and checks if a preview matches
|
|
|
|
.IR file \(aqs
|
|
|
|
extension and MIME type.
|
2022-06-14 14:19:18 +02:00
|
|
|
If it does, it runs a preview script.
|
2022-06-14 10:10:25 +02:00
|
|
|
If the script exits with status 127
|
|
|
|
(which usually means that a command was not found),
|
|
|
|
the next appropriate preview is selected, and so on.
|
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH OPTIONS
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.B \-l
|
|
|
|
List all previews.
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.Bsi \-m files \*(op
|
|
|
|
Print extension and MIME type of specified files.
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.Bsi \-s id
|
|
|
|
Start server with ID
|
|
|
|
.IR id .
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.Bsi \-c id
|
|
|
|
Send
|
|
|
|
.B clear
|
|
|
|
command to server with ID
|
|
|
|
.I id
|
|
|
|
(usually, it removes image from terminal).
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.Bsi \-e id
|
|
|
|
Kill server with ID
|
|
|
|
.IR id .
|
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH CONFIGURATION
|
|
|
|
.
|
2022-06-15 20:19:27 +02:00
|
|
|
.B ctpv
|
|
|
|
uses a configuration file usually located at
|
|
|
|
.IR \(ti/.config/ctpv/config
|
|
|
|
(see
|
|
|
|
.IR FILES ).
|
|
|
|
Its format somewhat resembles one used by
|
2022-06-14 10:10:25 +02:00
|
|
|
.IR lf .
|
2022-06-15 20:19:27 +02:00
|
|
|
There are several \(lqcommands\(rq that can be used to change
|
|
|
|
previews or set different settings.
|
2022-06-14 10:10:25 +02:00
|
|
|
Commands are separated by newlines.
|
|
|
|
Comments start with number sign
|
|
|
|
.RB ( # )
|
|
|
|
like in many other formats.
|
|
|
|
.
|
|
|
|
.SS Defining custom previews
|
|
|
|
.
|
|
|
|
A snippet below defines a new preview with name
|
|
|
|
.I cow
|
|
|
|
that applies to files with extension
|
|
|
|
.IR .moo .
|
|
|
|
A preview itself is a shell script enclosed within double curly
|
|
|
|
braces (this particular one utilizes the famous
|
|
|
|
.I cowsay
|
|
|
|
program):
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
preview cow .moo {{
|
2022-06-15 20:43:23 +02:00
|
|
|
\& cowsay < "$f"
|
2022-06-14 10:10:25 +02:00
|
|
|
}}
|
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
Running
|
|
|
|
.I "ctpv\ file.moo"
|
|
|
|
where
|
|
|
|
.I file.moo
|
|
|
|
contains \(lqsome text\(rq will produce the following output:
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
\# ___________
|
|
|
|
\# < some text >
|
|
|
|
\# -----------
|
|
|
|
\# \ ^__^
|
|
|
|
\# \ (oo)\_______
|
|
|
|
\# (__)\ )\/\
|
|
|
|
\# ||----w |
|
|
|
|
\# || ||
|
2022-06-15 20:43:23 +02:00
|
|
|
\&\ \(ul\(ul\(ul\(ul\(ul\(ul\(ul\(ul\(ul\(ul\(ul\
|
|
|
|
\&<\ some\ text\ >
|
|
|
|
\&\ \(mi\(mi\(mi\(mi\(mi\(mi\(mi\(mi\(mi\(mi\(mi\
|
|
|
|
\&\ \ \ \ \ \ \ \ \(rs\ \ \ ^\(ul\(ul^
|
|
|
|
\&\ \ \ \ \ \ \ \ \ \(rs\ \ (oo)\(rs\(ul\(ul\(ul\(ul\(ul\(ul\(ul
|
|
|
|
\&\ \ \ \ \ \ \ \ \ \ \ \ (\(ul\(ul)\(rs\ \ \ \ \ \ \ )\(rs/\(rs
|
|
|
|
\&\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\(mi\(mi\(mi\(miw\ |
|
|
|
|
\&\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ ||
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
Variable
|
|
|
|
.B $f
|
|
|
|
stores
|
|
|
|
.IR file
|
|
|
|
that was passed as a first argument to
|
|
|
|
.BR ctpv .
|
|
|
|
It's strongly suggested to enclose
|
|
|
|
.B $f
|
|
|
|
with double quotes
|
|
|
|
.RB ( \(dq$f\(dq )
|
|
|
|
because otherwise the script will not work as
|
|
|
|
expected if
|
|
|
|
.B $f
|
|
|
|
stores a filename with whitespace.
|
|
|
|
.PP
|
|
|
|
.
|
|
|
|
There are other variables that are exported into preview
|
|
|
|
script environment:
|
|
|
|
.BR $w ,
|
|
|
|
.BR $h ,
|
|
|
|
.BR $x ,
|
|
|
|
.BR $y
|
|
|
|
and
|
|
|
|
.BR $id .
|
|
|
|
However, they are rarely used even by built-in previews and
|
|
|
|
are only set if corresponding arguments were passed to
|
|
|
|
.B ctpv
|
|
|
|
command (see
|
|
|
|
.IR SYNOPSIS ).
|
|
|
|
.PP
|
|
|
|
.
|
|
|
|
You can specify MIME type instead of filename extension
|
|
|
|
in preview definition:
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
preview json_example application/json {{
|
2022-06-15 20:43:23 +02:00
|
|
|
\& # preview json files
|
2022-06-14 10:10:25 +02:00
|
|
|
}}
|
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
And you also can omit subtype part of the MIME type
|
|
|
|
by replacing it with
|
|
|
|
.BR * .
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
preview any_text_example text/* {{
|
2022-06-15 20:43:23 +02:00
|
|
|
\& # this one applies to all text files
|
2022-06-14 10:10:25 +02:00
|
|
|
}}
|
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
Setting subtype to
|
|
|
|
.B *
|
2022-06-14 14:19:18 +02:00
|
|
|
will make the preview above work for any file which MIME type starts with
|
2022-06-14 10:10:25 +02:00
|
|
|
.BR text/ .
|
|
|
|
.
|
|
|
|
.SS Setting priority
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
If there are several previews that apply to the same file type,
|
|
|
|
only the top one in the list is chosen (see
|
|
|
|
.IR "How previews are selected" ).
|
|
|
|
To alter this behavior, you can use
|
|
|
|
.B priority
|
|
|
|
command to change preview priority:
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
priority cat
|
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
The snippet above sets priority of preview named \(lqcat\(rq to 1,
|
|
|
|
thus now it's used for all text files.
|
|
|
|
It's possible to specify an integer as the second argument
|
|
|
|
to set priority other than 1 (may also be negative).
|
|
|
|
.
|
|
|
|
.SS Removing previews
|
|
|
|
.
|
|
|
|
.B remove
|
|
|
|
command simply removes a preview (also works for built-in ones):
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-16 00:29:09 +02:00
|
|
|
.
|
2022-06-14 10:10:25 +02:00
|
|
|
.Ex
|
|
|
|
remove cat
|
|
|
|
.Ee
|
2022-06-15 20:19:27 +02:00
|
|
|
.PP
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH FILES
|
|
|
|
.
|
|
|
|
.TP
|
|
|
|
.I $XDG_CONFIG_HOME/ctpv/config
|
|
|
|
Configuration file. If
|
|
|
|
.I $XDG_CONFIG_HOME
|
2022-06-15 20:19:27 +02:00
|
|
|
is not set, defaults to
|
|
|
|
.IR \(ti/.config .
|
2022-06-14 10:10:25 +02:00
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.
|
|
|
|
.BR lf (1)
|
|
|
|
.
|
|
|
|
.
|
|
|
|
.SH AUTHOR
|
|
|
|
.
|
|
|
|
Written by Nikita Ivanov.
|