@@ -0,0 +1,105 @@ .. -*- mode: rst -*-
.. highlight:: shell
============= Terminal Tips =============
These are some tips how to get more out of Pygments on the terminal.

How do I determine which shell I am using? ------------------------------------------ Run this command::
$ echo $SHELL
Mine outputs ``/usr/bin/fish``, which is the location of the executable. This means my computer is using the fish shell. ``neofetch`` (or a similar utility) can also provide that information.
Most shells are POSIX compliant.

Aliases (POSIX) ---------------
POSIX compliant shells includes ``bash`` and ``zsh``, and most shells.
Aliases allow you to call a function using a different name. In this case it calls :program:`pygmentize` by using a different name. The simplest is to make an alias called ``cath``::
$ alias cath="pygmentize"
The only thing is that :program:`pygmentize` does not really work like ``cat``. It does allow you to use a command that is similar to one use for cat, displaying a file.
Add additional flags can be added as desired. The monokai style works well for a dark background, so this is how you would add that option::
$ alias cath="pygmentize -O style=monokai"

Here is a version of ``less`` with syntax highlighting. It is slightly more complicated, because it uses the environment variable ``LESSOPEN`` to preprocess the input file(s)::
$ alias lessh='LESSOPEN="| pygmentize -O style=monokai %s" less -M -R '
These alias commands need to be added to your configuration in order to work when you open a new terminal (or restart the computer).
Add above commands to your configuration file:
* ``bash`` - edit either ``~/.bash_aliases`` (if it exists) or ``~/.bashrc`` file. * ``csh`` (C shell), edit the ``~/.cshrc`` file * ``ksh`` (Korn shell), edit the ``~/.kshrc`` file. * ``tcsh``, edit the ``~/.tcshrc`` file. * ``zsh``, edit the ``~/.zshrc`` file.
In order to apply the changes to the current shell environment systems: run ``source`` on the filename just edited::
$ source [~/.filenamerc]

Aliases (fish shell) -------------------- The above aliases for POSIX work just fine, but permanently saving an alias in fish shell is a little different. Functions are used to make permanent aliases. ``funced [command]`` is used to create the function, followed by ``funcsave [command]`` saves the function to the environment.

Running the ``funced cath``, brings up the default editor, and add the following code in the function::
function cath # 'cath' alias will highlight source code as cat does. alias cath="pygmentize" end
Here's what the ``cath`` function looks like with an additional argument::
function cath alias cath="pygmentize -O style=monokai" end
Note: that just like the POSIX shell you may run ``alias cath="pygmentize -O style=monokai"`` on the command line to test out the alias beforehand.
Test the ``cath`` function. To save the function run ``funcsave cath``. This saves the function for future sessions.

``funced lessh``, which is slightly more complicated, because it uses the environment variable ``LESSOPEN`` to preprocess the input file(s)::
function lessh LESSOPEN="| pygmentize -O style=native %s" less -M -R $argv end
Test the ``lessh`` function. To save the function run ``funcsave lessh``.