Documentarama.

README.md

@@ -5,7 +5,7 @@ imgcat
 
 It's like `cat` but for images.
 
-![$imgcat cat.jpg](./docs/imgcat.png)
+<img src="./docs/imgcat.png" alt="$imgcat cat.jpg" style="max-height: 512px">
 
 
 Install
@@ -18,8 +18,12 @@ brew tap eddieantonio/eddieantonio
 brew install imgcat
 ```
 
+**Important**: [See below](#note-on-iterm2-s-shell-integration) if
+you're using iTerm2 3.0 with shell integration installed.
+
 For other platforms, see [Build](#build).
 
+
 Usage
 -----
 
@@ -29,15 +33,35 @@ imgcat some_image.jpg
 
 See the [manpage](./docs/imgcat.1.md) for more invocations.
 
+Note on iTerm2's shell integration
+----------------------------------
+
+If you install iTerm2's [shell integration], chances are you also
+installed its additional scripts, including one called `imgcat`.
+**iTerm's `imgcat` overrides this program by default**. To see if you
+this is happening to you, use `which` to determine where your shell is
+finding imgcat:
+
+    which imgcat
+
+If it says: `imgcat: aliased to /Users/yourusername/.iterm2/imgcat`,
+then you must edit your shell startup file and add `unalias imgcat`
+**after** the line that sources iTerm2's script. For example:
+
+    test -e ${HOME}/.iterm2_shell_integration.zsh && source ${HOME}/.iterm2_shell_integration.zsh
+    unalias imgcat
+
+[shell integration]: https://www.iterm2.com/documentation-shell-integration.html
+
 Build
 -----
 
 ### Requirements
 
 (You most likely already have both of these).
 
- - libjpeg
  - GNU make
+ - libjpeg
 
 Then:
 
@@ -66,12 +90,10 @@ Acknowledgements
 
  - Uses the [CImg], distributed under the [CeCILL-C] license.
  - 256 Color chart and data from Jason Milkin's [public domain chart][256svg].
- - [NibbleAndAHalf]
 
 [CImg]: https://github.com/dtschump/CImg
 [CeCILL-C]: http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.txt
 [256svg]: https://gist.github.com/jasonm23/2868981
-[NibbleAndAHalf]: https://github.com/superwills/NibbleAndAHalf
 
 License
 -------

docs/imgcat.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 1.16.0.2
 .\"
-.TH "IMGCAT" "1" "November 10, 2016" "imgcat User Manual" "meow"
+.TH "IMGCAT" "1" "April 30, 2017" "imgcat User Manual" "meow"
 .hy
 .SH NAME
 .PP
@@ -12,9 +12,8 @@
 .SH DESCRIPTION
 .PP
 \f[B]imgcat\f[] prints images to your terminal screen.
-Yes, indeed it does.
 .PP
-By default, the image is printed at the full width and colour depth
+By default, the image is printed at the full width and color depth
 detected for your terminal.
 These can be overridden using \f[B]\-w\f[] to adjust the maximum width
 or \f[B]\-R\f[] to prevent resizing, even if the image is too big to fit
@@ -24,11 +23,9 @@ in the terminal; and \f[B]\-d\f[] to explicitly the set color depth.
 terminfo with the full capabilities of you terminal!\f[] See
 \f[B]Troubleshooting\f[] if you\[aq]re having a problem with this.
 .PP
-If the output stream is not a terminal (that is, output is redirected to
-a file, or piped into another program), then the image is \f[B]not\f[]
-resized to the size of the terminal.
-It does, however, uses the color depth of terminal set in the
-\f[C]TERM\f[] environment variable.
+If the output is not a terminal (that is, output is redirected to a
+file, or piped into another program), then the image is \f[B]not\f[]
+resized and the color depth is set to 8 colors.
 Overriding both width and color depth still work.
 .SS Options
 .TP
@@ -42,7 +39,7 @@ already as small as the provided width.
 .TP
 .B \f[B]\-d\f[] \f[I]MODE\f[], \f[B]\-\-depth\f[]=\f[I]MODE\f[]
 Explicitly set the output color depth to one of \f[B]ansi\f[],
-\f[B]8\f[] (alias of \f[B]ansi\f[]), or \f[B]256\f[].
+\f[B]8\f[] (alias of \f[B]ansi\f[]), \f[B]256\f[], or \f[B]iterm\f[].
 If not provided, the output color depth will be inferred with
 \f[C]tput\ colors\f[].
 .RS
@@ -53,6 +50,21 @@ Does not resize the image to fit the terminal\[aq]s width.
 Overrides \f[B]\-\-width\f[].
 .RS
 .RE
+.SS iTerm2 3.0
+.PP
+\f[B]imgcat\f[] supports iTerm2\[aq]s full\-color inline images (use
+\f[B]\-d iterm\f[] to explicitly enable this).
+However, iTerm2 is bundled with a script that is also called
+\f[B]imgcat\f[]! To use this program in preference to the script bundled
+with iTerm2, edit your shell\[aq]s configuration file such that, after
+the line that sources iTerm2\[aq]s shell integration and utilities, you
+unalias its built\-in script:
+.IP
+.nf
+\f[C]
+unalias\ imgcat
+\f[]
+.fi
 .SS Troubleshooting
 .PP
 First, test how many colors your terminal can output:

docs/imgcat.1.md

@@ -10,9 +10,9 @@
 
 # DESCRIPTION
 
-**imgcat** prints images to your terminal screen. Yes, indeed it does.
+**imgcat** prints images to your terminal screen.
 
-By default, the image is printed at the full width and colour depth
+By default, the image is printed at the full width and color depth
 detected for your terminal. These can be overridden using **-w** to
 adjust the maximum width or **-R** to prevent resizing, even if the
 image is too big to fit in the terminal; and **-d** to explicitly the
@@ -22,11 +22,10 @@ __Make sure your `TERM` environment variable is set to a terminfo with
 the full capabilities of you terminal!__ See **Troubleshooting** if
 you're having a problem with this.
 
-If the output stream is not a terminal (that is, output is redirected to
+If the output is not a terminal (that is, output is redirected to
 a file, or piped into another program), then the image is **not**
-resized to the size of the terminal. It does, however, uses the color
-depth of terminal set in the `TERM` environment variable. Overriding
-both width and color depth still work.
+resized and the color depth is set to 8 colors. Overriding both width
+and color depth still work.
 
 ## Options
 
@@ -37,13 +36,24 @@ both width and color depth still work.
 
 **-d** _MODE_, **--depth**=_MODE_
   ~ Explicitly set the output color depth to one of **ansi**, **8**
-  (alias of **ansi**), or **256**. If not provided, the output color
-  depth will be inferred with `tput colors`.
+  (alias of **ansi**), **256**, or **iterm**. If not provided, the
+  output color depth will be inferred with `tput colors`.
 
 **-R**, **--no-resize**
   ~ Does not resize the image to fit the terminal's width. Overrides
   **--width**.
 
+## iTerm2 3.0
+
+**imgcat** supports iTerm2's full-color inline images (use **-d iterm**
+to explicitly enable this). However, iTerm2 is bundled with a script
+that is also called **imgcat**! To use this program in preference to the
+script bundled with iTerm2, edit your shell's configuration file such
+that, after the line that sources iTerm2's shell integration and
+utilities, you unalias its built-in script:
+
+    unalias imgcat
+
 ## Troubleshooting
 
 First, test how many colors your terminal can output: