Added readme and license files.

README.rst

@@ -3,3 +3,139 @@ urxvt-wrapper
 =============
 
 Simplify invoking urxvt terminal from commandline.
+
+Motivation for creating this little script was to have ability to simply run
+urxvt with predefined features (like icons/font size/perl script list etc),
+without providing a ton of parameters nor keeping track of resources in
+``~/.Xdefaults`` file.
+
+
+Installation
+------------
+
+Simply put the script preferably in your ``$PATH``.
+
+There are a few dependencies:
+
+* Python
+* ``fc-list`` from fontconfig package
+* ``urxvt`` obviously (package is often called *rxvt-unicode*) built with XFT
+  support.
+* using ``--tabbedalt`` switch requires `tabbedalt`_ plugin.
+
+Also, there are three fonts internally used:
+
+* `Symbola`_ - Font with rich set of emoji glyphs
+* `Unifont`_ - Bitmap font with rich set of unicode glyphs
+* `DejaVu Sans`_ - which provides several more unicode glyphs
+
+All these fonts will be concatenated with the main font(s). If you don't have
+any of them, that's ok, they simply be filtered out. Although, I would
+recommend to install them to be able to display unusual glyphs/emoji.
+
+
+Configuration
+-------------
+
+There are several environment variables available to be put in ``~/.bashrc`` or
+such, which will have an impact on the defaults wrapper have. So here is the
+list of variables, with their default values:
+
+* ``URXVT_BMP``: ``[empty]`` - Font to be used as bitmap font (like `font-misc-misc`_
+  from xorg, or `terminus`_) before all the font defined in ``URXVT_TTF``. You
+  need to provide valid xft name for the font, so it is basically a convenient
+  way for having bitmap font available to use with ``--bitmap`` switch, for
+  details see below.
+* ``URXVT_ICON_PATH``: ``~/.urxvt/icons`` - Path for icons images.
+* ``URXVT_ICON``: ``[empty]`` - Icon to be used with the terminal.
+* ``URXVT_PERL_EXT``: ``url-select,keyboard-select,font-size,color-themes`` -
+  Comma separated list of perl extensions for the urxvt.
+* ``URXVT_RUN_DIRECT``: ``false`` - Urxvt can be run using simply ``urxvt``
+  executable or with daemon (``urxvtd``) and client (``urxvtc``). By default
+  the latter will be chosen for launching new terminal. Note, that you don't
+  need to manually run ``urxvtd`` - it will be run automatically on absence.
+* ``URXVT_SIZE``: 14 - font size. It's applied to all fonts.
+* ``URXVT_TTF``: ``[empty]`` - Font or comma separated font list to be used. Note,
+  that first font become main font, and the others will be used for glyphs that
+  are missing from the previous one. That makes the order of the selected fonts
+  crucial. See below for examples.
+
+Usage
+-----
+
+Simplest case is just to run it without any parameter (assuming script is
+somewhere in ``$PATH``:
+
+.. code:: shell-session
+
+   $ urxvt.py
+
+To run urxvt with *Hack Nerd Font* and *Webdings* xft fonts:
+
+.. code:: shell-session
+
+   $ urxvt.py -f 'Hack Nerd Font Mono,Webdings'
+
+If you wondering how to look for the particular font name, you can use
+``fc-list`` command. Let's try to look for the *Hack Nerd* font:
+
+.. code:: shell-session
+
+   $ fc-list|grep -i hack
+   /home/gryf/.fonts/Nerd Fonts/Hack Italic Nerd Font Complete Mono.ttf: Hack Nerd Font Mono:style=Italic
+   /home/gryf/.fonts/Nerd Fonts/Hack Bold Italic Nerd Font Complete Mono.ttf: Hack Nerd Font Mono:style=Bold Italic
+   /home/gryf/.fonts/Nerd Fonts/Hack Regular Nerd Font Complete Mono.ttf: Hack Nerd Font Mono:style=Regular
+   /home/gryf/.fonts/Nerd Fonts/Hack Bold Nerd Font Complete Mono.ttf: Hack Nerd Font Mono:style=Bold
+
+there are four files found. Every line can be divided using colon as a
+separator. First part of the line is the complete path to the
+font, then there is a comma separated list of names of the font and finally
+comma separated style list after ``style=`` keyword. For this example, name of
+the font is common for all four files, and the difference is in style only, and
+the name is **Hack Nerd Font Mono**.
+
+To use bitmap font (which still be used through the xft library, and defined as
+such), assuming that ``URXVT_BMP`` env variable contain name of the font (for
+example **Misc Fixed**) , it is simple enough to:
+
+.. code:: shell-session
+
+   $ urxvt.py -b
+
+Note, that this is exactly the same as:
+
+.. code:: shell-session
+
+   $ urxvt.py -f 'Misc Fixed'
+
+For more options, issue:
+
+.. code:: shell-session
+
+   $ urxvt.py -h
+
+to see complete list of supported parameters.
+
+Finally, you can pass all valid urxvt options to the executable. Just use
+``--`` delimiter and than use any valid params:
+
+.. code:: shell-session
+
+   $ urxvt.py -f 'Hack Nerd Font Mono' -n -s 16 -- -cr orange
+
+which set the regular and bold font face to *Hack Nerd* font with its size set
+to 16, without any perl extension and cursor color set to orange.
+
+
+License
+-------
+
+This work is licensed under GPL3. See LICENSE file for details.
+
+
+.. _terminus: http://terminus-font.sourceforge.net/
+.. _font-misc-misc: https://gitlab.freedesktop.org/xorg/font/font-misc-misc
+.. _tabbedalt: https://github.com/gryf/tabbedalt
+.. _Symbola: http://luc.devroye.org/fonts-47197.html
+.. _Unifont: http://unifoundry.com/
+.. _DejaVu Sans: https://dejavu-fonts.github.io/