Read TIMG_PIXELATION environment variable as fallback to --pixelation

This provides another way to tell timg what pixelation to use before
it falls back to auto-detection.

man/timg.1

@@ -1,30 +1,12 @@
-.\" Automatically generated by Pandoc 2.19.2
+.\" Automatically generated by Pandoc 3.1.8
 .\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
 .TH "timg" "1" "Jul 2023" "" ""
-.hy
 .SH NAME
-.PP
 timg - A terminal image and video viewer
 .SH SYNOPSIS
-.PP
 \f[B]timg\f[R] [<\f[I]options\f[R]>] <\f[I]image/video\f[R]>
 [<\f[I]image/video\f[R]>\&...]
 .SH DESCRIPTION
-.PP
 Show images, play animated gifs, scroll static images or play videos in
 the terminal.
 Even show PDFs.
@@ -48,7 +30,7 @@ read an image from a pipe.
 If the input from a pipe is a video, use the \f[B]-V\f[R] option (see
 below).
 .PP
-Under the hood, \f[V]timg\f[R] uses various image libraries to open and
+Under the hood, \f[CR]timg\f[R] uses various image libraries to open and
 decode a wide range of image formats.
 It uses threads to open and decode images in parallel for super-fast
 viewing experience for many images.
@@ -58,7 +40,6 @@ these file decoders ({GraphicsMagick, turbojpeg, qoi} or libav
 respectively).
 .SH OPTIONS
 .SS General Options
-.PP
 Most likely commonly needed options first.
 .TP
 \f[B]-p\f[R] \f[I]<[h|q|s|k|i]>\f[R], \f[B]--pixelation\f[R]=\f[I][h|q|s|k|i]\f[R]
@@ -90,47 +71,48 @@ It makes it look less `blocky' and usually better.
 Sixel output allows a high resolution image output that dates back
 to DEC VT200 and VT340 terminals.
 This image mode provides full
-resolution on a 256 color palette that \f[V]timg\f[R] optimizes for each
-image.
-You find the sixel protocol implemented by \f[V]xterm\f[R] (invoke
-with \f[V]-ti vt340\f[R]) and \f[V]mlterm\f[R] or \f[V]konsole\f[R].
+resolution on a 256 color palette that \f[CR]timg\f[R] optimizes for
+each image.
+You find the sixel protocol implemented by \f[CR]xterm\f[R] (invoke
+with \f[CR]-ti vt340\f[R]) and \f[CR]mlterm\f[R] or \f[CR]konsole\f[R].
 Recently, more terminal
 emulators re-discovered this format and started implementing it.
-This does not work in \f[V]tmux\f[R], but there is a tmux fork with
+This does not work in \f[CR]tmux\f[R], but there is a tmux fork with
 sixel
 support around.
 .TP
 \f[B]kitty\f[R] (short `k')
 The Kitty terminal implements an image protocol that allows for full
 24Bit RGB/32 Bit RGBA images to be displayed.
 This is implemented in the
-\f[V]kitty\f[R] terminal but also e.g.\ \f[V]konsole\f[R].
-You can even use this in \f[V]tmux\f[R]: This is the only protocol that
+\f[CR]kitty\f[R] terminal but also e.g.\ \f[CR]konsole\f[R].
+You can even use this in \f[CR]tmux\f[R]: This is the only protocol that
 can
-work around the reluctance of \f[V]tmux\f[R] to allow graphics
+work around the reluctance of \f[CR]tmux\f[R] to allow graphics
 protocols.
 Some creative workarounds (Unicode placeholders) are used that are
-only implemented in \f[V]kitty\f[R] version >= 0.28 right now.
-Also needs \f[V]tmux\f[R]
+only implemented in \f[CR]kitty\f[R] version >= 0.28 right now.
+Also needs \f[CR]tmux\f[R]
 version >= 3.3.
