@@ -4,70 +4,22 @@ sort: 4
4title: Talk manual
4title: Talk manual
7−# `:talk` manual
7+# `:talk`
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.
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.)
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.
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.
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.
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.
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.
44−Right now, the only public federal station is `urbit-meta`.
45−Because the party always starts in the kitchen.
47−## Quickstart
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.
49−Let's post something! At the default `:talk` prompt
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.
53−type the message:
13+## Quickstart
55− ~fintud-macrep:talk() hello, world.
57−And hit return. Don't worry, no one but you will see this. The
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).
58−`:` means you're posting to yourself. You'll get the post:
60− ~fintud-macrep: hello, world.
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.
61− ~fintud-macrep:talk()
63−It's boring to post to yourself. Let's join a station:
19+Let's join a station:
65 ~fintud-macrep: ;join ~doznec/urbit-meta
21 ~fintud-macrep: ;join ~doznec/urbit-meta
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`.)
71You'll see:
23You'll see:
73 ---------:talk| %porch subscribed to /urbit-meta, called `>`
25 ---------:talk| %porch subscribed to /urbit-meta, called `>`
@@ -77,11 +29,6 @@ You'll see:
77 ~doznec= ~fintud-macrep admitted to %urbit-meta
29 ~doznec= ~fintud-macrep admitted to %urbit-meta
78 ~fintud-macrep:talk>
30 ~fintud-macrep:talk>
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.
85Post a line to `/urbit-meta`:
32Post a line to `/urbit-meta`:
87 ~fintud-macrep:talk> hello, world
34 ~fintud-macrep:talk> hello, world
@@ -90,21 +37,17 @@ You'll see, echoed back at you through `~doznec`:
91 ~fintud-macrep> hello, world
38 ~fintud-macrep> hello, world
93−And of course, anyone else in `/urbit-meta` will see it as well.
40+To send a direct message to someone, first set your audience:
94−But you don't care about `/urbit-meta`, so leave it:
96− ~fintud-macrep:talk> ;leave >
42+ ~fintud-macrep:talk> ;~talsur-todres
100− ---------:talk| %porch has left /urbit-meta, called `>`
44+You'll see your prompt change:
102−Everyone else will see:
46+ ~fintud-macrep:talk[~talsur-todres]
104− ~doznec= ~fintud-macrep has left %urbit-meta
48+Then you're ready to chat away.
106−Now you're ready to use `:talk` for real! For general discussion
50+Those are the basics, and the rest is covered below.
107−about Urbit, we recommend `/urbit-meta`.
@@ -113,6 +56,8 @@ about Urbit, we recommend `/urbit-meta`.
113There are three kinds of inputs you can type at the `:talk`
56There are three kinds of inputs you can type at the `:talk`
114prompt: lines, URLs, and commands.
57prompt: lines, URLs, and commands.
116A line is 64 bytes of ASCII lowercase and spaces. If the line
61A line is 64 bytes of ASCII lowercase and spaces. If the line
117starts with '@', it's an action (IRC `/me`).
62starts with '@', it's an action (IRC `/me`).
@@ -121,23 +66,23 @@ insert a Unicode bullet-point character in an appropriate space
121in your post, to show you the prospective linebreak. Your essay
66in your post, to show you the prospective linebreak. Your essay
122will be posted in multiple lines.
67will be posted in multiple lines.
71+A URL is any valid URL.
124−A URL is any valid URL. A command is any line starting with `;`.
75+A command is any line starting with `;`.
126−### Source annotation
77+### Prefixes
128−Any post in your flow is shown with its author, together with a
79+`|` - Informational messages
129−glyph that shows how the post reached you. A post can reach you
130−in one of three ways:
132−Any post you see reached you in one of three ways. Either it was
81+`:` - Posts directly to you
133−sent directly to just you; to you and others; or to a station you
136−Informational messages are `|`. Posts directly to you are `:`. Posts to
137−you and others (a multiparty conversation) are `;`, unless you've bound
83+`;` - Posts to you and others (a multiparty conversation)
138−this conversation to a glyph. Posts to a station use that station's
84+
139−glyph. Posts to a complex audience that doesn't directly include you are
85+`*` - Posts to a complex audience that doesn't directly include you are.
142### Station Glyphs
87### Station Glyphs
@@ -153,7 +98,6 @@ will assign the `>` annotation to `/urbit-test`.
154### Audience selection
99### Audience selection
156−Audience selection is important in a multiplexed communicator!
157The audience is always shown in your prompt. If there's a glyph
101The audience is always shown in your prompt. If there's a glyph
158for it, it's shown as the glyph:
102for it, it's shown as the glyph:
@@ -163,11 +107,10 @@ Otherwise, the audience is shown in parens:
164 ~fintud-macrep:talk(~dannum-mitryl)
108 ~fintud-macrep:talk(~dannum-mitryl)
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
168is simply `;station` - eg, `;~dannum-mitryl` for a direct post;
111is simply `;station` - eg, `;~dannum-mitryl` for a direct post;
169−`/urbit-meta` or `~doznec/urbit-meta` to post to a federal
112+`;/urbit-meta` or `;~doznec/urbit-meta` to post to a federal
170−station, `%mystation` to post to a station on your own ship.
113+station, `;%mystation` to post to a station on your own ship.
171For a station bound to a glyph, `;` then the glyph; eg, `;>`.
114For a station bound to a glyph, `;` then the glyph; eg, `;>`.
173You can post a line and set the audience in one command, eg:
116You 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`,
208on the station or conversation whose glyph is `>`.
151on the station or conversation whose glyph is `>`.
210The effect of activating a post depends on the post. For a link,
153The 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
154+the full URL is shown. For a text
212−clipboard, or even automatically navigated to. Even for a text
213post, activating shows the full audience, for complex audiences.
155post, activating shows the full audience, for complex audiences.
215Posts in your `:talk` flow are numbered; the numbers are printed
157Posts in your `:talk` flow are numbered; the numbers are printed
@@ -233,56 +175,43 @@ most recent; etc.
234### Nicknames
176### Nicknames
236−<mark>Implemented, no autocompletion</mark>
238Sometimes you know your Urbit friends by other names, on or
178Sometimes you know your Urbit friends by other names, on or
239offline. Use the `;nick` command to assign or look up
179offline. Use the `;nick` command to assign or look up
240nicknames.
180nicknames.
242−`;nick` with no arguments lists all nicknames; `;nick
182+`;nick` - list all nicknames
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.
248−Of course, nicknames are strictly local - like the names on
184+`;nick ~fintud-macrep` - look up a nickname
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
254−If you would prefer to see nicknames instead of urbit names when
186+`;nick plato` - search in reverse
255−someone speaks, use `;set noob`. `;unset noob` disables this
258−### Presence
188+`;nick ~fintud-macrep plato` create a nickname
260−You'll see presence notifications when people enter or leave
190+`;nick ~fintud-macrep ~` clear an assigned nickname
261−stations you're subscribed to.
263−`;who` lists everyone in all your stations. `;who station`
192+`;set noob` show nicknames instead of urbit names
264−lists everyone in that station.
266−### Typing indicator
194+`;unset noob` show urbit names instead of nicknames
268−<mark>Not yet implemented</mark>
196+All nicknames must be 14 characters or less, lowercase. Nicknames are strictly local - like the names on
269−
197+entries in a phonebook. Sometimes in a post you want to mention
270−If one or more urbits in your audience is typing, `:talk`'s
198+someone you know by a nickname. Just type `~plato`, and `:talk`
271−presence system will detect it and change the prompt:
199+will replace it with `~fintud-macrep`.
273− ~fintud-macrep [~dannum-mitryl...]=
201+### Presence
275−### Creating and managing stations
203+You'll see presence notifications when people enter or leave
204+stations you're subscribed to.
206+`;who` - list everyone in all your stations
278−<mark>Non-channel stations, and managing white/blacklists,
208+`;who station` - list everyone in that station
279−are a planned feature that is not yet implemented</mark>
210+### Creating and managing stations
281To create your own mailbox, party, journal or board:
211To create your own mailbox, party, journal or board:
283− ;create party %myfunparty
284 ;create journal %serious-journal
213 ;create journal %serious-journal
285− ;create board %bizarre-board
214+ ;create channel %serious-journal
@@ -303,11 +232,3 @@ To appoint a coauthor of `%serious-journal`:
304 ;author %serious-journal ~lagret-marpub
233 ;author %serious-journal ~lagret-marpub
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:
312−- `noob` - Display user-defined nicknames instead of ship names