Add Terminal Tips Documentation (#2425)

* add Terminal Tips Documentation - Issue #2131

* add newlines after ::, typo

* Add highlight directive

---------

Co-authored-by: Jean Abou Samra <jean@abou-samra.fr>

2 files changed, 106 insertions, 0 deletions

diff --git a/doc/docs/index.rst b/doc/docs/index.rst
index 930467c4..3db2b107 100644
--- a/doc/docs/index.rst
+++ b/doc/docs/index.rst
@@ -46,6 +46,7 @@ Pygments documentation
 .. toctree::
    :maxdepth: 1
 
+   terminaltips
    rstdirective
    moinmoin
    java
diff --git a/doc/docs/terminaltips.rst b/doc/docs/terminaltips.rst
new file mode 100644
index 00000000..c81ab80d
--- /dev/null
+++ b/doc/docs/terminaltips.rst
@@ -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``.