From 7c7ea7c37eb49413e4b1c4b90be262882156197f Mon Sep 17 00:00:00 2001 From: Nikita Ivanov Date: Tue, 14 Jun 2022 13:10:25 +0500 Subject: [PATCH] Add man page --- doc/ctpv.1 | 312 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 doc/ctpv.1 diff --git a/doc/ctpv.1 b/doc/ctpv.1 new file mode 100644 index 0000000..f06f7c5 --- /dev/null +++ b/doc/ctpv.1 @@ -0,0 +1,312 @@ +.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 +.PP +.IP +.EX +.. +. +.de Ee +.EE +.PP +.. +. +. +.TH CTPV 1 "June 2022" Linux "User Manuals" +.SH NAME +ctpv \- 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 +.B \-s +.I id +.Ys +. +.Sy +.B \-c +.I id +.Ys +. +.Sy +.B \-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 +(including one for previewing images with +.IR ueberzug ) +and an option for defining custom previews. +. +.SS Integration +. +The following snippets should be added to configuration files +of corresponding programs: +. +.TP +\fIlf\fP file manager: +.EX +set previewer ctpv +set cleaner ctpvclear +&ctpv -s $id +cmd on-quit $ctpv -e $id +.EE +. +.SS How previews are selected +. +Initially, +.B ctpv +retrieves MIME type and extension from +.I file +given in the first argument (MIME type is extracted using +.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. +If it does, it runs the 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 +. +The configuration file format somewhat resembles one used by +.IR lf . +There are several commands that allow you to customize +.B ctpv +behavior. +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): +. +.Ex +preview cow .moo {{ + cowsay < "$f" +}} +.Ee +. +Running +.I "ctpv\ file.moo" +where +.I file.moo +contains \(lqsome text\(rq will produce the following output: +. +.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 +. +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: +. +.Ex +preview json_example application/json {{ + # preview json files +}} +.Ee +. +And you also can omit subtype part of the MIME type +by replacing it with +.BR * . +. +.Ex +preview any_text_example text/* {{ + # this one applies to all text files +}} +.Ee +. +Setting subtype to +.B * +will make the preview 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: +. +.Ex +priority cat +.Ee +. +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): +. +.Ex +remove cat +.Ee +. +. +.SH FILES +. +.TP +.I $XDG_CONFIG_HOME/ctpv/config +Configuration file. If +.I $XDG_CONFIG_HOME +is empty or not set, defaults to +.IR $HOME/.config . +. +. +.SH SEE ALSO +. +.BR lf (1) +. +. +.SH AUTHOR +. +Written by Nikita Ivanov.