@@ -4,70 +4,22 @@ sort: 4
44title: Talk manual
55---
66
7−# `:talk` manual
8−
9−`:talk` is the Urbit appliance for chatter and notifications.
10−For less sophisticated users, Urbit *is* just `:talk`. If you
11−see `:talk` as "like Slack, but distributed," or "like IRC, but
12−persistent and encrypted," you're not completely wrong.
13−
14−`:talk` is an unusual messenger in two ways. One: by default, it
15−multiplexes all content streams into a single flow. Most UI
16−researchers agree that context-switching is cognitively expensive
17−and leads to surfing the Internet. (`:talk` is also used for
18−your system notifications.)
19−
20−Two: text lines are limited to 64 ASCII bytes, no uppercase.
21−This restriction is mobile-friendly and reduces the aesthetic
22−impact of low-quality content.
23−
24−Messages in `:talk` are called "posts". Posts go to "stations,"
25−which are just like IRC or Slack channels. Any urbit can host or
26−subscribe to any number of stations.
27−
28−`:talk` is not a text-only messenger; it's designed to support
29−arbitrary content in posts, from URLs to images to long-form
30−text. (Only URLs right now.) However, any message on `:talk`
31−has to be able to summarize itself in a 64-byte text line.
32−
33−There are four kinds of station: a write-only `%mailbox` for
34−direct messages, an invite-only `%party` for private conversation,
35−a read-only `%journal` for curated content, and a public-access
36−`%board` for general use or abuse.
37−
38−While there's obviously no central `:talk` server for all of
39−Urbit, and thus no such thing as a truly global station space,
40−active Urbit stars cooperate to federate, manage and mirror a
41−collectively-managed namespace, very like Usenet. These
42−"federal" stations are generally public-access boards.
43−
44−Right now, the only public federal station is `urbit-meta`.
45−Because the party always starts in the kitchen.
7+# `:talk`
468
47−## Quickstart
48−
49−Let's post something! At the default `:talk` prompt
9+`:talk` is the Urbit messaging and notifications protocol. Today we use `:talk` to chat and coordinate, sort of like a distributed, encrypted Slack. This is the simplest, most immediate use for `:talk`, but we hope it can become much more than just persistent IRC. `:talk` is a general purpose tool for both aggregating and publishing heterogenous streams of messages. Applications can use `:talk` as their transport protcol, API connectors can push disparate data sources into `:talk`, there are lots of things a distributed message protocol can be used for.
5010
51− ~fintud-macrep:talk()
11+`:talk`s design is similar in spirit to [nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol) the underlying protocol for Usenet. Let's briefly outline the design: `:talk` messages are called ‘posts’. Posts go to ‘stations’. Any urbit can host or subscribe to any number of stations. There’s no central `:talk` server. Any Urbit can host one. There are four kinds of station: a write-only `%mailbox` for direct messages, an invite-only `%party` for private conversation, a read-only `%journal` for curated content, and a public-access `%board` for general use.
5212
53−type the message:
54−
55− ~fintud-macrep:talk() hello, world.
13+## Quickstart
5614
57−And hit return. Don't worry, no one but you will see this. The
58−`:` means you're posting to yourself. You'll get the post:
15+There are two ways of using `:talk`: from the CLI or through a web interface available at `http://localhost:8080/talk` (or equivalent). The web interface ships as compiled JavaScript on your Urbit, but has its own source repo [here](https://github.com/urbit/talk).
5916
60− ~fintud-macrep: hello, world.
61− ~fintud-macrep:talk()
17+The web interface doesn't expose *all* the functionality of the CLI, and it's more or less self-explanatory. We'll give examples from the command line.
6218
63−It's boring to post to yourself. Let's join a station:
19+Let's join a station:
6420
6521 ~fintud-macrep: ;join ~doznec/urbit-meta
6622
67−(`/urbit-meta` is a federal station, meaning it's hosted by your
68−star (for `~fintud-macrep`, `~doznec`). The `/` notation is just
69−an abbreviation for `~doznec/urbit-meta`.)
70−
7123You'll see:
7224
7325 ---------:talk| %porch subscribed to /urbit-meta, called `>`
@@ -77,11 +29,6 @@ You'll see:
7729 ~doznec= ~fintud-macrep admitted to %urbit-meta
7830 ~fintud-macrep:talk>
7931
80−Notice the character assignment - stations you're subscribed to are
81−assigned [consistent ASCII glyphs](#-station-glyphs), which you'll
82−see in the log when you hear from these stations, and on the prompt
83−when you're talking to them.
84−
8532Post a line to `/urbit-meta`:
8633
8734 ~fintud-macrep:talk> hello, world
@@ -90,21 +37,17 @@ You'll see, echoed back at you through `~doznec`:
9037
9138 ~fintud-macrep> hello, world
9239
93−And of course, anyone else in `/urbit-meta` will see it as well.
94−But you don't care about `/urbit-meta`, so leave it:
40+To send a direct message to someone, first set your audience:
9541
96− ~fintud-macrep:talk> ;leave >
97−
98−You'll see:
42+ ~fintud-macrep:talk> ;~talsur-todres
9943
100− ---------:talk| %porch has left /urbit-meta, called `>`
44+You'll see your prompt change:
10145
102−Everyone else will see:
46+ ~fintud-macrep:talk[~talsur-todres]
10347
104− ~doznec= ~fintud-macrep has left %urbit-meta
48+Then you're ready to chat away.
10549
106−Now you're ready to use `:talk` for real! For general discussion
107−about Urbit, we recommend `/urbit-meta`.
50+Those are the basics, and the rest is covered below.
10851
10952## Manual
11053
@@ -113,6 +56,8 @@ about Urbit, we recommend `/urbit-meta`.
11356There are three kinds of inputs you can type at the `:talk`
11457prompt: lines, URLs, and commands.
11558
59+#### Lines
60+
11661A line is 64 bytes of ASCII lowercase and spaces. If the line
11762starts with '@', it's an action (IRC `/me`).
11863
@@ -121,23 +66,23 @@ insert a Unicode bullet-point character in an appropriate space
12166in your post, to show you the prospective linebreak. Your essay
12267will be posted in multiple lines.
12368
124−A URL is any valid URL. A command is any line starting with `;`.
69+#### URLs
70+
71+A URL is any valid URL.
72+
73+### Commands
74+
75+A command is any line starting with `;`.
12576
126−### Source annotation
77+### Prefixes
12778
128−Any post in your flow is shown with its author, together with a
129−glyph that shows how the post reached you. A post can reach you
130−in one of three ways:
79+`|` - Informational messages
13180
132−Any post you see reached you in one of three ways. Either it was
133−sent directly to just you; to you and others; or to a station you
134−subscribe to.
81+`:` - Posts directly to you
13582
136−Informational messages are `|`. Posts directly to you are `:`. Posts to
137−you and others (a multiparty conversation) are `;`, unless you've bound
138−this conversation to a glyph. Posts to a station use that station's
139−glyph. Posts to a complex audience that doesn't directly include you are
140−`*`.
83+`;` - Posts to you and others (a multiparty conversation)
84+
85+`*` - Posts to a complex audience that doesn't directly include you are.
14186
14287### Station Glyphs
14388
@@ -153,7 +98,6 @@ will assign the `>` annotation to `/urbit-test`.
15398
15499### Audience selection
155100
156−Audience selection is important in a multiplexed communicator!
157101The audience is always shown in your prompt. If there's a glyph
158102for it, it's shown as the glyph:
159103
@@ -163,11 +107,10 @@ Otherwise, the audience is shown in parens:
163107
164108 ~fintud-macrep:talk(~dannum-mitryl)
165109
166−`:talk` works fairly hard to get the audience right and minimize
167−manual switching. But to manually set the audience, the command
110+To manually set the audience, the command
168111is simply `;station` - eg, `;~dannum-mitryl` for a direct post;
169−`/urbit-meta` or `~doznec/urbit-meta` to post to a federal
170−station, `%mystation` to post to a station on your own ship.
112+`;/urbit-meta` or `;~doznec/urbit-meta` to post to a federal
113+station, `;%mystation` to post to a station on your own ship.
171114For a station bound to a glyph, `;` then the glyph; eg, `;>`.
172115
173116You can post a line and set the audience in one command, eg:
@@ -208,8 +151,7 @@ meaning that `~fintud-macrep` posted a link to `foobar.com`,
208151on the station or conversation whose glyph is `>`.
209152
210153The effect of activating a post depends on the post. For a link,
211−the full URL is shown and (system permitting) put into the OS's
212−clipboard, or even automatically navigated to. Even for a text
154+the full URL is shown. For a text
213155post, activating shows the full audience, for complex audiences.
214156
215157Posts in your `:talk` flow are numbered; the numbers are printed
@@ -233,56 +175,43 @@ most recent; etc.
233175
234176### Nicknames
235177
236−<mark>Implemented, no autocompletion</mark>
237−
238178Sometimes you know your Urbit friends by other names, on or
239179offline. Use the `;nick` command to assign or look up
240180nicknames.
241181
242−`;nick` with no arguments lists all nicknames; `;nick
243−~fintud-macrep` looks up a nickname; `;nick plato` searches in
244−reverse; `;nick ~fintud-macrep plato` creates a nickname, and
245−`;nick ~fintud-macrep ~` clears an assigned nickname. All
246−nicknames must be 14 characters or less, lowercase.
182+`;nick` - list all nicknames
247183
248−Of course, nicknames are strictly local - like the names on
249−entries in a phonebook. Sometimes in a post you want to mention
250−someone you know by a nickname. Just type `~plato`, and `:talk`
251−will replace it magically with `~fintud-macrep` (or beep if no
252−`~plato` is bound).
184+`;nick ~fintud-macrep` - look up a nickname
253185
254−If you would prefer to see nicknames instead of urbit names when
255−someone speaks, use `;set noob`. `;unset noob` disables this
256−setting.
186+`;nick plato` - search in reverse
257187
258−### Presence
188+`;nick ~fintud-macrep plato` create a nickname
259189
260−You'll see presence notifications when people enter or leave
261−stations you're subscribed to.
190+`;nick ~fintud-macrep ~` clear an assigned nickname
262191
263−`;who` lists everyone in all your stations. `;who station`
264−lists everyone in that station.
192+`;set noob` show nicknames instead of urbit names
265193
266−### Typing indicator
194+`;unset noob` show urbit names instead of nicknames
267195
268−<mark>Not yet implemented</mark>
269−
270−If one or more urbits in your audience is typing, `:talk`'s
271−presence system will detect it and change the prompt:
196+All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on
197+entries in a phonebook. Sometimes in a post you want to mention
198+someone you know by a nickname. Just type `~plato`, and `:talk`
199+will replace it with `~fintud-macrep`.
272200
273− ~fintud-macrep [~dannum-mitryl...]=
201+### Presence
274202
275−### Creating and managing stations
203+You'll see presence notifications when people enter or leave
204+stations you're subscribed to.
276205
206+`;who` - list everyone in all your stations
277207
278−<mark>Non-channel stations, and managing white/blacklists,
279−are a planned feature that is not yet implemented</mark>
208+`;who station` - list everyone in that station
280209
210+### Creating and managing stations
281211To create your own mailbox, party, journal or board:
282212
283− ;create party %myfunparty
284213 ;create journal %serious-journal
285− ;create board %bizarre-board
214+ ;create channel %serious-journal
286215
287216etc.
288217
@@ -303,11 +232,3 @@ To appoint a coauthor of `%serious-journal`:
303232
304233 ;author %serious-journal ~lagret-marpub
305234
306−### Settings
307−
308−To set a frontend option in your `talk` session, use `;set
309−[option]`, or `;unset [option]` to unset it. To see all currently
310−set options, just type `;set`. The options available are:
311−
312−- `noob` - Display user-defined nicknames instead of ship names
313− if available.