espanso/README.md

136 lines
3.3 KiB
Markdown
Raw Normal View History

2019-09-16 10:50:51 +00:00
![espanso](images/titlebar.png)
2019-09-15 17:10:18 +00:00
2019-09-16 12:42:51 +00:00
> A cross-platform Text Expander written in Rust
2019-09-15 17:10:18 +00:00
2019-09-16 12:25:09 +00:00
![Language](https://img.shields.io/badge/language-rust-orange)
![Platforms](https://img.shields.io/badge/platforms-Windows%2C%20macOS%20and%20Linux-blue)
![License](https://img.shields.io/github/license/federico-terzi/espanso)
2019-09-16 10:50:51 +00:00
![example](images/example.gif)
2019-09-15 17:10:18 +00:00
2019-09-16 12:42:51 +00:00
#### What is a Text Expander?
2019-09-15 17:35:05 +00:00
2019-09-15 18:25:33 +00:00
A *text expander* is a program that detects when you type
2019-09-15 17:35:05 +00:00
a specific **keyword** and replaces it with **something else**.
This is useful in many ways:
2019-09-15 18:25:33 +00:00
* **Save a lot of typing**, expanding common sentences.
* Create **system-wide** code snippets.
* Execute **custom scripts**
* Use **emojis** like a pro.
2019-09-15 17:35:05 +00:00
2019-09-16 12:42:51 +00:00
___
## Key Features
2019-09-15 17:10:18 +00:00
2019-09-15 17:35:05 +00:00
* Works on **Windows**, **macOS** and **Linux**
2019-09-15 18:25:33 +00:00
* Works with almost **any program**
2019-09-15 17:35:05 +00:00
* Works with **Emojis** 😄
* **Date** expansion support
* **Custom scripts** support
* **Shell commands** support
* **App-specific** configurations
2019-09-15 17:10:18 +00:00
* File based configuration
2019-09-16 12:25:09 +00:00
## Table of contents
- [Installation](#installation)
- [Windows](#install-windows)
- [Linux](#install-linux)
- [macOS](#install-macos)
2019-09-18 09:55:18 +00:00
- [Usage](#usage)
2019-09-16 12:25:09 +00:00
- [FAQ](#faq)
- [Donations](#donations)
- [License](#license)
## Installation
### <a name="install-windows"></a>Windows
2019-09-17 18:46:48 +00:00
TODO
2019-09-16 12:25:09 +00:00
### <a name="install-linux"></a>Linux
2019-09-17 18:46:48 +00:00
TODO
2019-09-16 12:25:09 +00:00
### <a name="install-macos"></a>MacOS
2019-09-15 17:10:18 +00:00
The easiest way to install espanso on macOS using the [Homebrew](https://brew.sh/)
package manager, but you can also do it manually.
#### Using Homebrew
The first thing to do is to add the official espanso *tap* to Homebrew with
the following command:
```
brew tap federico-terzi/espanso
```
Then you can install espanso with:
```
brew install espanso
```
To make sure that espanso was correctly installed, you can open a terminal and type:
```
espanso --version
```
At this point, you have to [Enable Accessibility](#enabling-accessibility) to use espanso.
#### Enabling Accessibility
Because espanso uses the macOS [Accessibility API](https://developer.apple.com/library/archive/documentation/Accessibility/Conceptual/AccessibilityMacOSX/)
to work, you need to authorize it using the following procedure:
Open a terminal and type the command:
```
espanso install
```
A dialog should show up, click on "Open System Preferences", as shown here:
![Accessibility Prompt](images/accessibility-prompt.png)
Then, in the "Privacy" panel click on the Lock icon (1) to enable edits and
then check "espanso" (2), as shown in the picture:
![Accessibility Settings](images/accessibility-macos-enable.png)
Now open the terminal again and type:
```
espanso install
```
If everything goes well, you should see the espanso icon appear in the status bar:
![macOS status bar icon](images/espanso-icon-macos-statusbar.png)
If you now type `:espanso` in any text field, you should see "Hi there!" appear!
2019-09-17 18:46:48 +00:00
2019-09-18 09:55:18 +00:00
## Usage
TODO
2019-09-16 12:25:09 +00:00
## FAQ
2019-09-15 17:10:18 +00:00
2019-09-17 18:46:48 +00:00
#### How does espanso work?
2019-09-15 17:10:18 +00:00
2019-09-17 18:46:48 +00:00
TODO
2019-09-15 17:10:18 +00:00
2019-09-16 12:25:09 +00:00
## Donations
2019-09-16 10:50:51 +00:00
espanso is a free, open source software developed in my (little) spare time.
If you liked the project and would like to support further development,
please consider making a small donation, it really helps :)
2019-09-15 17:10:18 +00:00
2019-09-16 10:50:51 +00:00
[![Donate with PayPal](images/donate.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=FHNLR5DRS267E&source=url)
2019-09-15 17:10:18 +00:00
2019-09-16 12:25:09 +00:00
## License
2019-09-15 17:10:18 +00:00
2019-09-15 17:35:05 +00:00
espanso was created by [Federico Terzi](http://federicoterzi.com)
and is licensed under the [GPL-3.0 license](/LICENSE).