taloncommunity/wiki

Community maintained wiki for Talon Voice

wiki's Issues

wiki index points to missing videos

https://github.com/TalonCommunity/Wiki/blob/main/index.md

points to https://github.com/TalonCommunity/Wiki/blob/main/videos

which no longer exists

The page source link is broken

When clicking the 'source' link on a page I end up in an infinite redirect loop.

The link goes to https://talon.wiki/blob/gh-pages//getting_started.md
Which then redirects to: https://talon.wiki/new/gh-pages?filename=wiki/gh-pages.md, where it gets stuck.

Body text is not black any more

The color of the text on the wiki seems to have become gray again, which makes it significantly harder to read for me. I thought I fixed this in #11.

Add TODO to Speech engine section

https://talon.wiki/unofficial_talon_docs/#speechengine In the sentence in the section where it says this section needs a page of its own, I would put TODO So that people can search/grep through the wiki for todos When they’re looking for things to add/edit. It might be a useful idea to make a wiki rule that if you think a section is unfinished, to flag it with a to do and explain why.

Add best practices for designing command sets

It would be great to have some general best practices for command set design.
There are a few ideas we removed here: #73

Make "Talon Wiki" in upper left corner of site a link to the home page

Remove download zip/tar links

The custom theme has these "Download ZIP File" and "Download TAR Ball" links which aren't really useful. The "View On Github" button is useful, but not completely necessary. We should at least remove the TAR and ZIP buttons.

Invalid link to custom.css on almost all pages

The custom.css file returns 404 on every page except the root.

Unofficial talon docs page has a zooming issues on iPhone

https://talon.wiki/unofficial_talon_docs/ On this page, when I am using my iPhone, Soon as I take my finger off the screen the page zooms in in a very annoying way. This is what I see on that page. The left hand section of text is cut off, and I am not permitted to zoom it back out so that I can see it. I don’t have this problem on any other page of the wiki so far.

Discussion thread: what do we include in the “Getting Started” page?

This is the issue for discussing what to include on the Getting Started page.

TLDR: getting started should include everything necessary to get a basic working installation of Talon on all three operating systems such that when you say 'help alphabet' the alphabet appears

A set of basic commands

Lots of links to other pages where appropriate, such as links to tutorials, links to more advanced installation guides, links to troubleshooting, etc.

Now feel free to make proposals about what 'everything necessary' means, what basic commands should be included, and other things to nail down what ought to be in Getting Started.

Fix "Many commands work badly" section in improving_recognition_accuracy.md

This section is unnecessarily negatively phrased and may demotivate users. The phrasing "Many commands work badly" is vague and may suggest a statement of fact instead of a fixable situation the user might be in.

edit wiki in light of public release of new talon

Most pages on the wiki were written before the new Talon version was publicly released, so a lot of them need rewriting. They tend to assume that readers have access to the beta channel, and refer to the legacy release for mac as the public release. We should instead call the old public version of talon "legacy", the current public version "public", and label things that only work in the beta as "beta". We should aim for most of the information on the wiki to be useful and accessible to public Talon users, and mark beta-specific information clearly.

• Rewrite getting_started.md.
• Rewrite advanced_talon.md.
• Check that the install process on getting_started.md is still accurate for public.
• Fix the wav2letter set up instructions in getting_started.md; they currently link to #beta.
• Fix up the FAQ.
• Check that there are no other spurious references to the beta where they don't belong.

Remove Legacy Talon version

We mention the Legacy Talon version in Getting Started page. Folks who are still using the Legacy probably don't need to be told that it exists, and it's not a real option for new users, so let's get rid of it.

Remove commands from knausj other than the basics

We have examples of commands from the knausj repository, but maybe it's best to leave documentation of those commands to that repository. Maybe we leave just the basics: help, command history, wake up / sleep, dictation / command mode.

TOC contents have some added newlines

these extra newlines might be a result of adding hard_wrap to the _config.yml. Explore removing these or making them consistent

search box does not work

The search box in the upper right corner of the page seems to do nothing.

video content request - knausj

This is a request for a video on the knausj installation. Would you like to help the wiki? Consider doing a quick screen recording of the download and setup of the knausj repo. You could make one video for each platform OR a single video showing mac, linux, and windows - up to you!

