@@ -11,23 +11,27 @@ title: Messaging (:talk)
1111
1212<div class="col-md-8">
1313
14−`:talk` is the Urbit messaging and notifications protocol. Today we use
15−`:talk` just to chat and coordinate, but it's really a general purpose
16−piece of infrastructure.
14+`:talk` is the built-in frontend for the Urbit messaging and notifications
15+protocol, `:hall`. Today we use `:hall` just to chat and coordinate, but
16+it's really a general purpose piece of infrastructure.
1717
1818For the time being come join us in `/urbit-meta` by using the
1919<a href="#-quickstart">quickstart</a> below.
2020
21−Today `:talk` is sort of like a distributed, encrypted Slack that can be
22−used from the CLI and the browser. There’s no central `:talk` server.
21+Today `:hall` is sort of like a distributed, encrypted Slack that can be
22+used from the CLI and the browser. There’s no central `:hall` server.
2323Any Urbit can host one.
2424
25−`:talk` is a general purpose tool for both aggregating and publishing
26−streams of messages. Applications can use `:talk` as their transport
27−protcol, API connectors can push disparate data sources into `:talk`,
25+`:hall` is a general purpose tool for both aggregating and publishing
26+streams of messages. Applications can use `:hall` as their transport
27+protocol, API connectors can push disparate data sources into `:hall`,
2828and so on. There are lots of things a distributed message protocol can
2929be used for that we haven't even thought of.
3030
31+Here we'll be discussing how to operate the default CLI frontend, `:talk`,
32+to send and receive messages. For a more in-depth look at `:hall`'s
33+internals, take a look at its [documentation](#TODO).
34+
3135</div>
3236
3337</div>
@@ -35,36 +39,29 @@ be used for that we haven't even thought of.
3539## Quickstart
3640
3741For the most part we use `:talk` as a single-instance of Slack: one main
38−channel (`/urbit-meta`) and dms. Everyone is more than welcome in
39−`/urbit-meta`. It's the place to get help, ask questions and chat about
42+channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
43+in `/urbit-meta`. It's the place to get help, ask questions and chat about
4044Urbit in general.
4145
4246Let's join `/urbit-meta`:
4347
4448Use `ctrl-x` to switch from `:dojo` to `:talk`.
4549
46−If you're a planet:
47−
48− ~your-urbit:talk> ;join /urbit-meta
49−
50−If you're a comet:
50+To join `/urbit-meta`:
5151
52− ~your-really-long-urbit:talk> ;join ~binzod/urbit-meta
52+ ~your-urbit:talk[] ;join /urbit-meta
5353
5454You'll see:
5555
56− ---------:talk| %porch subscribed to /urbit-meta, called `>`
57− ---------:talk| rules of /urbit-meta:
58− ---------:talk| don't be rude
59− ---------:talk| urbit-meta is politically correct and safe for work
60− ~binzod= ~your-urbit admitted to %urbit-meta
56+ --------------| ;join /urbit-meta
57+ --------------| new glyph '>'
6158 ~your-urbit:talk>
6259
6360Post a line to `/urbit-meta`:
6461
6562 ~your-urbit:talk> hello, world
6663
67−You'll see, echoed back at you through `~binzod`:
64+You'll see, echoed back at you:
6865
6966 ~your-urbit> hello, world
7067
@@ -80,11 +77,11 @@ Now you and `~talsur-todres` can exchange messages directly.
8077
8178To set your audience back to `/urbit-meta`:
8279
83− ~your-urbit:talk> ;~binzod/urbit-meta
80+ ~your-urbit:talk> ;/urbit-meta
8481
8582Use `;leave` to unsubscribe from a channel:
8683
87− ~your-urbit:talk> ;leave ~binzod/urbit-meta
84+ ~your-urbit:talk> ;leave /urbit-meta
8885
8986There are two ways of using `:talk`: from the CLI or through a web ui
9087available at `http://your-urbit.urbit.org/talk` (or
@@ -101,51 +98,67 @@ Now you can tell your friends to `;join ~your-urbit/my-channel`.
10198
10299## Manual
103100
104−`:talk`'s design is similar in spirit to
101+`:hall`'s design is similar in spirit to
105102[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
106103the underlying protocol for Usenet.
107104
108−Our design is pretty simple: `:talk` messages are called ‘posts’. Posts
109−go to ‘stations’. Any urbit can host or subscribe to any number of
110−stations.
105+Our design is pretty simple: `:hall` messages go to ‘circles’. Any urbit
106+can host or subscribe to any number of circles.
111107
112−There are four kinds of stations: a write-only `%mailbox` for direct
113−messages, an invite-only `%party` for private conversation, a read-only
108+There are four kinds of circles: a write-only `%mailbox` for direct
109+messages, an invite-only `%village` for private conversation, a read-only
114110`%journal` for curated content, and a public-access `%channel` for
115111general use.
116112
117113### Posts
118114
119−For the time being a post is either a line, a URL or a command.
115+A post can be a variety of different data structures. Let's look at the
116+ones you can use from within `:talk`: lines, URLs, expressions and
117+replies.
120118
121119#### Lines
122120
123−A line is 64 bytes of ASCII lowercase, spaces and punctuation. If the
124−line starts with '@', it's an action (IRC `/me`).
121+A line is simply a string of text. Depending on the filtering rules set
122+by the circle's host, these may or may not include uppercase and Unicode
123+characters.
124+If the line starts with `@`, it's an action (IRC `/me`).
125125
126−The `:talk` interface will let you keep typing past 64 bytes, but insert
127−a Unicode bullet-point character in an appropriate space in your post,
128−to show you the prospective linebreak. Your essay will be posted in
129−multiple lines.
130−
131− ~your-urbit:talk> this is a long message, so it will by truncated right at this•spot
126+ ~your-urbit:talk> @sends a message
132127
133128will print as
134129
135− ~your-urbit; this is a long message, so it will by truncated right at this
136− ~your-urbit; spot
130+ ~your-urbit sends a message
137131
138132#### URLs
139133
140134A URL is any valid URL.
141135
142− ~your-urbit:talk> http://example.com
136+ ~your-urbit:talk> http://example.com/
137+
138+### Expressions
139+
140+Expressions can be used to show and evaluate Hoon code. Send an expression
141+by prefacing your message with `#`.
142+
143+ ~your-urbit:talk> #(add 1 2)
144+
145+will print as
146+
147+ ~your-urbit# (add 1 2)
148+ 3
143149
144−### Commands
150+### Replies
145151
146−A command is a hoon expression, prefaced by '\#'.
152+To indicate what you're saying is in direct response to a specific
153+message, select the message (see Activating Lines below) and type your
154+response.
147155
148− ~your-urbit:talk> #(add 2 2)
156+ ~some-urbit> hello! how are you?
157+ ~your-urbit:talk> ; good, thanks!
158+
159+will print as
160+
161+ ~your-urbit>^ good, thanks!
149162
150163### Activating Lines
151164
@@ -153,17 +166,18 @@ A line number identifying the *subsequent* line is displayed every 5
153166lines.
154167
155168 ---------[0]
156− ~your-urbit; this is my message
157− ~your-urbit@ this is an @ message
158− ~your-urbit; this is a long message, so it will by truncated right at this
159− ~your-urbit; spot
169+ ~your-urbit> this is my message
170+ ~your-urbit> this is another message
171+ ~your-urbit sends a message
160172 ~your-urbit/ http://example.com/
173+ ~your-urbit# (add 1 2)
174+ 3
161175 ---------[5]
162− ~your-urbit# (add 2 2) 4
176+ ~your-urbit>^ that's my message!
163177
164178You can use a line number to *activate* a line:
165179
166− ~your-urbit:talk> ;0
180+ ~your-urbit:talk> ;5
167181
168182which prints the number, line identifier, timestamp, sender, audience,
169183and contents:
@@ -171,64 +185,132 @@ and contents:
171185 ? 0
172186 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
173187 ~your-urbit to ~another-urbit
174− this is my message
188+ in reply to: ~your-urbit:
189+ > this is my message
190+ that's my message!
175191
176−Activating a URL will print the full URL (it could have been truncated),
177−and activating a command will evaluate it.
192+If information got truncated — like happens for long URLs or expressions —
193+or if there's additional information available — as is the case with
194+replies and attachments — activating the message will show you all the
195+details.
178196
179197You can activate the most recent line with `;`, the second-most recent
180198with `;;`, and so on.
181199
182−### Creating and managing stations
200+### Creating and managing circles
201+
202+`;create [type] %name 'description'`
203+Creates and joins a circle, where `[type]` is any of the following:
204+- `channel`: public circle. Has a blacklist for write control.
205+- `village`: invite-only circle.
206+- `journal`: publicly readable, invite-only for writing.
207+- `mailbox`: publicly writeable, can only be read by its host.
208+
209+`;delete %name 'optional reason'`
210+Deletes a circle. If a reason is specified, that gets sent to all
211+subscribers before the circle gets deleted.
212+
213+`;depict %name 'description'`
214+Changes the description of circle `%name`.
215+
216+`;filter %name [capitals] [unicode]`
217+Configures the message filter for circle `%name`: whether to allow
218+capital and/or unicode characters. `y`/`&`/`true` for allowed,
219+`n`/`|`/`false` for disallowed.
220+
221+`;invite %name ~someone`
222+Invite someone into your circle `%name`. If they were previously banished,
223+removes them from the blacklist.
224+Can also invite multiple ships at once, `~comma, ~separated`.
225+
226+`;banish %name ~someone`
227+Banish someone from your circle `%name`. If they were previously invited,
228+removes them from the whitelist.
229+Can also banish multiple ships at once, `~comma, ~separated`.
183230
184−`;create journal %serious-journal 'description'` - Creates a `%journal`,
185−a privately writable publicly readable station.
231+`;source %name ~other/circle`
232+Adds `~other/circle` as a source for circle `%name`. This causes all
233+messages sent to `~other/circle` to also appear in `%name`.
186234
187−`;create channel %serious-channel 'description'` - Creates a `%channel`,
188−a publicly readable publicly writeable station.
235+`;unsource %name ~other/circle`
236+Removes `~other/circle` as a source for circle `%name`.
237+
238+### Membership
239+
240+If you have joined a circle, you can make this information publicly
241+publicly available to help others find that circle as well.
242+
243+`;show ~some/circle`
244+Adds a circle to your public membership list.
245+
246+`;hide ~some/circle`
247+Removes a circle from your public membership list.
189248
190249### Presence
191250
192251You'll see presence notifications when people enter or leave stations
193252you're subscribed to.
194253
195−`;set quiet` - Turn off presence notifications
254+`;set quiet`
255+Turn off presence notifications
256+
257+`;unset quiet`
258+Turn on presence notifications
196259
197−`;unset quiet` - Turn on presence notifications
260+`;who`
261+List everyone in all your subscribed circles. Optionally specify a
262+specific circle to list members of just those.
263+
264+`;attend ~some/circle [presence]`
265+Manually set your presence to show up as one of the following. (In the
266+future, a sufficiently advanced client can automatically set these for
267+you.)
268+- `talk` - typing
269+- `hear` - listening
270+- `idle` - inactive
271+- `gone` - not present
272+
273+`;name ~some/circle 'my nickname'`
274+Set a nickname for yourself in a specific circle. It will display to users
275+who have done `;set nick`.
276+
277+### Audience
198278
199−`;who` - list everyone in all your stations
279+An audience consists of one or more messaging targets. These can be
280+circles or ships. (In the latter case, it's secretly the `~ship/inbox`
281+circle.)
200282
201−### Station Glyphs
283+### Circle glyphs
202284
203−Glyphs are assigned by station hash out of the following list
285+Glyphs are assigned by circle hash out of the following list
204286
205287 > = + - } ) , . " ' ^ $ % & @
206288
207289Alphanumeric characters and `|#;:*~_` are reserved; all others (the
208−above lists, and `\/!?({<`) can be manually assigned.
290+above list, and `\/!?({<`) can be manually assigned.
209291
210−`;bind > /urbit-test` - assigns the `>` glyph to `/urbit-test`.
292+`;bind + /urbit-test`
293+Assigns the `+` glyph to `/urbit-test`.
211294
212−To see what station is bound to a glyph:
295+`;unbind + /urbit-test`
296+Unassigns the `+` glyph from `/urbit-test`.
297+
298+To see what circle is bound to a glyph:
213299
214300 ;what +
215− {[%.y p=[p=~binzod q=~.urbit-meta]]}
301+ /urbit-test
216302
217303### Prefixes
218304
219305Received posts are prefixed with a glyph to let you know what the
220306audience is. You can activate an individual post to see the full
221−audience.
222−
223−`|` - Informational messages
224−
225−`:` - Posts directly to you
307+audience.
308+There are a few special-purpose glyphs.
226309
227−`;` - Posts to you and others (a multiparty conversation)
228−
229−`*` - Posts to a complex audience that doesn't directly include you.
230−
231−### Audience
310+- `|` - Informational messages
311+- `:` - Posts directly to you
312+- `;` - Posts to you and others (a multiparty conversation)
313+- `*` - Posts to a complex audience that doesn't directly include you.
232314
233315#### Prompt
234316
@@ -241,20 +323,24 @@ Here we're talking to the station bound to `=`:
241323
242324Here we're talking directly to `~dannum-mitryl`:
243325
244− ~your-urbit:talk(~dannum-mitryl)
326+ ~your-urbit:talk[~dannum-mitryl]
245327
246328#### Configuration
247329
248−`;~urbit/station` - Set audience to `~urbit/station`
330+`;~urbit/station`
331+Set audience to `~urbit/station`.
249332
250−`;=` - Set audience to the station bound to the `=` glyph
333+`;=`
334+Set audience to the station bound to the `=` glyph.
251335
252−`;~dannum-mitryl` - Set audience to `~dannum-mitryl` (a direct post).
336+`;~dannum-mitryl`
337+Set audience to `~dannum-mitryl` (a direct post).
253338
254−`;%station` - Set audience to a station on your own ship
339+`;%station`
340+Set audience to a station on your own ship.
255341
256−`;~dannum-mitryl this is a private message` - Set the audience and send
257−a post in the same line. This works for all of the above.
342+`;~dannum-mitryl this is a private message`
343+Set the audience and send a post to it. This works for all of the above.
258344
259345Your audience is configured 'implicitly' with regard to the following
260346rules (in order):
@@ -269,29 +355,48 @@ Clear any 'implicit' audience setting by moving your cursor to the start
269355of the line and pressing backspace (whether the line is empty or not).
270356Posting a line clears the typing and activation configurations.
271357
272−### Nicknames
358+### Local nicknames
359+
360+`;nick`
361+List all local nicknames.
362+
363+`;nick ~your-urbit`
364+Look up a nickname.
365+
366+`;nick plato`
367+Search in reverse.
273368
274−`;nick` - list all nicknames
369+`;nick ~your-urbit plato`
370+Create a nickname.
275371
276−`;nick ~your-urbit` - look up a nickname
372+`;nick ~your-urbit ~`
373+Clear an assigned nickname.
277374
278−`;nick plato` - search in reverse
375+`;set nicks`
376+Show nicknames instead of urbit names. If no local nickname is set, uses
377+that user's self-set name.
279378
280−`;nick ~your-urbit plato` create a nickname
379+`;unset nicks`
380+Show urbit names instead of nicknames.
281381
282−`;nick ~your-urbit ~` clear an assigned nickname
382+Nicknames longer than 14 character will be truncated in output. Nicknames
383+are strictly local - like the names on entries in a phonebook.
283384
284−`;set noob` show nicknames instead of urbit names
385+### Miscellaneous configuration
285386
286−`;unset noob` show urbit names instead of nicknames
387+`;set showtime`
388+Show the timestamp for each message.
287389
288−All nicknames must be 14 characters or less, lowercase. Nicknames are
289−strictly local - like the names on entries in a phonebook. Sometimes in
290−a post you want to mention someone you know by a nickname. Just type
291−`~plato`, and `:talk` will replace it with `~your-urbit`.
390+`;unset showtime`
391+Stop showing the timestamp for each message.
292392
293−### Timestamps
393+`;set notify`
394+Emit a terminal bell sound if your six-syllable ship name is mentioned in
395+a message.
294396
295−`;set showtime` - Show the timestamp for each message
397+`;unset notify`
398+Do not notify when your ship name is mentioned.
296399
297−`;unset showtime` - Stop showing the timestamp for each message
400+`;set width [number]`
401+Set the rendering width of `:talk` to a specific number of characters.
402+(Minimum of 30.)