espanso / website Goto Github PK

Hello ! Here is a little markdown tutorial draft I just made to help people grasp some key beginner concepts. I made use of the 'Task' features of Markdown to help people going to the end by checking what was done or not. (Made with Obsidian.md, maybe some parts will be broken if you use another markdown reader). Feedback welcomed, no copyrights wanted.

Guided Tutorial.md

I put a list of documentation updates on the main repo Issue list, but it might fit better here.

A few items I have spotted. By no means exclusive!

ToDo:

• Privacy Policy #1560 security.md is due for an update, #18

Done:

• Usage of use_standard_includes:. I think I have worked it out - see this Discord entry. For a while I thought it should be deprecated like force_clipboard: true, rather than documented, but it may simplify things for some people.
• Examples of single-line format [...] for short sequences
• Add section about quoting (or not) values in Espanso YAML
• I'd like to rewrite many of the simple code examples without quote marks where they're not needed
• cmd.exe won't work as a multiline inline shell: expansion
• Only one app-specific config can apply at any time
• Include examples of embedding multiline scripts and shell commands in triggers
• Remove the link to our out-dated gist list of date formats, leaving a link to the source material only - espanso/espanso#1072
• Update migration advice to suggest moving the legacy packages folder to espanso/match/packages
• Add #acfg#, #pacfg# & #pdetect#
• Variable names can only be alphanumeric or underscore characters.
• Available match options #10 - all these are now present in the documentation in appropriate sections - I'm not sure a separate list would be useful, so I've added a link to the relevant file and lines in the main repo.
• Usage of search_terms:
• Other options listed here: x11_use_xdotool_backend, emulate_alt_codes, post_search_delay, post_form_delay.
• emulate_alt_codes: true see here
• filter_os: rule
• Autofix in the documentation seems to be outdated #1767
• Update links to federico-terzi/espanso to espanso/espanso?
• MacOS brew installation docs should be updated #1804
• ?add Discord server to the docs header
• Plain scalar Regex triggers are easier to debug if we don't have to escape every “\”. I'll add a note about this.
• force_mode: clipboard|keys and force_clipboard: true (possible duplicate of the first) #1690 Are there other undocumented controls? (See parse.rs.)
• left_word: ord right_word: controls. See here.
• Document markdown & html #1806
• paragraph: prevents markdown: starting a new paragraph. See here.
• Factors determining size of forms - [Discord conversation] (https://discord.com/channels/884163483409731584/1013916990760554608/1185019971185692682) & [Reddit] (https://www.reddit.com/r/espanso/comments/18ibpbi/help_with_making_forms_better/) summary
• Output of UTF8 foreign characters (in Windows?) #1736 #1749 #1698
• Ability to output Unicode characters, e.g. replace: "\u0105" (UTF-16), or "\U00000105" (UTF-32) or "\xC4" (UTF-8?)
• Multiple filters, need to apply alphabetically by filename to determine application order #1269
• CTRL-character triggers are possible but likely to cause problems in editors, and over-delete characters on triggering #383

Request: Add security section for Espanso to main website/documentation

As a long-time user of Espanso I am often preaching its virtues; but recently encountered some FUD: a friend installed but then immediately uninstalled Espanso worrying about the fact that it captures all keyboard input, including potentially passwords (which it does not - see below)

It's not an unreasonable worry, and it is actually addressed, it's just not easy to find, tucked away at https://github.com/espanso/espanso/security/policy

While espanso detects key presses as a keylogger would do, it doesn't log anything. Moreover, to further reduce risks, espanso only stores in memory the last 3 chars by default (you can change this amount by setting the backspace_limit parameter in the config) and this is needed to allow the user to correct wrongly typed triggers by pressing backspace, up to 3 characters.

The documentation already includes a list of all available config options - it would also be helpful to include a list of all available match options.

For example, this could be helpful if one wants to quickly check which are valid match types:

    vars:
      - name: mydate
        type: date
    vars:
      - name: output
        type: choice
# ...

I've had a look through the website and also the Espanso repo, but couldn't something that quickly shows which YAML keys & values are valid.

@federico-terzi do you think this is something we should add to the website or would https://github.com/federico-terzi/espanso be a better fit?

I am trying to create some global variables that are some informative text linked to a website, like this: stackoverflow post showing how to format a link in YAML. I can't seem to figure out the right way to set these up. I've tried searching the documentation for 'link', 'params', and 'global_vars', but haven't seen anything about doing links in YAML.

(code block updated to correct typo)

global_vars:
  - name: formatted_link
    type: echo
    params:
      echo: [Displayed Text](url)
•••
matches:
  - trigger: :link
    replace: {{formatted_link}}

I get this output:

Caused by:
    0: failed to parse YAML match group
    1: while parsing a block mapping, did not find expected key at line 21 column 31
    2: while parsing a block mapping, did not find expected key at line 21 column 31

(The column numbers are going to be based off of my actual text, but correspond to the first character inside the parentheses—the start of the url.)

Replacing echo with format does not seem to work, either, and I'm not sure what other kinds of params are valid. Putting the link inside quotation marks results in nothing being evaluated, but does stop the error.

Given VS Code's popularity with developers, and misbehaviour when not used with force_mode: clipboard (espanso/espanso#675) we could add a wee tutorial on writing a VS Code specific config file.

It'd give us a few advantages:

1. Easy to point people to when they're having VS Code problems
2. A nice way to demonstrate app-specific config exists and is easy
3. Could start a "Cookbook" style section
4. Something to share in dev circles to attract more assistance :P

Hi Espanso team,

I really like the website and documentation, great work! I noticed that search is missing - have you already considered adding it using: https://docusaurus.io/docs/search?

Cheers