video content request - pop/hiss and mouse commands

Would someone like to make a quick video that shows getting started with mouse commands, and pop/hiss?
voice commands for mouse stuff are defined here in my repo
https://github.com/knausj85/knausj_talon/blob/master/misc/mouse.talon#L8

Rename "Unofficial Talon Docs" page

The "Unofficial Talon Docs" page isn't very descriptive (isn't the whole wiki "unofficial talon docs"?). We could rename the page to be more about scripting and configuration, which is what it seems to be about.

API documentation?

The API docs on the official Talon website are (by their own admission) incomplete at best, but the only other attempt at a set of organised API docs I could find was https://github.com/dwighthouse/unofficial-talonvoice-docs, which is over a year old and not up-to-date with the new public (previously "beta") release.

Would this be the right place for a set of community-maintained API docs for Talon?

Suggestion: Make home page an introduction to Talon

When I first saw the wiki, I was a little confused where to start. I found it a little bit disorienting at the homepage is about contributing to the wiki instead of about the subject of the wiki. It would be great if the home page described talon and may talked about how best to use the wiki to get started with a link to the contribution page.

Add more commands to https://talon.wiki/common_commands/

Please add more commands to this list, to help people get started. Thanks!
https://talon.wiki/common_commands/

Improve ordering of navigation sidebar

Including, but not limited to:

• what is "Unofficial talon docs" and why is it second?
• maybe move FAQ up to the second position?

Give demo videos more descriptive names

In the video section, video names sound intimidating and technically obscure. If they were put under a title such as

#Master talon users demonstrating the power of voice control

And then group videos under subsectionssections such as

##Demonstrations of how to code

And

##Demonstrations of how to play games

it would make video demo section seem much friendlier to newbies when they are trying to pick what to watch first.

Page with Details about Dragon and Talon Setup

It would be great to have more detail about using Talon and Dragon together.

Examples:
How do they work together?
How to tell whether Dragon or Talon is handling a command.
See comment: #71 (comment)

explain how to use eye tracking and pop to click on the wiki

We should have a page explaining how to use eye tracking and pop to click on the wiki, and link to this page from Getting Started.

Dead link to Markdown Syntax Guide

The Contributing page for this wiki includes a link to a "Markdown Syntax Guide" however the link appears to be outdated or otherwise broken.

Remove TOC from pages (or move it to better location)

The TOC being the first content on each page make the page feel spammy and it's probably mostly in the way. We should consider removing it or moving it to a better location (a sidebar perhaps?).

Add how to access troubleshooting log instructions

In talon.wiki.troubleshooting In the section" talon does nothing when I speak," it talks about using the log to check if you’ve got your microphone on.

I think instructions on how to access the log would be an effective addition to the troubleshooting section. I would love a set of instructions on how to access the log on each operating system. That seems like information that would help people troubleshoot their own problems.

Generate sidebar links automatically

Right now links have to be manually added to this sidebar, but it would be great if the theme automatically pulled in all .md files.

The sidebar is rendered from: https://github.com/TalonCommunity/Wiki/blob/gh-pages/_includes/sidebar.html

Remove or reduce 'Recently Changed' section sidebar

The Recently Changed section of the sidebar is mostly just duplicated links from the Menu and isn't entirely helpful. It ends up making the page feel more cluttered. We should consider removing it or, at least, reducing it in size to a smaller number of links.

Difficulty in distinguishing between text and inline code

Take this snippet from the Wiki for example:

It's not easy to distinguish between text and code.
Simply adding some css could improve it significantly.

I added this css in the above example:

background-color: #e4f2ff;
padding: 4px;
border-radius: 3px;

Make examples clear whether they are for public or beta

Examples are included but they don't always say they are for beta or public. Would be good to make sure it's clearly marked.

video content request - mousegrid

Would someone be willing to make a quick video showing how to install, config, and start using mousegrid?
https://github.com/timo/talon_scripts/tree/master/mousegrid

Some improvements to troubleshooting doc

It might be useful if the troubleshooting doc had a gif which showed where the levels should be in audacity. The gif right now is quite helpful, but it doesn't have an indication of the following:

• The volume level should go down to zero when you're not speaking
• You want the volume to be as high as possible without clipping, eg in the yellow zone

