snippits
    http://ben.kudria.net/code/snippits
    by Benjamin Kudria


== DESCRIPTION:

This is a Ruby text expansion program for Linux - it will type text for you.  It
uses 'snippits', small text files with a simple syntax to determine what to
type.  However, snippits can be very powerful, since they can contain embedded
Ruby, special keys (Control, Shift, Up, etc), and can contain a cursor placement
instructions.

== REQUIREMENTS:

eRB:: <tt>sudo apt-get install ruby1.8</tt> on Debian/Ubuntu-like
xte:: from the xautomation suite: <tt>sudo apt-get install xautomation</tt> on Debian/Ubuntu-like
ASpell and RASpell:: Not required, but adds extra features: <tt>sudo apt-get install aspell-en</tt> and <tt>sudo gem 
install raspell</tt>

Please consult your distribution documentation on how to install Ruby, Rubygems,
eRB, and ASpell.

== Getting started quickly:

Follow these steps to get started with Snippits quickly.  For more in-depth
instructions, see the INSTALL and USAGE sections.

1. Install required packages.
   On a Debian-like system, run: <tt>sudo apt-get install ruby ruby1.8-dev rdoc rubygems libruby-extras xautomation 
   xclip aspell libaspell-dev aspell-en build-essential</tt>.

   Then, install snippits: <tt>sudo gem install snippits</tt>

2. Configure Ruby to use Rubygems:
   <tt>echo "export RUBYOPT=\"rubygems\"" > ~/.bashrc</tt>,
   then, hit Alt+F2, type <tt>source ~/.bashrc</tt>, hit enter.

3. Create your personal snippits folder: <tt>mkdir ~/.snippits</tt>

4. Create a snippit to test with: edit the file <tt>~/.snippits/name</tt>, type in
   your name, and save the file.

5. In the console, run <tt>snippit name</tt> to *output* your name.

6. Focus on a text box, hit Alt+F2, type <tt>ks name</tt> to *type* your name into
   the textbox

7. Bind a hotkey (method depends on your Desktop Environment, e.g., KDE, GNOME,
   etc) to run the command <tt>ks keyword</tt>.  Open an editor, type <tt>name</tt>, then
   type your hotkey.  The word <tt>name</tt> will disappear, and will be replaced by
   your name

8. To use on-the-fly spelling correction, type a misspelled word, then type your
   hotkeys.  The misspelled word will be replaced with a corrected phrase.

== INSTALL:

Install required software as described above, then:

* sudo gem install snippits

== USAGE:

There are two programs which work together to let you auto-type snippits.

=== snippit
This program looks into the snippits directory (<tt>$HOME/.snippits</tt> by default),and
takes the snippit filename as an argument. It will execute it and output the
result of the snippit  Snippit depends on eRB, embedded Ruby, to be installed.
See REQUIREMENTS above for help with installing eRB, or consult the
documentation for your distribution.

==== SYNTAX:

snippit files are small files with a certain simple syntax.  First, the name of
the file is a parameter that can be passed the snippit command, or used as a
keyword (more about this below).  Then, the contents of the file are plain text,
and will be output as-is.  You also have the option of using embedded Ruby
tags, <% %>, to embed Ruby.  For example, to display the output of 1+1
(in case it ever changes), as evaluated by Ruby, you could write
<% print 1+1 %>, or, more concisely, <%=1+1%>.

=== keyout

This program has a very simple function.  It take a single paramater as input,
and then types it.  It supports toggling modifier keys, direction keys, some
other special keys, and cursor placement.  keyout depends on xte from the
xautomation suite.See REQUIREMENTS above for help with installing xte, or
consult the documentation for your distribution.

==== SYNTAX:

keyout will literally type the paramater you give it, with a few exceptions.
The following special characters are supported:

{enter}, {return}
{tab}
{up}, {down}, {left}, {right}
{backspace}, {delete}
{shift}, {control, {alt}, {meta}
{home}, {end}
{cursor}
{paste}
{sleep}

NOTE: The codes for the modifier keys (Control, Alt, etc)are toggles - type them
once to turn them on, type them again to turn them off.  They are automatically
turned off at the end of execution.

{cursor} places the cursor within the typed text
{sleep} delays execution for 1 second
{paste} types the contents of the snippit whose name is in the clipboard

Include the curly braces in your input.  for example, to type 'aaabbb', and
place the cursor between the a's and b's, do:

keyout 'aaa{cursor}bbb'

Or:
keyout "Fff{shift}g{shift}gg"
results in: FffGgg

And:
keyout "Fff{left}{shift}g{shift}gg" FfGggf
results in: FfGggf

===

There is also  a very small glue script, 'ks'

So, to type your name, or your email
ks name
or
ks eml

I've assigned my most common snippits to shortcut keys
using KDE's KHotkeys program.  Try using multi-key mode to conserve shortcuts.

=== KEYWORD (advanced)

This is a more advanced, and also slightly buggy snippit.  It reads the text you
just typed, to a word boundary, erases the text, and then types the snippit
whose name is the text you just typed.  So, type name, execute the keyword
snippit, and it will type the name snippit.  If the just-typed text is not the
name of a snippit, it be retyped, an run through the spelling dictionary,
if RASpell support is enabled.

== GPG-encrypted files

You might be tempted to store passwords, credit card numbers, your social
security number, etc., in a snippit, but you shouldn't store them in plain
text - they could be compromised.  To help with this, Snippits supports
GPG-encrypted snippits.

To use an encrypted snippit, take your text, encrypt it, and place into a
snippit file as usual.  Then, when snippit encounters a GPG-encrypted file, it
will prompt for the passphrase to unlock your key (or, it will use a running
gpg-agent).  To ensure it selects the right key to decrypt, make sure the
environment variable GPGKEY is set to your key ID.

This feature is still under development, so please test it and submit any bugs
or other issues you discover.

== How to submit patches

Read about the {8 steps for fixing other people's 
code}[http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/] and for section 8c,
visit the {Snippits Rubyforge page}[http://rubyforge.org/projects/snippits/]
The repository is svn://rubyforge.org/var/svn/snippits/ for anonymous access.

== LICENSE:

GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

See LICENSE.txt for the entire License text.