open.source/espanso
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update 'installing from repo' & 'publishing on expanso hub' instructions

Browse Source 
Fix some punctuations and add line breaks for long sentences in
"Getting Started" doc
This commit is contained in:
Muhammed Zakir 2020-08-18 01:01:40 +05:30
parent a480ad1a03
commit 7ddd5c1e6d
2 changed files with 67 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
docs/get-started.md
View File

@ -2,16 +2,18 @@
title: Getting Started
layout: docs
---
In this section we will cover the basics of espanso to get you started immediately.
In this section, we will cover the basics of espanso to get you started immediately.
Make sure to [install espanso](/install) before diving into the next sections.
### Starting espanso
If you followed the [Windows](/install/win/) or [MacOS](/install/mac/) installation correctly, **espanso will be automatically started** when you power up your computer. There are times, however, when you may need to start
espanso explicitly, such as when you're using Linux.
If you followed the [Windows](/install/win/) or [MacOS](/install/mac/) installation correctly,
**espanso will be automatically started** when you power up your computer. There are times,
however, when you may need to start espanso explicitly, such as when you're using Linux.
It's very easy to check if espanso is currently running: if you're using **MacOS** or **Windows**, you should see
the **icon in the status bar**. If you don't see it, or if you're using **Linux**, another way to check it is to **open a terminal** and type:
It's very easy to check if espanso is currently running: if you're using **MacOS** or **Windows**,
you should see the **icon in the status bar**. If you don't see it, or if you're using **Linux**,
another way to check it is to **open a terminal** and type:
```bash
espanso status
@ -23,8 +25,8 @@ If you see "`espanso is not running`", then you'll need to start espanso manuall
espanso start
```
At this point you are ready to use espanso. Open any typing application and type `:espanso`, you should
see `Hi there!` appear.
At this point you are ready to use espanso. Open any typing application and type `:espanso`,
you should see `Hi there!` appear.
If you don't see it, make sure espanso is currently running. You could also try to repeat the installation procedure.
@ -35,12 +37,14 @@ espanso works by **detecting** your keypresses and **replacing** them when they
![How espanso works](/assets/images/match1.png)
The rule that associate the *trigger* with the *replaced text* is called **Match** and is a core concept of espanso.
Matches are very flexible and powerful to solve many tasks. You can learn all about Matches in their [documentation](/docs/matches/) page.
Matches are very flexible and powerful to solve many tasks.
You can learn all about Matches in their [documentation](/docs/matches/) page.
![Match](/assets/images/match2.png)
espanso ships with very few built-in Matches to give you the maximum flexibility, but you can expand its capabilities
in two ways: creating your own **custom matches** or **installing packages**. Both of these possibilities are introduced below.
in two ways: creating your own **custom matches** or **installing packages**.
Both of these possibilities are introduced below.
### Configuration
@ -51,6 +55,8 @@ reside in the `espanso` directory, whose location depends on the current OS:
* macOS: `$HOME/Library/Preferences/espanso` (e.g. `/Users/user/Library/Preferences/espanso`)
* Windows: `{FOLDERID_RoamingAppData}\espanso` (e.g. `C:\Users\user\AppData\Roaming\espanso`)
By default, configuration folder is hidden in most systems. To open it, copy path of your
configuration folder and paste it in the address bar (aka path bar) of your file manager/explorer.
A quick way to find the path of your configuration folder is by using the following command:
```bash
@ -78,7 +84,8 @@ Jon Snow
By now you should know that we need to **define a Match**.
With your favourite text editor, open the `.espanso/default.yml` file, introduced previously in the [Configuration](#configuration) section. You should see something like:
With your favourite text editor, open the `.espanso/default.yml` file, introduced previously in the
[Configuration](#configuration) section. You should see something like:
```yml
# espanso configuration file
@ -134,17 +141,21 @@ espanso restart
Now try to type `:br` anywhere. If you did everything correctly, you should see `Best Regards` appear!
> In version 0.5.1, espanso introduced the `edit` subcommand which makes editing configuration files much easier. Take a look at [Quick Editing](/docs/configuration/#quick-editing) if you are interested.
> In version 0.5.1, espanso introduced the `edit` subcommand which makes editing configuration files much easier.
Take a look at [Quick Editing](/docs/configuration/#quick-editing) if you are interested.
### Understanding Packages
Custom matches are amazing, but sometimes it can be tedious to define Matches for every **common operation**,
and even more when you want to **share them with other people**.
espanso offers an easy way to **share and reuse matches** with other people, **packages**. In fact, they are so important that espanso includes a **build-in package manager** and a **store**, the [espanso hub](https://hub.espanso.org/).
espanso offers an easy way to **share and reuse matches** with other people, **packages**. In fact,
they are so important that espanso includes a **build-in package manager** and a **store**,
the [espanso hub](https://hub.espanso.org/).
If you are lucky enough, someone might have already written a **package** to include the matches you need!
Otherwise, you can create a package and publish it on the hub, for more information check out the [Packages](/docs/packages/) documentation.
Otherwise, you can create a package and publish it on the hub, for more information check out the
[Packages](/docs/packages/) documentation.
### Installing a Package
@ -170,7 +181,8 @@ If you now type `:ook` into any text field, you should see 👍👍👍👍 appe
Let's conclude this introduction with the most important shortcut espanso offers, the **toggle shortcut**:
There are times when you may want to **disable espanso to avoid an unwanted expansion**. This can be
easily accomplished by quickly **double pressing the `ALT` key** ( Option on MacOS ). You should then see a notification showing "Espanso disabled".
easily accomplished by quickly **double pressing the `ALT` key** ( Option on MacOS ). You should then
see a notification showing "Espanso disabled".
At this point, espanso will be disabled and will not expand any match.
@ -179,9 +191,13 @@ To **re-enable** it, double press the `ALT` key again.
#### Customizing the Toggle Key
By default, espanso can be temporarily disabled & enabled by pressing the Alt key twice, resulting in a notification saying "espanso disabled." Pressing Alt twice again will enable it, and you'll receive a notification saying "espanso enabled." This does not turn off espanso, it simply disables it until you enable it again.
By default, espanso can be temporarily disabled & enabled by pressing the Alt key twice, resulting in a
notification saying "espanso disabled." Pressing Alt twice again will enable it, and you'll receive a
notification saying "espanso enabled." This does not turn off espanso, it simply disables it until
you enable it again.
If you'd like to customize this behavior, simply add the `toggle_key` option to your previously mentioned `default.yml` and set it to `OFF` or one of the available options:
If you'd like to customize this behavior, simply add the `toggle_key` option to your previously mentioned
`default.yml` and set it to `OFF` or one of the available options:
| | | | |
|--------------|-------------|---------------|--------------|
@ -189,7 +205,10 @@ If you'd like to customize this behavior, simply add the `toggle_key` option to
| `LEFT_CTRL` | `LEFT_ALT` | `LEFT_SHIFT` | `LEFT_META` |
| `RIGHT_CTRL` | `RIGHT_ALT` | `RIGHT_SHIFT` | `RIGHT_META` |
Using the above example `default.yml`, if I wanted to make it so espanso is disabled/enabled when I press the left control key twice. To do this, I add `toggle_key: LEFT_CTRL` to the file like so, and then pressing the left control key twice disables/enables espanso:
Using the above example `default.yml`, if I wanted to make it so espanso is disabled/enabled when I press
the left control key twice, I add `toggle_key: LEFT_CTRL` to the file like so, and then, pressing
the left control key twice disables/enables espanso.
```yml
# espanso configuration file
@ -219,4 +238,3 @@ toggle_key: OFF
```
After the changes are made, if you used `espanso edit` it will automatically restart. If not, issue a `espanso restart` and you'll be ready to go!

50
docs/packages.md
View File

@ -2,7 +2,7 @@
title: Packages
layout: docs
---
**Packages** makes it easy to reuse Matches created by other people or **share** yours with the world. Thanks
**Packages** make it easy to reuse *Matches* created by other people or **share** yours with the world. Thanks
to [espanso hub](https://hub.espanso.org/), the official **espanso package repository**, and the **built-in
package manager**, using them is a breeze.
@ -29,18 +29,25 @@ espanso restart
#### External Packages
Some packages (namely the bigger ones that would make the core repository too large) are now considered external, and espanso will block the installation by default, prompting the user to verify the source of the package (the repository).
Some packages (namely the bigger ones that would make the core repository too large) are now considered external,
and espanso will block the installation by default, prompting the user to verify the source of the package (the repository).
In case the user wants to proceed with the installation, a the `--external` flag could be used:
In case the user wants to proceed with the installation, the `--external` flag could be used:
```
espanso install <package> --external
espanso install <package_name> --external
```
#### From a Repository
Currently packages can only be installed from the [espanso hub](https://hub.espanso.org/), but direct
installation from a repository is coming soon. Follow the status on this [Issue](https://github.com/federico-terzi/espanso/issues/55).
To install from a repository, pass repository's URL after package name. Like the above command,
espanso will block the installation without `--external` flag.
```
espanso install <package_name> <repo_url> --external
```
**Note**: Given repository must be in compliance with the specification described in [Creating a Package](#creating-a-package).
### Listing Installed Packages
@ -58,9 +65,9 @@ To remove a package, open a terminal and type:
espanso uninstall <package-name>
```
Where `<package-name>` is the name of the package. You can obtain that name [listing installed packages](#listing-installed-packages).
where `<package-name>` is the name of the package. You can obtain that name by [listing installed packages](#listing-installed-packages).
Then don't forget to **restart** espanso using:
Then, don't forget to **restart** espanso using:
```
espanso restart
@ -72,22 +79,22 @@ espanso restart
package creation process will be improved in the future.
In their basic form, Packages are just **configuration files**, very similar to
[those you've seen before](/docs/configuration), with a few *metadata* to describe them.
[those you've seen before](/docs/configuration), with a few *metadata* fields to describe them.
Packages are hosted on **GitHub repositories**. To create one, go ahead and
Packages must be hosted on **GitHub repositories**. To create one, go ahead and
fork the [espanso package example](https://github.com/federico-terzi/espanso-package-example/) repo.
From that example you can create your own package in a few easy steps:
1. Change the `simple-package` directory name to your desired **package name** (only alphanumeric characters and '-' are
allowed)
2. Change the **metadata** in the header of the `simple-package/README.md` file, where:
* `package_name` is the name of the package ( must be the same as the directory )
* `package_title` human friendly version of the package name.
* `package_desc` a **short** description of the package
* `package_version` the version of the package, you should not change this one when you start.
* `package_author` your name
* `package_repo` the repo address of this package, should match the final github address
2. Change the **metadata** in the header of the `simple-package/README.md` file:
* `package_name` name of the package (must be the same as the directory)
* `package_title` human friendly version of the package name
* `package_desc` a **short** description of the package
* `package_version` the version of the package, you should not change this one when you start
* `package_author` your name
* `package_repo` URL of this package repository - https://github.com/<username>/<repo_name>
3. Then after the `---` you can write the package description using the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) syntax.
4. Modify the `package.yml` file contained in the `0.1.0` folder (matching the package version) by **changing the name** and **including your Matches**. For example:
@ -105,5 +112,10 @@ allowed)
#### Publishing on espanso hub
After following all these steps, you can request to publish your package to [espanso hub](http://hub.espanso.org)
by opening an [Issue](https://github.com/federico-terzi/espanso-hub/issues) with the following information:
* The package **repository** url
by opening an [Issue](https://github.com/federico-terzi/espanso-hub/issues) with the following format:
* Title: 'New package - <package name>'
* Body:
* The package **repository** url
* A short description of your package
* List of replacements and optionally, their descriptions
* Requirements/Dependencies, if any