README.txt

Path: README.txt
Last Update: Mon Feb 18 23:27:17 -0500 2008
dot/f_0.png

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

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: sudo apt-get install ruby ruby1.8-dev rdoc rubygems libruby-extras xautomation xsel aspell libaspell-dev aspell-en build-essential.

    Then, install snippits: sudo gem install snippits

  2. Configure Ruby to use Rubygems: echo "export RUBYOPT=\"rubygems\"" > ~/.bashrc, then, hit Alt+F2, type source ~/.bashrc, hit enter.
  3. Create your personal snippits folder: mkdir ~/.snippits
  4. Create a snippit to test with: edit the file ~/.snippits/name, type in your name, and save the file.
  5. In the console, run snippit name to output your name.
  6. Focus on a text box, hit Alt+F2, type ks name 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 ks keyword. Open an editor, type name, then type your hotkey. The word name 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 ($HOME/.snippits 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 and for section 8c, visit the Snippits Rubyforge page 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.

[Validate]