Information on configurations other than the knausj ought to be included and stashed somewhere

While deleting the advanced Talon page Emily and Tara decided that having links somewhere on the wiki to alternative configurations would be valuable to put somewhere under a more meaningful name than 'Advanced Talon'

Alternative User Configurations

If you do not have anything specific in mind, start out using knausj_talon, which has become the most shared Talon configuration. Of course there are alternatives, but only use one repository - they should not be mixed.

| Talon Release | GitHub Repository | Description |
|-|-|
| Public | knausj85's knausj_talon | The currently recommended go-to repository for general use |
| Public | Fidgetingbit's Talon Config | Fork of Knausj's config with VimSpeak support |
| Public | mrob95's Talon Config | Mark Robert's Talon config with support for Windows dev tools (Windows Terminal, Mintty, Windows Workspaces) |

Remove the Setting Up Talon in Windows 10 with Dragon tutorial

I reveiwed the tutoril I wrote last year, and about 80% of this https://talon.wiki/SettingUpTalonWindows10Dragon/ tutorial can be replaced by a link to the getting started page on talonvoice.com and an installation video. 80% of the information is redundant and the other 20% is incorrect or dated.

So I would replace that entire page with
a link to https://talonvoice.com/docs/index.html#getting-started
if they want to actually see a step-by-step installation of talon, I have this youtube video of installing Talon on Windows. We can refer them to it with a note to skip the wav2letter installation and install Dragon instead. https://youtu.be/wizshwYfuRo

This issue is pending me learning how to do a regular pull request.

Section to explain how python interacts with talon files

We could do a better job at explaining how python and talon files interact. We could also include a minimum amount of code example, like this one that was posted in talon slack:

from talon import Module
mod = Module()
@mod.action_class
class Actions:
    def action1():
        """prints hi"""
        print('hi')
    def action2(name: str, number: int):
        """prints a name and number"""
        print(name, number)

this defines new functions in talonscript that can be used in a .talon file with the syntax user.action1() or user.action2("name", 5)

hello world: user.action1()
block command:
    insert("hello world")
    key(ctrl-c)
    user.action2("name", 5)

fix download links to sconv-b5/large-b2

currently https://talon.wiki/advanced_talon/ links to messages from #beta regarding installing sconv-b5 & large-b2 that have fallen out of slack's history, so they're unusable. I believe we shouldn't link directly to the b5/large-b2 download links, since they're beta-exclusive and not public. So we should find some other solution.

Add documentation for anchors

Anchors, ^ and $, are used in talon commands to anchor commands at the begging or end, similar to regex anchors (but with some differences).

Examples:

^ means "this can only be matched at the start of a phrase"
$ means "this can only be matched at the end of a phrase"

They can be combined. If you bind ^test one two three$ and you say test one two three four, it should not recognize.

They can be part of a longer sentence, for example, $ so it doesn't try to recognize commands while you're talking.

^wake up$ uses anchors so it can't be recognized mid sentence, which means fewer false positives.

Edge anchoring can change the meaning of a word depending on how it is used. e.g. over$ vs over can be two separate commands.

https://talonvoice.slack.com/archives/C7ENXA7C4/p1621350960040900

Basic customization - Keyboard shortcuts; Needs updating

I am told that adding Keyboard shorts cuts are now available for Windows but the wiki still says it is only an option for Mac.

https://github.com/TalonCommunity/Wiki/blob/main/basic_customization.md#keyboard-shortcuts

If there is a better way to submit a new issue, please let me know.

auto line-wrap text

Some text blobs are currently all on one line, which will be hard to read on wide monitors and will make future diffs hard to read. We should explore some automatic line wrapping.

Move "Testing the basics" from Getting Started

This section may make more sense in Troubleshooting. Also, make it less Mac specific or split it into separate Mac/Windows pages.

Getting Started page should be more accessible to folks with non-programming background

• Users shouldn't need to reference installation docs on talonvoice.com. Redirecting folks there and back adds friction and can be avoided by filling out installation steps directly on the wiki.
• Add instructions for users who don't use the command line.
• Specifics about Linux are currently very prominent on the page but are not relevant for many users. This information is important, but should be reorganized so it's not so prominent.
• Every choice on the page adds friction (e.g., beta vs. free version or table of speech engines). We should update the flow to assume a default option to keep the flow simple; link to additional options.

