ctpv/doc/ctpv.1

'\" t
.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
.IP
.EX
..
.
.de Ee
.EE
..
.
.
.TH CTPV 1 "June 2022" Linux "User Manuals"
.
.SH NAME
ctpv \(em terminal previewer
.
.
.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
.RB { \-s | \-c | \-e }
.I id
.Ys
.
.
.SH DESCRIPTION
.
.B ctpv
is a previewer utility made for integration into other programs.
It supports a variety of \(lqpreviews\(rq out of the box,
as well as an option to define custom ones.
.PP
.
When
.B ctpv
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.
Symbolic links are dereferenced.
.
.SS Dependencies
.
Previewing each file type requires specific programs.
If a program is not found on the system,
.B ctpv
will try to use another one.
Only one program is required for each file type.
For example, you only need either
.IR elinks ,
.IR lynx
or
.IR w3m
installed on your system to view HTML files.
.
\# 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 chafa
T}
json	T{
jq
T}
markdown	T{
mdcat
T}
odt	T{
libreoffice
T}
pdf	T{
pdftoppm
T}
text	T{
bat cat highlight source-highlight
T}
torrent	T{
transmission-show
T}
video	T{
ffmpegthumbnailer
T}
.TE
\# TABLEEND
.
.SS Integration
.
.TP
\fIlf\fP file manager
Add this snippet to
.I lf
configuration file (usually located at
.IR \(ti/.config/lf/lfrc ).
.PP
.
.Ex
set previewer ctpv
set cleaner ctpvclear
&ctpv -s $id
cmd on-quit $ctpv -e $id
.Ee
.
.SS Image previews
.
Image previews are enabled by either installing
.I Überzug
or
.I Chafa
(as seen in
.IR Dependencies )
or using built-in image preview functionality of
.I Kitty
terminal.
.PP
.
When possible,
.B ctpv
will prefer
.I Überzug
over others image preview methods. You can override this
behavior by using
.B forcekitty
or
.B forcechafa
options (see
.IR "Preview options" ).
.
.SS How previews are selected
.
Initially,
.B ctpv
retrieves MIME type and extension from
.I file
passed in the first argument (MIME type is extracted using
.BR libmagic (3)).
.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 's
extension and MIME type.
If it does, it runs a preview script.
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
.
.B ctpv
uses a configuration file usually located at
.IR \(ti/.config/ctpv/config
(see
.IR FILES ).
Its format somewhat resembles one used by
.IR lf .
There are several \(lqcommands\(rq that can be used to change
previews or set different settings.
Commands are separated by newlines.
Comments start with number sign
.RB ( # )
like in many other formats.
.
.SS Preview options
.
An option can be set using
.B set
command.
.
.TP
.B forcekitty
Always use
.I Kitty
terminal's built-in method of previewing images.
.
.TP
.B forcechafa
Always use
.I Chafa
for image previews.
.
.TP
.B noimages
Print only text and do not use any image previewing method.
.
.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):
.PP
.
.Ex
preview cow .moo {{
\&    cowsay < "$f"
}}
.Ee
.PP
.
Running
.I "ctpv\ file.moo"
where
.I file.moo
contains \(lqsome text\(rq will produce the following output:
.PP
.
.Ex
\#  ___________ 
\# < some text >
\#  ----------- 
\#         \   ^__^
\#          \  (oo)\_______
\#             (__)\       )\/\
\#                 ||----w |
\#                 ||     ||
\&\ \(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\ |
\&\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ ||
.Ee
.PP
.
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:
.PP
.
.Ex
preview json_example application/json {{
\&    # preview json files
}}
.Ee
.PP
.
And you also can omit subtype part of the MIME type
by replacing it with
.BR * .
.PP
.
.Ex
preview any_text_example text/* {{
\&    # this one applies to all text files
}}
.Ee
.PP
.
Setting subtype to
.B *
will make the preview above work for any file which MIME type starts with
.BR text/ .
.
.SS Setting priority
.
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:
.PP
.
.Ex
priority cat
.Ee
.PP
.
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):
.PP
.
.Ex
remove cat
.Ee
.PP
.
.
.SH FILES
.
.TP
.I $XDG_CONFIG_HOME/ctpv/config
Configuration file. If
.I $XDG_CONFIG_HOME
is not set, defaults to
.IR \(ti/.config .
.
.
.SH SEE ALSO
.
.BR lf (1)
.
.
.SH AUTHOR
.
Written by Nikita Ivanov.