code format isn't obvious: add some docs

[warner]

It'd be nice if the wormhole receive side could remind users that tab-completion is available. This might also help avoid the confusion that happens when the sender says (speaks) "the wormhole code is three purple kumquat", and the receiver doesn't guess that there are supposed to be hyphens in between words instead of spaces.

I didn't want to make wormhole receive show too-specific of an example (e.g. Type in the wormhole code here. Wormhole codes look like "4-purple-kumquat".), for fear that folks would literally type in the example text. But maybe something like Wormhole codes look like "NN-WORD-WORD" might be sufficiently non-specific to avoid confusion.

[warner]

For tab-completion, here's one idea: just after entering a code (on the wormhole receive side), if the user did not use tab-completion, print a reminder that it's available:

% wormhole rx
Enter receive wormhole code: 6-hazardous-beeswax
(note: you can use <Tab> to complete words)
hello world
%

If they did use tab, the reminder is not displayed, so we're not cluttering up the output for experienced users.

That example shows one potential downside: when used for text messages (e.g. wormhole send --text "hello world"), it might not be obvious which part of the output is the text message, and which part is the tab reminder.

We could also put it into the prompt, but then it will be there every time, even when the user has demonstrated knowledge of the feature:

% wormhole receive
Enter receive wormhole code (use <Tab> for completion): 5-liberty-crackdown
hello world

@dkg suggested changing the prompt in response to what happens while the user is typing. I don't see how to use this ahead of time (e.g. show the reminder in the prompt at the start, but then remove it from the prompt after they've typed a tab). But maybe we could wait until the user hits Return, and then change the prompt at the very last minute. That would move the reminder up to the code-input line, but wouldn't display anything until we know the reminder might be necessary. I don't know how to make libreadline do that, though: the API I've seen makes the prompt seem pretty immutable.

[dkg]

On Fri 2017-01-06 11:55:48 -0500, Brian Warner wrote:

@dkg suggested changing the prompt in response to what happens while the user is typing. I don't see how to use this ahead of time (e.g. show the reminder in the prompt at the start, but then remove it from the prompt after they've typed a tab).

can "wormhole" keep local state about whether the user used "tab" in any of the last 10 times they've used "wormhole rx"? you could choose a different prompt based on whether they're regular tab users.

But maybe we could wait until the user hits Return, and then change the prompt at the very last minute. That would move the reminder up to the code-input line, but wouldn't display anything until we know the reminder might be necessary. I don't know how to make libreadline do that, though: the API I've seen makes the prompt seem pretty immutable.

i don't know how to adjust the prompt in libreadline either :/ it might not be something easy to do, though maybe it's worth asking libreadline upstream about it.

fwiw, i'd advocate updating the prompt well before hitting return -- if it's possible to update the prompt as soon as libreadline knows it has something "useful" to tab-complete, that would be ideal :)

     --dkg

[warner]

can "wormhole" keep local state about whether the user used "tab" in any of the last 10 times they've used "wormhole rx"? you could choose a different prompt based on whether they're regular tab users.

Not yet.. we don't yet create ~/.wormhole/, which is where that stuff wants to live. In the future, when we add a state directory for other reasons, that'd be a great place to remember it.

fwiw, i'd advocate updating the prompt well before hitting return -- if it's possible to update the prompt as soon as libreadline knows it has something "useful" to tab-complete, that would be ideal :)

Well, that's the question :). It's useful (and common) to hit Tab before you type anything else, because if there's only one channel allocated at that moment, it will complete on that, so you won't have to type any digits at all (it will fill in the hyphen too). If you like, you can hit Tab before typing any letters either, and you'll get the full wordlist to choose from, which is a bit on the large side (256 words) but you can almost just visually search for the right one, which could help e.g. if you didn't read english at all (straight pattern-matching).

So on any given execution of the program, it's useful to remind the user about tabs from the very beginning. But if they already know about tabs, then any reminder is just cluttering up the screen.

The hybrid approach is to mention tabs after the fact, which doesn't help anyone the first time through, but does provide a discovery path so that next time they might find things easier. And by that point we know whether they used tabs this time or not, so we can avoid saying anything if they're already aware of the feature.

But then the question is where to place this notification. It can't be before the prompt because they might already know about tabs and (without saved state) we can't know that yet. We can either put it inside the prompt (which would be less cluttersome, but we don't know how to make libreadline do that), or on the line after the prompt (which is slightly cluttersome).

I guess I'm leaning towards the post-prompt line, although maybe adding a few spaces would help distinguish it from any --text= message that follows.

[warner]

The reminder for tab-completion landed, so now this ticket is just about docs on the code format. I think we can kick that out to the next release.

[antipatico]

I'm having troubles with the documentation. I'm trying to build an UI for wormhole, thus I'm trying to understand the project structure so I can choose the best way to code it.

The structure of the project isn't easy to grasp at first. To me personally it's the usage of a lot of huge frameworks (Twitsted and click to cite a couple) and functions decorators.

I'm trying to use the API but I can't wrap my head around how I should use the wormhole object with Twisted (I had never heard of Twisted in my life before).

I think it sensible to add some more documentation about code's internals, a list of use-cases for the API and a couple of working examples. It could be helpful for some people to ship the FSM pngs built.