Specify that “language” means programming language

Under https://talon.wiki/scripting_and_configuration/ When it said “activating your language” I am mediately assumed that it meant I could switch between, say, French or English. Which goes to show that I am not primarily a programmer, but it may be useful to clarify in the title that switching languages means switching programming languages.

need clarity on combining .talon context header requirements

In this section - https://talon.wiki/unofficial_talon_docs/#context-header - we have the following text:

Each kind of requirement can be listed several times. Entries of the same kind of requirement are OR‘d together, and of different kinds are AND‘d.

The 'same kind' language is ambiguous. Here's some alternate language (from aegis) which could be used instead:

talon ORs between the same key, because it needs to (you can't generally match app: slack and app: safari at the same time for example)
talon ANDs between different keys, because it needs to (app: slack, title: /talon/)

See https://talonvoice.slack.com/archives/C9MHQ4AGP/p1623385104250700 .

video content request - how to start with eyetracking

Would someone make a couple of quick videos to show how to setup and start using these various controls?
Talon has a few different modes for eye tracking, fyi
• Control Mouse: cursor follows gaze, you can use head tracking for finer movement
• Zoom Mouse: builds on control mouse, you can use a pop noise to zoom in and a second to click -- no head tracking in the zoom view https://talonvoice.slack.com/archives/G9YTMSZ2T/p1591969994075300 - see the responses from kim2 and jcaw too
If you're on beta, and using my depo, enabling control mouse will also enable the pop-to-click (no zoom step).
If you're on Windows, you might consider using it in conjunction with Optikey mouse
http://optikey.org/

Setting up dev environment in Windows requires webrick

Hey there,

I'm not really familiar with Ruby or Jekyll, I was trying to test some features localy and got the site to build, but needed to both add webrick, and change the port number on my run command to due to port 4000 either being occupied or having a permissions issue.

Issue referencing needing to add webrick

---

Port issue error and some resources below I looked at:

`bind': Permission denied - bind(2) for 127.0.0.1:4000 (Errno::EACCES)

• One
• Two
• Three

Ultimately adding a port number to the serve command got around this problem.

bundle exec jekyll serve --port 4001

Complete error code:

jekyll 3.9.2 | Error:  Permission denied - bind(2) for 127.0.0.1:4000
C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:201:in `bind': Permission denied - bind(2) for 127.0.0.1:4000 (Errno::EACCES)
    from C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:201:in `listen'
    from C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:765:in `block in tcp_server_sockets'
    from C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:227:in `each'
    from C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:227:in `foreach'
    from C:/Ruby31-x64/lib/ruby/3.1.0/socket.rb:763:in `tcp_server_sockets'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/webrick-1.7.0/lib/webrick/utils.rb:60:in `create_listeners'    
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/webrick-1.7.0/lib/webrick/server.rb:130:in `listen'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/webrick-1.7.0/lib/webrick/server.rb:111:in `initialize'        
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/webrick-1.7.0/lib/webrick/httpserver.rb:47:in `initialize'     
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:229:in `new'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:229:in `start_up_webrick'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:104:in `process'     
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:93:in `block in start'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:93:in `each'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:93:in `start'        
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/lib/jekyll/commands/serve.rb:75:in `block (2 levels) in init_with_program'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `block in execute'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `each'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `execute'      
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/mercenary-0.3.6/lib/mercenary/program.rb:42:in `go'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/mercenary-0.3.6/lib/mercenary.rb:19:in `program'
    from C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/jekyll-3.9.2/exe/jekyll:15:in `<top (required)>'
    from C:/Ruby31-x64/bin/jekyll:25:in `load'
    from C:/Ruby31-x64/bin/jekyll:25:in `<main>'

Branch at: Spiteless/windows_dev_setup

Consistent Style in 'Improving Accuracy' page

The sections in the Improving Accuracy page should also have consistency, either categories of things to check/fix or "what do I do if?" style, but not both.

Unable to make changes in place

Whenever I try to make and save changes to the wiki using the in place editor it fails and I get the below error message which doesn't help me to debug what's wrong.