@@ -1,680 +0,0 @@
7−Talk is the built-in frontend for the Urbit messaging and notifications
8−protocol, Hall. Today we use Hall to chat and coordinate, but it's really
9−a general purpose piece of infrastructure.
11−For the time being come join us in `~dopzod/urbit-help` by using the
12−'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
15−Today, Hall is sort of like a distributed, encrypted Slack that can be
16−used from the CLI and the browser. There’s no central Hall server.
17−Any urbit can host one.
19−Hall is a general purpose tool for both aggregating and publishing
20−streams of messages. Applications can use Hall as their transport
21−protocol, API connectors can push disparate data sources into Hall,
22−and so on. There are lots of things a distributed message protocol can
23−be used for that we haven't even thought of.
25−Here we'll be discussing how to operate the default CLI frontend, Talk,
26−to send and receive messages. For a more in-depth look at Hall's internals,
27−take a look at its [documentation](@/docs/learn/arvo/hall.md).
31−The most common uses of Talk right now are communicating over a public chat channel called `~dopzod/urbit-help` and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.
33−There are two ways of using Talk: from the terminal running the Urbit process, or through the Landscape web UI available at `http://localhost/~~/landscape`.
35−If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.
39−In Hall, a medium for a message is called a _circle_. There are four types of circles, but we for now we'll be dealing with the _channel_: a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#manual) section.
41−Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
46−~your-urbit:talk> ;join ~dopzod/urbit-help
49−Scrolling down your terminal window, you'll probably see the playback of
50−previous `~dopzod/urbit-help` messages that you missed.
52−Post a line to `~dopzod/urbit-help:`
55−~your-urbit:talk= Hello, world!
58−You'll see your message printed below messages from others that came before it:
61−~your-urbit= Hello, world!
64−### Subscribing to a Channel in Landscape
66−In Landscape, you can always navigate to a channel by opening the menu, or using the shortcut `cmd-k`, then typing `go ~host-urbit/channel-name`. However, if you want to see messages in your inbox, you'll need to join from the Talk terminal.
71−;join ~dopzod/urbit-help
74−Now, navigate to `localhost/~~/landscape`. You should see recent messages under the "Recent" tab, and if you navigate to the "All" tab, you should see your subscription to `~dopzod/urbit-help` under "Chats".
78−To send a direct message to someone, first set your audience:
81−~your-urbit:talk= ;~talsur-todres
84−You'll see your prompt change:
87−~your-urbit:talk[~talsur-todres]
90−Now you and `~talsur-todres` can exchange messages directly.
93−~your-urbit:talk[~talsur-todres] Hey buddy!
96−To set your audience back to `~dopzod/urbit-help`:
99−~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help
102−You'll see your prompt change back:
108−You can also use the ASCII "glyph" assigned to your `~dopzod/urbit-help` circle as a shortcut:
111−~your-urbit:talk[~talsur-todres] ;=
115−(Your ship may have a different glyph than `=` for your circle)
117−Use `;leave` to unsubscribe from a channel:
120−~your-urbit:talk= ;leave ~dopzod/urbit-help
123−The web UI ships as compiled JavaScript on your urbit, but has its own
124−source repo [here](https://github.com/urbit/talk).
126−Last, let's create a channel we can invite some friends to:
129−~your-urbit:talk= ;create channel %my-channel 'Some description.'
132−Now you can tell your friends to `;join ~your-urbit/my-channel`.
138−Hall's design is similar in spirit to
139−[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
140−the underlying protocol for Usenet.
142−Our design is pretty simple: Hall messages are called _posts_. Posts
143−go to _circles_. Any urbit can host or subscribe to any number of circles.
145−There are four kinds of circles: a write-only `%mailbox` for direct
146−messages, an invite-only `%village` for private conversation, a read-only
147−`%journal` for curated content, and a public-access `%channel` for
152−A post can be a variety of different data structures. Let's look at the
153−ones you can use from within Talk: lines, URLs, Hoon and replies.
157−A line is simply a string of text. Depending on the filtering rules set
158−by the circle's host, these may or may not include uppercase and Unicode
159−characters (see [filter](#filter)).
161−If the line starts with `@`, it's an action (like `/me` in IRC).
164−~your-urbit:talk= @sends a message.
170−~your-urbit sends a message.
175−A URL is any valid URL.
178−~your-urbit:talk= https://example.com/
183−You can use Talk to evaluate Hoon code and share the result with everyone in a
184−Hall circle. To do so, preface your Hoon with `#`.
187−~your-urbit:talk= #(add 2 2)
193−~your-urbit# (add 2 2)
199−To indicate what you're saying is in direct response to a specific message, select the message (see Activating Lines below) and type your response.
202−~some-urbit= Hello! How are you?
203−~your-urbit:talk= ; Well, thanks!
209−~your-urbit=^ Well, thanks!
214−A line number identifying the **subsequent** line is displayed every 5
219−~your-urbit= This is my message.
220−~your-urbit= This is another message.
221−~your-urbit sends a message.
222−~your-urbit/ http://example.com/
223−~your-urbit# (add 2 2)
226−~your-urbit=^ That's my message!
229−You can use a line number to **activate** a line:
235−which prints the number, line identifier, timestamp, sender, audience,
240−0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
241−~your-urbit to ~another-urbit
242−in reply to: ~your-urbit:
243−> This is my message.
247−If information got truncated — like what happens for long URLs or expressions,
248−or if there's additional information available — as is the case with
249−replies and attachments (e.g. stack traces) — activating the message will show
252−You can also activate the most recent line with `;`, the second-most recent
253−with `;;`, and so on.
255−### Creating and managing circles
257−As mentioned before, any urbit can host any number of circles. Existing circles
258−can be deleted or modified with various commands. All commands in this section
259−shoild be sent from the `talk>` prompt.
263−Syntax: `;create [type] %name 'description'`
265−Creates and joins a circle, where `[type]` is any of the following:
266−- `channel`: public circle. Has a blacklist for write control.
267−- `village`: invite-only circle.
268−- `journal`: publicly readable, invite-only for writing.
269−- `mailbox`: publicly writeable, can only be read by its host.
271−Let's create an example mailbox:
274−sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
277−Something like this should print:
280−--------------| ;create mailbox %coolbox 'cool messages only'
281−--------------| :: onn %coolbox
282−--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
283−--------------| %coolbox: see ~sampel-palnet hear
284−--------------| new > %coolbox
285−--------------| %coolbox: cap: cool messages only
286−--------------| %coolbox: fit: caps:Y unic:â
291−Syntax: `;delete %name 'optional reason'`
293−Deletes a circle. If a reason is specified, that gets sent to all
294−subscribers before the circle gets deleted.
296−To delete our example above:
299−sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
302−#### Change Description
304−Syntax: `;depict %name 'description'`
306−Changes the description of an existing circle `%name`.
311−sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
317−Syntax: `;filter %name [capitals] [unicode]`
319−Configures the message filter for circle `%name`: whether to allow
320−capital and/or unicode characters. `y`/`&`/`true` for allowed,
321−`n`/`|`/`false` for disallowed.
323−So, to allow capital letters and disallow unicode in the circle `%coolbox`:
326−sampel-palnet:talk> ;filter %coolbox & |
330−sampel-palnet:talk> ;filter %coolbox y n
333−And we get the output:
336−--------------| ;filter %coolbox & |
337−--------------| %coolbox: fit: caps:Y unic:n
342−Syntax: `;invite %name ~someone`
344−Invites someone into your circle `%name`. If they were previously banished,
345−removes them from the blacklist.
346−Can also invite multiple ships at once, `~comma, ~separated`.
351−~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
356−Syntax: `;banish %name ~someone`
358−Removes someone from your circle `%name`. If they were previously invited,
359−removes them from the whitelist.
360−Can also banish multiple ships at once, `~comma, ~separated`.
364−Syntax: `;source %name ~other/circle`
366−Adds `~other/circle` as a source for circle `%name`. This causes all
367−messages sent to `~other/circle` to also appear in `%name`.
372−~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
377−Syntax: `;unsource %name ~other/circle`
379−Removes `~other/circle` as a source for circle `%name`.
384−~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
387−### Circle Membership
389−If you have joined a circle, you can make this information publicly
390−available to help others find that circle as well.
394−Syntax: `;show ~some/circle`
396−Adds a circle to your public membership list on your Hall profile. Hall profiles
401−Syntax: `;hide ~some/circle`
403−Removes a circle from your public membership list on your Hall profile. Hall
404−profiles are not used yet.
408−You'll see status notifications when people enter or leave circles you're
411−#### Notifications Off
415−Turn off status (and config) notifications.
417−#### Notifications On
419−Syntax: `;unset quiet`
421−Turn on status (and config) notifications.
427−List everyone in all your subscribed circles. Optionally specify a
428−specific circle to list members of just those: `;who ~some/circle`
433−~sampel-palnet:talk> ;who ~marzod/urbit-help
438−Syntax: `;attend ~some/circle [presence]`
440−Manually set your presence to show up as one of the following. (In the
441−future, a sufficiently advanced client can automatically set these for
447−- `gone` - not present
452−~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
455−#### Set Display Name
457−Syntax: `;name ~some/circle 'my handle'`
459−Set a handle ("name") for yourself in a specific circle. It will display
460−to users who have done `;set nicks`, but gets truncated if it's longer
465−An audience consists of one or more messaging targets. These can be
466−circles or ships. (In the latter case, it's secretly the `~ship/inbox`
471−Glyphs are found at the end of your prompt to as a quick indicator of where
472−your messages will be sent.
474−Glyphs are assigned by circle hash out of the following list:
477−> = + - } ) , . " ' ^ $ % & @
480−Alphanumeric characters and `|#;:*~_` are reserved; all others (the
481−above list, and `\/!?({<`) can be manually assigned.
483−For example, `-` the glyph at the end of the prompt below might indicates that
484−messages sent from this prompt will go to some circle with that glyph:
490−To see what circle is bound to a glyph, use the `;what` command followed by the
491−glyph in question, or use `;what` without specifying a glyph to see all of your
492−subscriptions which are bound to glyphs. For example, to see `=`:
495−~sampel-palnet:talk> ;what =
499−To see all of your glyph-bound subscriptions:
502−~sampel-palnet:talk> ;what
503−> ~paldev/numismatic-forum
504−. ~middev/ny-martians
508−Not every audience has a glyph, however. When the audience doesn't have a glyph,
509−such as in the case of direct-messaging a ship, we see their name at the end of
510−the prompt instead. Here we're talking directly to `~dannum-mitryl`:
513−~sampel-palnet:talk[~dannum-mitryl]
518−Syntax: `;bind [glyph] /circle-name`
520−Assigns the chosen glyph to a circle owned by your ship.
525−~sampel-palnet:talk> ;bind + /my-circle
530−Syntax: `;unbind [glyph] /circle-name`
532−Unassigns the chosen glyph from a circle owned by your ship.
537−~sampel-palnet:talk> ;unbind + /my-circle
542−Received posts are prefixed with a glyph to let you know what the
543−audience is. You can activate an individual post to see the full
546−There are a few special-purpose glyphs:
548−- `|` - Informational messages
549−- `:` - Posts directly to you
550−- `;` - Posts to you and others (a multiparty conversation)
551−- `*` - Posts to a complex audience that doesn't directly include you.
560−Set audience to `~ship/circle`.
562−#### Set Audience by Glyph
566−Set audience to the circle previously bound to the chosen glyph.
568−#### Set Audience to Ship
572−Set audience to another ship.
574−#### Set Audience to Own Circle
578−Set audience to a circle on your own ship
580−#### Set Audience + Send Message
582−Syntax: `;~dannum-mitryl this is a private message`
584−Set the audience and send a post in the same line. This works for all of the
585−above audience commands.
587−Your audience is configured with regard to the following rules (in order):
589−- if you manually set the audience, that audience.
590−- if you activated a post, the post you activated.
591−- audience of the last post sent.
599−List all local nicknames.
603−Syntax: `;nick ~some-urbit`
605−Look up a nickname using the known ship-name.
607−#### Reverse Find Nickname
609−syntax: `;nick plato`
611−Find a ship's name using its nickname.
615−Syntax: `;nick ~some-urbit plato`
617−Create a new nickname.
621−Syntax: `;nick ~some-urbit ~`
623−Clear an assigned nickname.
625−#### Display Nicks, Not Ship-Names
629−Show nicknames instead of ship-names. If no local nickname is set, uses
630−that user's handle. If the user has no handle, just the urbit name.
632−#### Display Ship-Names, Not Nicks
634−Syntax: `;unset nicks`
636−Show ship-names instead of nicknames.
638−Nicknames and handles longer than 14 character will be truncated in
639−output. Nicknames are strictly local - like the names on entries in a
642−### Miscellaneous configuration
646−Syntax: `;set showtime`
648−Show the timestamp for each message.
652−Syntax: `;unset showtime`
654−Stop showing the timestamp for each message.
656−#### Change Time Zone
658−Syntax: `;set timezone [+/-][hours]`
660−Adjust the display of the timestamps to a specific timezone. Relative to UTC.
662−#### Sound Notification On
664−Syntax: `;set notify`
666−Emit a terminal bell sound if your six-syllable ship name is mentioned in
669−#### Sound Notification Off
671−Syntax `;unset notify`
673−Do not notify when your ship name is mentioned.
677−Syntax: `;set width [number]`
679−Set the rendering width of `:talk` to a specific number of characters.