Espanso: Help Wanted: Documentation

[federico-terzi]

Most of the things have been sorted out at the moment. If you want to help, you can proof-read the docs or wait until other entries make their way into the list :)

Hey guys,

I started to notice that the documentation is becoming a bit stale, especially considering the number of features/changes that have been introduced in each release.

If any of you is willing to help me update the docs, that would be super helpful to the project :)

Things that are missing in the docs

I always take some time to write a detailed change log in each version, so that could be a good starting point to see what changed/which are the features to document.

This is a rough list of the things that are missing:

• [x] Mac manual installation instructions (see: https://github.com/federico-terzi/espanso/issues/210#issuecomment-608617197)
• [x] At the end of the Getting Started page, it might be a good idea to add a paragraph explaining how to change the toggle_key, as I receive a lot of requests about it (here are the possible values: https://www.reddit.com/r/espanso/comments/gemz9d/disable_or_change_double_alt_disable_function/fpodyxb?utm_source=share&utm_medium=web2x)
• [ ] Add a "Miscellaneous" section to the docs, to include useful configurations/scripts. In this section, I would add the Rofi Integration and the Script to convert MS dictionaries to espanso matches.
• [x] Remove espanso-bin from the list of AUR packages: https://espanso.org/install/linux/#installing-on-manjaro--arch (until we sort out why it doesn't work reliably, we should remove it)
• [x] Add a "CLI" section to the docs, to include the new CLI options: https://github.com/federico-terzi/espanso/releases/tag/v0.6.3
• [x] Changes to the "Configuration" page:
  
  
  
  • [x] Explain the auto_restart feature: https://github.com/federico-terzi/espanso/releases/tag/v0.6.2 (which is now on by default)
  
  
  • [x] Explaining the fast_inject option: https://github.com/federico-terzi/espanso/releases/tag/v0.5.5 (which is now on by default)
  
  
  • [x] Document the hide icon and notifications options: https://github.com/federico-terzi/espanso/releases/tag/v0.5.5
  
  
  • [x] Document the reason behind the Secure input notification on macOS, as well as how to disable them: https://github.com/federico-terzi/espanso/releases/tag/v0.5.4
  
  
• [x] Update the ShellExtension docs:
  
  
  
  • [x] Refactor the "Trimming the output" section as now trim is true by default. So it should explain how to remove Trim if needed
  
  
  • [x] Document the possibility to use different shells: https://github.com/federico-terzi/espanso/releases/tag/v0.6.0 Here we should add the default values for each OS, as well as the possible values: (see: https://github.com/federico-terzi/espanso/blob/master/src/extension/shell.rs#L96 )
  
  
  • [x] Add a section to explain how to use Unix commands on Windows using the WSL shell
  
  
  • [x] Document the fact that a CONFIG environment variable is injected when executing shell commands: https://github.com/federico-terzi/espanso/issues/277
  
  
• [x] Add a section in the "Packages" section to document how to install a repository from an external repository: https://github.com/federico-terzi/espanso/releases/tag/v0.6.0
• [x] Add a paragraph in the ScriptExtension to document the %HOME% placeholder: https://github.com/federico-terzi/espanso/issues/265
• [ ] Document the Echo extension. Example of usage: https://espanso.org/docs/matches/#advanced-topics

Wow, that was a long one! 😂 I probably missed something, so I'll keep this post updated.

Moreover, I'm sure there are some of you (especially English native speakers) that could make some sections easier to understand. Again, any help is greatly appreciated :)

How to contribute

The docs are located in the gh-pages branch and are written in Markdown with Jekyll. If you want to contribute, please fork espanso, update the docs in the gh-pages branch and open a PR.

Before starting a change, it might be a good idea to write a comment here to make sure nobody started the same task :)

If something is not clear, don't hesitate to contact me or to comment here!

Any help is greatly appreciated :)

[caro401]

Hi, I'd love to help out with this. I've only recently started using Espanso, so I'm not super familiar with the code or less well-documented features yet. Perhaps I could start out with proof-reading and expanding the existing docs (I'm a native English speaker) if that's helpful?

[federico-terzi]

Hey @caro401,
That would be great! Thanks for the help :)

[4lch4]

Hey @federico-terzi, I'm in the same boat as @caro401 here.

I stumbled upon Espanso last night trying to find a replacement to TextExpander that'd work across Mac/Windows/Linux, since I have to move between the three. I'm absolutely in love with Espanso and have already started building a couple packages for various programming languages I work in and tasks I perform regularly.

Here are a couple tasks I would like to tackle:

1. The Mac manual installation instructions, as I have one of them handy and need to install it on that device anyway.
2. Add a paragraph explaining how to change the toggle_key as per the referenced Reddit thread.

I'm not aware of any specific issues open for these though, would you prefer I open a new one for them and then get to work?

[federico-terzi]

Hey @4lch4,

Thanks for the kind words :)

Here are a couple tasks I would like to tackle:
The Mac manual installation instructions, as I have one of them handy and need to install it on that device anyway.
Add a paragraph explaining how to change the toggle_key as per the referenced Reddit thread.
I'm not aware of any specific issues open for these though, would you prefer I open a new one for them and then get to work?

That would be great! There is no need for issues, just open a PR when you are finished and then we will update the post above :)

Thanks again for your help!

[4lch4]

After finishing that up, I noticed the mention of wanting to talk about the Rofi support. Is that out yet?

[federico-terzi]

@4lch4 Yes indeed, you can setup Rofi with the command shown in this post: https://www.reddit.com/r/espanso/comments/hdzcjc/the_upcoming_version_will_make_rofi_integration/fvo3lhg?utm_source=share&utm_medium=web2x

Cheers :)

[yashlala]

I'd like to give this a stab. I'm already reasonably familiar with Jekyll and Espanso. In any case, the changelogs are practically documentation-quality themselves, so familiarity shouldn't be too much of an issue.

This weekend, I'll finish the configuration page, the CLI section, the external packages issue, and some of the quick-fix bullet points such as the espanso-bin task. I'll send a PR when I'm finished — I'm writing this comment mainly so I won't be lazy and put it off ;)

[federico-terzi]

@yashlala Sounds great! Thank you very much for the help :)

[federico-terzi]

I'm currently reviewing the docs myself, so avoid doing any work this weekend if possible :)

[macintacos]

I noticed that there was a type: echo parameter that was shown in the Advanced Topics section of the documentation, but there was no further description of what it is. I know that it's likely just a simplification of the echo shell command, but I figured I'd call it out here.

It's leaving me to wonder what other "type"s there are that are just not documented. I'm not familiar enough with Rust to "figure it out" myself so... perhaps that's another thing to list out?

[federico-terzi]

@macintacos You are definitely right, I missed that one. Thank you for pointing that out.

perhaps that's another thing to list out?

Yes, definitely. It's the simplest possible Extension, which I quietly introduced in version 0.7.0, but could be useful in many situations