move plugin into $ZSH/plugins/printc

plugins/printc/README.md

@@ -0,0 +1,129 @@
+# printc
+
+With this plugin you can print any color within the rgb color space via an interface that
+is as simple as a regular print statement.
+
+This simple tool provides an abstraction layer on top of terminal ANSI rgb escape codes,
+making the addition of colorized output to your functions, shell scripts, and/or
+interactive terminal in zsh a piece of cake. There is support for any of the colors which
+can be achieved via the form R G B, where R, G and B are any numeric value
+between 0 and 255, representing the red, green, blue color space values respectively.
+Users of this plugin are able to issue a  `printc` statement, followed by the previous
+mentioned rgb values, followed by the text to be printed. There is also 36 built in colors
+which can be accessed via tab auto-complete. And there is support for bold, italic, and
+underline text.
+
+#### Table of Contents
+ - [Setup](#Setup)
+ - [Configuration](#Configuration)
+    - [Requirements](#Requirements)
+    - [Italics Setup](#Italics-Setup)
+ - [Usage](#Usage)
+    - [Options](#Options)
+    - [General Structure of Command](#General-Structure-of-Command)
+ - [Notes on Environment Setup and Script Usage](#Notes-on-Environment-Setup-and-Script-Usage)
+
+
+## Setup
+To use, add printc to the plugins array inside your `~/.zshrc` file:
+```
+plugins=(... printc)
+```
+## Configuration
+
+### Requirements
+Your terminal emulator must support 256 color. If you want to leverage italic text,
+depending on your terminal emulator you will likely need to add support for displaying
+italic text. The process is very simple, and I'll include instruction on how to do so. As
+long as your terminal emulator supports, and is set up for 256 color, which almost all are
+now-a-days, you can use the color aspect of the plugin, even without the italic
+functionality.
+
+At the least your TERM environment variable must be set as so:
+```
+export TERM=xterm-256color
+```
+
+It is possible that this is all that will be needed for the italic functionality to work
+as well. I do reccomend trying and seeing if italics work. It it does not, just follow the
+simple steps below.
+
+### Italics Setup
+ 1) Create a directory `~/.terminfo`
+
+ 2) Create a file inside `~/.terminfo` called `xterm-256color-italics.terminfo`
+
+ 3) Place the follwing contents inside `xterm-256color-italics.terminfo` *exactly* as
+ they are shown:
+
+ ```
+ xterm-256color-italic|xterm with 256 colors and italic,
+ sitm=\E[3m, ritm=\E[23m,
+ use=xterm-256color,
+ ```
+
+ 4) Inside `~/.terminfo` run the command `tic xterm-256color-italics.terminfo`
+
+ 5) Set your TERM environment variable as so:
+ ```
+ export TERM=xterm-256color-italic
+ ```
+ You can export TERM in your `~/.zshrc` or `~/.zshenv` or many other ways. If you're an
+ iTerm2 user you can do it through the GUI terminal emulator settings there. It doesn't
+ matter how you do it, as long as the TERM environment variable is set and exported to
+ one of the above mentioned values, most likely the latter if you want italics.
+
+ As an aside, I have not tested this inside TMUX, but it should work there as long as the
+ environment is set up to properly handle color and italics.
+
+# Usage
+
+### Options
+  | Option              | Function               |
+  | :-----------------: | --------------         |
+  | -b                  | Bold                   |
+  | -u                  | Underline              |
+  | -i                  | Italic                 |
+  | -C `color`          | Specify built in color |
+  | -l                  | List built in colors   |
+  | -n                  | No newline             |
+  | -h                  | Display help page      |
+
+### General Structure of Command
+ * `printc [-b] [-u] [-i] [-n] <0-255> <0-255> <0-255> "Colorized Text to Display"`
+     * This is the structure used when specifying a color with RGB values.
+     * Note the absense of quotes around the RGB numbers, this is required.
+     * Note the inclusion of quotes around the intended output, also required.
+         * As usual double quotes will allow parameter expansion.
+     * The RGB values must come after any options, and before the intended output.
+ * `printc [-b] [-u] [-i] [-n]> -C <built in color> "Colorized Text to Display"`
+     * This is the structure used when specifying a color that is built in to the plugin.
+     * Quoting the intended output is not required when using built in color options.
+ * Options can be given in any order, and chained together, such as
+ `-buinC <built in color>`, so long as `built in color` follows immediately after `-C`,
+ and in the case of using RGB values, they must come after any options that are given.
+
+# Notes on Environment Setup and Script Usage
+ Immediately after setup, the `printc` command will be available to use
+ interactively, or inside aliases and functions. You can create nice colorized, formatted
+ text for your output. In order to be used inside ZSH scripts, you will need to make the
+ `printc` tool available outside of your current shell. One easy way to do this is to add
+ the following lines to your `~/.zshenv` file.
+
+ ```
+ fpath=($HOME/.oh-my-zsh/plugins/printc $fpath)'
+ ZSH=$HOME/.oh-my-zsh/'
+ ```
+ The first line makes the plugin itself available to shells that are forked from your
+ interactive session, and the second line is an environment variable provided by OMZ,
+ which is referenced inside of the `printc` plugin, and therefore needs to be exposed to
+ children shells who want access to the tool. This can be done manually, or there is an
+ included script, called `setup.sh` which will set everything up automatically if ran. It
+ only needs to be ran once.
+
+ And finally, any script that uses the `printc` command will have to include the line
+ `autoload -Uz printc` near the top.
+
+ If you only want to use `printc` interactively, and/or inside functions and aliases, then
+ the above environment setup is not needed.
+