README.md in talks-0.2.0 vs README.md in talks-0.3.0
- old
+ new
@@ -1,73 +1,95 @@
# Talks gem — now your ruby and command-line tools can talk with you
-### This is beta now.
-
### Build Status 
If you want to HEAR some response from your code or command-line tools, just use this gem.
-You can use this gem on MacOS X and on other linux/unix systems with installed [espeak](http://espeak.sourceforge.net).
+You can use this gem on MacOS X and on other linux/unix systems with [espeak](http://espeak.sourceforge.net) installed.
+Now with support for notifiers through [notifier](https://github.com/fnando/notifier) gem!
+Check the notifier's
+[README](https://github.com/fnando/notifier/blob/master/README.rdoc) and
+find what notifier you want to use - there is support for every OS!
+
+I added in all sections of this readme notes about usage notifier
+functionality.
+
Sponsored by Evil Martians <http://evilmartians.com>
## Why?
-For example - some really long task and you just get some coffee, read book or surf internet
-and you want to know when this task will ends, but don't want to check your mac or terminal each minute -
-you can just add small hook in the end of your code and when it will ends - you will hear it with voice that you
-choose from MacOS X `say` function collection or from `espeak` collection.
+### Example
+You're running some really long task and you leave the desk to drink some coffee, read a book or surf the internet
+and you want to be notified that the task has finished its execution. You don't want to check your machine each minute. With this gem
+you can just add a little hook at the end of your code and when the execution ends - you will hear it in voice
+that you have chosen from MacOS X `say` function collection or from `espeak` collection.
+
+Now if you forgot power on you sound on machine you can always see
+notifications by notifiers like Growl, Kdialog, Knotify, etc. Full list of notifiers is
+[here](https://github.com/fnando/notifier/blob/master/README.rdoc).
+
You can find some examples of `talks` usage in organization [ruby-talks](https://github.com/ruby-talks):
* [rails-talks](https://github.com/ruby-talks/rails-talks)
* [bundler-talks](https://github.com/ruby-talks/bundler-talks)
* [spec-talks](https://github.com/ruby-talks/spec-talks)
## How?
-On MacOS X this gem just using native MacOS X `say` command line tool.
-On linix/unix this gem using espeak speech synthesis.
+On MacOS X this gem is just using the native MacOS X `say` command line tool.
+On linix/unix this gem is using espeak speech synthesis.
-### In all examples below I used MacOS X voice types. For espeak you can read section [Using talks with espeak](https://github.com/ruby-talks/talks#using-talks-with-espeak)
+For notifications this gem uses [notifier](https://github.com/fnando/notifier/blob/master/README.rdoc) gem.
+### In all examples below I've used MacOS X voice types. For espeak you can read section [Using talks with espeak](https://github.com/ruby-talks/talks#using-talks-with-espeak)
+
### Configuration
You can configure default voices and messages for `talks` with `~/.talksrc` file or with `your_project/.talksrc` file. It should be written in YAML format:
`~/.talksrc`
```yml
default_voice: 'whisper'
engine: 'say'
+notifier: 'off' # if this option passed - you will not receive notifications at all
voices:
info: 'pipe'
messages:
info: 'hello'
warn: 'WE GONNA DIE!!!'
```
-The same you can do in your code dynamicly through Talks.config instance.
-You can configure now only default voice for `say` method and voices and messages for 4 types of talks: `info, warn, success, error`
+You can also do it in your code dynamically through Talks.config instance.
+You can configure only the default voice for `say` method and voices and messages for 4 types of talks: `info, warn, success, error`
+
For command-line commands you can configure default voices and hook messages:
`~/.talksrc`
```yml
bundle:
voice: 'vicki'
before_message: 'Bundler again will do all right'
after_message: "Bundler's job is done here"
+ before_notify: 'This will go to notification before `before_message`'
+ after_notify: 'This will go to notification after `after_message`'
+# notifier: 'off' # this option will turn off notifications for this command
```
You can create your own default preferences for each command-line tool which you want to run with `talks` or `talking` command in front:
`~/.talksrc`
```yml
ls:
voice: 'bad'
before_message: 'Now we will see what in the directory'
- after_message: ''
+ after_message: '.'
+ before_notify: 'This will go to notification before `before_message`'
+ after_notify: 'This will go to notification after `after_message`'
+# notifier: 'off' # this option will turn off notifications for this command
cap:
...
vim:
...
scp:
@@ -82,18 +104,25 @@
```bash
$ talking bundle install
```
After that `talks` will wrap execution of this command with voice messages. By default messages will be like 'command_name task started/ended'.
-You can preconfigure messages in your `~/.talksrc` file or you can send options right in talking command:
+You can preconfigure messages in your `~/.talksrc` file or you can send options right in the talking command:
```bash
$ talking -v agnes -bm 'We gonna die!' -am 'Not sure if we can hear that' rm -rf ./
# the same
$ talking --voice agnes --before-message 'We...' --after-message 'Not...' rm -rf ./
```
+The same with notifications:
+```bash
+$ talking -v agnes -bn 'We gonna die!' -an 'Not sure if we can hear that' rm -rf ./
+# the same
+$ talking --voice agnes --before-notify 'We...' --after-notify 'Not...' rm -rf ./
+```
+
### Using talks in your code
```bash
$ gem install talks
```
@@ -108,40 +137,41 @@
# There are 4 types of voice: say or info, warn, success, error
Talks.info 'This is info'
# Talks.warn 'Some text'
# Talks.success 'Some text'
# Talks.error 'Some text'
+Talks.notify 'This will be shown to you by your notifier'
```
-`Talks.say` can be customized with type of message and voice by adding options to executing this method:
+`Talks.say` can be customized with type of message and voice by adding options to this method parameters:
```ruby
Talks.say 'Hello like pipe', voice: 'pipe'
Talks.say 'Hello like error', type: :error # the same as using Talks.error
```
-All voices which I found in manual for `say`:
+All voices which I've found in `say` manual:
```ruby
VOICES = %w(
agnes albert alex bad bahh bells boing bruce bubbles cellos
deranged fred good hysterical junior kathy pipe princess ralph
trinoids vicki victoria whisper zarvox
)
```
### Using talks with espeak
-You can configure your `talks` usage even on MacOS X for using [espeak](http://espeak.sourceforge.net):
+You can configure your `talks` engine even to tell MacOS X to use [espeak](http://espeak.sourceforge.net):
`~/.talksrc`
```yml
engine: 'espeak'
```
-Otherwise `talks` will set engine by default to `say` on MacOS X and to `espeak` on all other OS if command `which espeak` returns something than empty string.
+Otherwise `talks` will set engine by default. It will be set to `say` on MacOS X and to `espeak` on all other OS-es if command `which espeak` returns non-empty string.
-For espeak you have different set of voices and many languages (which this gem not support yet). Voices for espeak:
+You can even configure your language in espeak (this gem still doesn't support different languages). Voices for espeak:
```ruby
Talks.voices[:espeak]
# =>
[
@@ -150,22 +180,26 @@
]
```
## Who?
-I did it by myself
+I did it myself.
### Contributors
* @gazay
### A lot of thanks
- * @aderyabin - idea of extended customization of talks is his.
+ * @kossnocorp - for idea with notifiers.
- * @brainopia - bro helps me with any my idea. He adviced me to do command line tool talks.
+ * @shime - for grammar fixes in readme and better explanation of my idea.
-You can help me with this fun gem and I'll gladly add you here, or above
+ * @aderyabin - extended customization of talks is his idea.
+
+ * @brainopia - bro helps me with any idea of mine. He advised me to do command line tool talks.
+
+You can help me with this fun gem and I'll gladly add you here, or above.
## License
The MIT License