-You have to explicitly set the \f[V]-pk\f[R] option inside
+You have to explicitly set the \f[CR]-pk\f[R] option inside
 tmux as timg would otherwise just use block-pixels there.
 .TP
 \f[B]iterm2\f[R] (short `i')
 The iterm2 graphics is another image protocol that allows for full
 24 Bit RGB/32 Bit RGBA images.
 It originated on the popular macOS
 OpenSource iTerm2 terminal but is now also implemented by
-\f[V]wezterm\f[R] and
-\f[V]konsole\f[R].
-.PP
-\f[V]timg\f[R] attempts to recognize the available terminal feature, but
-it might not be able to auto-detect all full-resolution compatible
-terminals and fall back to \f[B]quarter\f[R] in that case.
-In that case you\[cq]d pass the \f[V]-p\f[R] option to choose the best
-pixelation.
-If you\[cq]re always working in the same terminal, maybe create an
-alias, e.g.\ \f[V]alias timg=\[aq]timg -ps\[aq]\f[R].
+\f[CR]wezterm\f[R] and
+\f[CR]konsole\f[R].
+.PP
+If no option is given, default is taken from environment variable
+\f[B]TIMG_PIXELATION\f[R].
+If that is not set, \f[CR]timg\f[R] attempts to auto-detect the
+available terminal feature.
+Not all full-resolution compatible terminals can be auto-detected so it
+will fall back to \f[B]quarter\f[R] in that case.
+Consider passing the \f[CR]-p\f[R] option or set the
+\f[CR]TIMG_PIXELATION\f[R] environment variable in that case.
 .RE
 .TP
 \f[B]--grid\f[R]=<\f[I]cols\f[R]>[x<\f[I]rows\f[R]>]
@@ -151,19 +133,19 @@ It is possible to customize the title by giving a format string.
 In this string, the following format specifiers are expanded:
 .RS
 .IP \[bu] 2
-\f[V]%f\f[R] = full filename
+\f[CR]%f\f[R] = full filename
 .IP \[bu] 2
-\f[V]%b\f[R] = basename (filename without path)
+\f[CR]%b\f[R] = basename (filename without path)
 .IP \[bu] 2
-\f[V]%w\f[R] = image width
+\f[CR]%w\f[R] = image width
 .IP \[bu] 2
-\f[V]%h\f[R] = image height
+\f[CR]%h\f[R] = image height
 .IP \[bu] 2
-\f[V]%D\f[R] = internal decoder used (image, video, qoi, sta, openslide,
-\&...)
+\f[CR]%D\f[R] = internal decoder used (image, video, qoi, sta,
+openslide, \&...)
 .PP
-If no format string is given, this is just the filename (\f[V]%f\f[R])
-or, if set, what is provided in the \f[V]TIMG_DEFAULT_TITLE\f[R]
+If no format string is given, this is just the filename (\f[CR]%f\f[R])
+or, if set, what is provided in the \f[CR]TIMG_DEFAULT_TITLE\f[R]
 environment variable.
 .RE
 .TP
@@ -191,7 +173,7 @@ Like \f[B]-f\f[R], but relative filenames are resolved relative to the
 \f[I]directory the file list resides in\f[R].
 This allows you to e.g.\ have a file list at the top of a directory
 hierarchy with relative filenames but are not required to change into
-that directory first for \f[V]timg\f[R] to resolve the relative paths.
+that directory first for \f[CR]timg\f[R] to resolve the relative paths.
 .TP
 \f[B]-b\f[R] <\f[I]background-color\f[R]>
 Set the background color for transparent images.
@@ -206,7 +188,7 @@ blended edges for the text-block based pixelations.
 .PP
 Another special value is \f[B]auto\f[R]:
 .IP \[bu] 2
-For graphics modes, this behaves like \f[V]none\f[R], sending RGBA
+For graphics modes, this behaves like \f[CR]none\f[R], sending RGBA
 images for alpha-blending directly in the terminal.
 .IP \[bu] 2
 For text-block modes, this attempts to query the terminal for its
@@ -223,9 +205,9 @@ The allows for HTTML/SVG/X11 colors like \f[B]-b\f[R].
 .RS
 .PP
 The checkerboard pattern has square blocks one character cell wide and
-half a cell high (see \f[V]--pattern-size\f[R] to change).
+half a cell high (see \f[CR]--pattern-size\f[R] to change).
 .PP
-A common combination would be to use \f[V]-bgray -Bdarkgray\f[R] for
+A common combination would be to use \f[CR]-bgray -Bdarkgray\f[R] for
 backgrounds known from image editors.
 .PP
 Sometimes setting such background is the only way to see an image, e.g.
@@ -293,11 +275,11 @@ allow some time to show the image of course, so good in combination with
 .RE
 .TP
 \f[B]-V\f[R]
-Tell \f[V]timg\f[R] that this is a video, directly read the content as
+Tell \f[CR]timg\f[R] that this is a video, directly read the content as
 video and don\[cq]t attempt to probe image decoding first.
 .RS
 .PP
-Usually, \f[V]timg\f[R] will first attempt to interpret the data as
+Usually, \f[CR]timg\f[R] will first attempt to interpret the data as
 image, but if it that fails, will fall-back to try interpret the file as
 video.
 However, if the file is coming from stdin, the first bytes used to probe
@@ -316,15 +298,15 @@ Somewhat the opposite of \f[B]-V\f[R].
 \f[B]-w\f[R]<\f[I]seconds\f[R]>
 Wait time in seconds between images when multiple images are given on
 the command line.
-Fractional values such as \f[V]-w0.3\f[R] are allowed.
+Fractional values such as \f[CR]-w0.3\f[R] are allowed.
 .TP
 \f[B]-wr\f[R]<\f[I]seconds\f[R]>
-Similar to \f[V]-w\f[R], but wait time between \f[I]rows\f[R].
-If a \f[V]--grid\f[R] is chosen, this will wait at the end of a
+Similar to \f[CR]-w\f[R], but wait time between \f[I]rows\f[R].
+If a \f[CR]--grid\f[R] is chosen, this will wait at the end of a
 completed row.
-If no grid is chosen, then this is equivalent to \f[V]-w\f[R].
-Both, \f[V]-w\f[R] and \f[V]-wr\f[R] can be provided to show each image
-individually, but also have a wait time between rows.
+If no grid is chosen, then this is equivalent to \f[CR]-w\f[R].
+Both, \f[CR]-w\f[R] and \f[CR]-wr\f[R] can be provided to show each
+image individually, but also have a wait time between rows.
 .TP
 \f[B]-a\f[R]
 Switch off anti-aliasing.
@@ -342,7 +324,7 @@ see \f[B]-W\f[R] if you want to fill the width.
 .RS
 .PP
 It is possible to only partially specify the size before or after the
-\f[V]x\f[R]-separator, like \f[B]-g<width>x\f[R] or
+\f[CR]x\f[R]-separator, like \f[B]-g<width>x\f[R] or
 \f[B]-gx<height>\f[R].
 The corresponding other value is then derived from the terminal size.
 .RE
@@ -361,15 +343,15 @@ network.
 Default compression level is 1 which should be reasonable default in
 almost all cases.
 To disable, set to 0 (zero).
-Use \f[V]--verbose\f[R] to see the amount of data \f[V]timg\f[R] sent to
-the terminal.
+Use \f[CR]--verbose\f[R] to see the amount of data \f[CR]timg\f[R] sent
+to the terminal.
 .TP
 \f[B]--threads\f[R]=<\f[I]n\f[R]>
 Run image decoding in parallel with n threads.
 By default, up to 3/4 of the reported CPU-cores are used.
 .TP
 \f[B]--color8\f[R]
-For \f[V]half\f[R] and \f[V]quarter\f[R] block pixelation: Use 8 bit
+For \f[CR]half\f[R] and \f[CR]quarter\f[R] block pixelation: Use 8 bit
 color mode for terminals that don\[cq]t support 24 bit color (only shows
 6x6x6 = 216 distinct colors instead of 256x256x256 = 16777216).
 .TP
@@ -393,7 +375,6 @@ This might be useful for developers of terminal emulations to do
 performace tests or simply if you want to redirect the output to a file
 and don\[cq]t want to wait.
 .SS For Animations, Scrolling, or Video
-.PP
 Usually, animations are shown in full in an infinite loop.
 These options limit infinity.
 .TP
@@ -436,7 +417,6 @@ Scroll with delta x and delta y.
 The default of 1:0 scrolls it horizontally, but with this option you can
 scroll vertically or even diagonally.
 .SH RETURN VALUES
-.PP
 Exit code is
 .TP
 \f[B]0\f[R]
@@ -450,7 +430,8 @@ image provided.
 If an invalid option or parameter was provided.
 .TP
 \f[B]3\f[R]
-If \f[V]timg\f[R] could not determine the size of terminal (not a tty?).
+If \f[CR]timg\f[R] could not determine the size of terminal (not a
+tty?).
 Provide \f[B]-g\f[R] option to provide size of the output to be
 generated.
 .TP
@@ -462,17 +443,24 @@ Could not read file list file provided with \f[B]-f\f[R].
 .SH ENVIRONMENT
 .TP
 \f[B]TIMG_DEFAULT_TITLE\f[R]
-The default format string used for \f[V]--title\f[R].
-If not given, the default title format string is \[dq]\f[V]%f\f[R]\[dq].
+The default format string used for \f[CR]--title\f[R].
+If not given, the default title format string is
+\[dq]\f[CR]%f\f[R]\[dq].
+.TP
+\f[B]TIMG_PIXELATION\f[R]
+The default pixelation if not provided by the \f[CR]-p\f[R] or
+\f[CR]--pixelation\f[R] option (see choice of values there).
+If neither the environment variable nor the option is given, timg
+attempts to auto-detect the best pixelation for the terminal.
 .TP
 \f[B]TIMG_USE_UPPER_BLOCK\f[R]
 If this environment variable is set to the value \f[B]1\f[R],
-\f[V]timg\f[R] will use the U+2580 - `Upper Half Block' Unicode
+\f[CR]timg\f[R] will use the U+2580 - `Upper Half Block' Unicode
 character.
 .RS
 .PP
-To display pixels, \f[V]timg\f[R] uses a Unicode half block and sets the
-foreground color and background color to get two vertical pixels.
+To display pixels, \f[CR]timg\f[R] uses a Unicode half block and sets
+the foreground color and background color to get two vertical pixels.
 By default, it uses the U+2584 - `Lower Half Block' character to achieve
 this goal.
 This has been chosen as it resulted in the best image in all tested
@@ -501,31 +489,27 @@ your terminal emulator of choice.
 .RE
 .TP
 \f[B]TIMG_ALLOW_FRAME_SKIP\f[R]
-Set this environment variable to 1 if you like to allow \f[V]timg\f[R]
+Set this environment variable to 1 if you like to allow \f[CR]timg\f[R]
 to drop frames when play-back is falling behind.
 This is particularly useful if you are on a very slow remote terminal
 connection that can\[cq]t keep up with playing videos.
 Or if you have a very slow CPU.
 .SH EXAMPLES
-.PP
 Some example invocations including scrolling text or streaming an online
 video are put together at <https://timg.sh/#examples>
 .PP
 It might be useful to prepare some environment variables or aliases in
 the startup profile of your shell.
-The \f[V]timg\f[R] author typically has these set:
+The \f[CR]timg\f[R] author typically has these set:
 .IP
-.nf
-\f[C]
+.EX
 # The default --title format
 export TIMG_DEFAULT_TITLE=\[dq]%b (%wx%h)\[dq]
 
 # image list. An alias to quickly list images; invoke with ils images/*
 alias ils=\[aq]timg --grid=3x1 --upscale=i --center --title --frames=1 -bgray -Bdarkgray\[aq]
-\f[R]
-.fi
+.EE
 .SH KNOWN ISSUES
-.PP
 This requires a terminal that can deal with Unicode characters and 24
 bit color escape codes.
 This will be problematic on really old installations or if you want to
@@ -534,16 +518,13 @@ display images on some limited text console.
 The option \f[B]-V\f[R] should not be necessary for streaming video from
 stdin; timg should internally buffer bytes it uses for probing.
 .SH BUGS
-.PP
 Report bugs at <http://github.com/hzeller/timg/issues>
 .SH COPYRIGHT
-.PP
 Copyright (c) 2016..2023 Henner Zeller.
 This program is free software, provided under the GNU GPL version 2.0.
 .PP
 <https://gnu.org/licenses/gpl-2.0.html>
 .SH SEE ALSO
-.PP
 GraphicsMagick, ffmpeg(1), utf-8(7), unicode(7), kitty(1),
 https://en.wikipedia.org/wiki/Sixel
 .SH AUTHORS

man/timg.1.md

@@ -94,11 +94,12 @@ Most likely commonly needed options first.
      : OpenSource iTerm2 terminal but is now also implemented by `wezterm` and
      : `konsole`.
 
-     `timg` attempts to recognize the available terminal feature, but it might
-     not be able to auto-detect all full-resolution compatible terminals and
-     fall back to **quarter** in that case. In that case you'd pass the `-p`
-     option to choose the best pixelation. If you're always working in the
-     same terminal, maybe create an alias, e.g. `alias timg='timg -ps'`.
+    If no option is given, default is taken from environment variable
+    **TIMG_PIXELATION**. If that is not set, `timg` attempts to
+    auto-detect the available terminal feature. Not all full-resolution
+    compatible terminals can be auto-detected so it will fall back
+    to **quarter** in that case. Consider passing the `-p`
+    option or set the `TIMG_PIXELATION` environment variable in that case.
 
 **-\-grid**=<*cols*>[x<*rows*>]
 :    Arrange images in a grid. If only one parameter is given, arranges in a
@@ -382,6 +383,12 @@ Exit code is
 :   The default format string used for `--title`. If not given, the default
     title format string is \"`%f`\".
 
+**TIMG_PIXELATION**
+:   The default pixelation if not provided by the `-p` or `--pixelation`
+    option (see choice of values there). If neither the environment variable
+    nor the option is given, timg attempts to auto-detect the best pixelation
+    for the terminal.
+
 **TIMG_USE_UPPER_BLOCK**
 :    If this environment variable is set to the value **1**, `timg` will use the
      U+2580 - 'Upper Half Block' Unicode character.

src/CMakeLists.txt

@@ -30,7 +30,7 @@ endif()
 
 target_include_directories(timg PRIVATE ${CMAKE_BINARY_DIR}/src)
 
-target_compile_features(timg PRIVATE cxx_std_14)
+target_compile_features(timg PRIVATE cxx_std_17)
 
 if(TIMG_VERSION_FROM_GIT)
   git_describe(GIT_DESCRIBE_VERSION)