@@ -235,100 +235,115 @@ Let’s get started using the `:chat-cli` application, also known more simply as
236### Quickstart
236### Quickstart
238−The most common uses of `:chat-cli` right now are communicating over a public chat channel on `~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.
238+The most common uses of `:chat-cli` right now are communicating over a public chat channel on `~dopzod/urbit-help.` Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.
240−There are two ways of using `:chat-cli`: from the terminal running the Urbit process, or through the Landscape web UI available from your ship’s URL address, mentioned earlier in this guide.
240+Note that largely equivalent functionality is also available through Chat's web UI in landscape. This is available from your ship’s URL address, mentioned earlier in this guide.
242### Joining a chat
242### Joining a chat
244−In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four types of chats: the _channel_ (public with blacklist), _village_ (private with whitelist), the _journal_ (publicly readable, privately writable), and the _mailbox_ (privately readable, publicly writable). But 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](#messaging-manual) section later on.
244+In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four types of chats: the _channel_ (public with blacklist), _village_ (private with whitelist), the _journal_ (publicly readable, privately writable), and the _mailbox_ (privately readable, publicly writable). But 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](#messaging-manual) section later on.xxxx
246Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
246Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
251−~your-urbit:chat-cli> ;join ~dopzod/urbit-help
251+~sampel-palnet:chat-cli/ ;join ~dopzod/urbit-help
254−Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed. You c
256−Post a line to `~dopzod/urbit-help:`
254+Now that you're in, try post a line to `~dopzod/urbit-help`:
259−~your-urbit:chat-cli= Hello, world!
257+~sampel-palnet:chat-cli= Hello, world!
262You'll see your message printed below messages from others that came before it. You can always type `;chats` in the `chat-cli` prompt to list all the chats you're in:
260You'll see your message printed below messages from others that came before it. You can always type `;chats` in the `chat-cli` prompt to list all the chats you're in:
263+~sampel-palnet:chat-cli= ;chats
266Glyphs will be automatically assigned to channels, but have the option of binding a glyph (single non-alphanumeric character) to the channel you're joining; the syntax is in the form of `;join ~dopzod/books +`. The chosen glyph will be the symbol that ends your prompt, and it will be what you use as a shortcut to switch to this channel.
267Glyphs will be automatically assigned to channels, but have the option of binding a glyph (single non-alphanumeric character) to the channel you're joining; the syntax is in the form of `;join ~dopzod/books +`. The chosen glyph will be the symbol that ends your prompt, and it will be what you use as a shortcut to switch to this channel.
269−~your-urbit:chat-cli= ;+
270+~sampel-palnet:chat-cli= ;+
270−~your-urbit:chat-cli+
271+~sampel-palnet:chat-cli+
273Use `;leave` to unsubscribe from a channel:
274Use `;leave` to unsubscribe from a channel:
276−~your-urbit:chat-cli= ;leave ~dopzod/urbit-help
277+~sampel-palnet:chat-cli= ;leave ~dopzod/urbit-help
279Now, let's create a channel we can invite some friends to:
280Now, let's create a channel we can invite some friends to:
282−~your-urbit:chat-cli= ;create channel /my-channel
283+~sampel-palnet:chat-cli= ;create channel /my-channel
285Now you can tell your friends to `;join ~your-urbit/my-channel`.
286Now you can tell your friends to `;join ~your-urbit/my-channel`.
287−### Direct messaging
288+### Hoon
289−To send a direct message to someone, first set your audience:
290+You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.
292−~your-urbit:chat-cli= ;~talsur-todres
293+~sampel-palnet:chat-cli= #(add 2 2)
295−You'll see your prompt change:
296+This will print as:
298−~your-urbit:chat-cli[~talsur-todres]
299+~sampel-palnet# (add 2 2)
301−Now you and `~talsur-todres` can exchange messages directly.
303+### URLs
305+To share a URL, send it as its own message, with no content before or after it.
304−~your-urbit:chat-cli[~talsur-todres] Hey buddy!
308+~sampel-palnet:chat-cli= https://urbit.org/
307−To set your audience back to `~dopzod/urbit-help`:
311+This will print as:
310−~your-urbit:chat-cli[~talsur-todres] ;~dopzod/urbit-help
314+~sampel-palnet/ https://urbit.org/
313−You'll see your prompt change back:
317+### Expanding messages
319+In the case of URLs, they may be too long to display on a single message line. For Hoon code, the code or result could be big. In `:chat-cli`, these get shortened when initially printed out. To view the entire contents, you can select the message in various ways.
322+~sampel-palnet+ some message
324+~sampel-palnet+ let's try selecting this message!
325+~sampel-palnet+ another message
316−~your-urbit:chat-cli=
326+~sampel-palnet:chat-cli=
319−#### Hoon
329+In the above example, we can select the middle message by issuing any of the following command:
321−You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.
324−~your-urbit:chat-cli= #(add 2 2)
332+;240
327−will print as
337+`;n` looks for the last message whose sequence number ends in `n`. `;;` simply picks the second-to-last message.
339+Detailed message output will look something like this:
330−~your-urbit# (add 2 2)
342+? 240
331−4
343+ 0v5.g7r7l.n0d7m.mp4bn.gp6vr.sm5lj at ~2019.10.17..22.08.27..8a03
345+ to ~dopzod/urbit-help
346+let's try selecting this message!
334### Creating and managing chats
349### Creating and managing chats
@@ -343,12 +358,12 @@ Creates and joins a chat, where `[type]` is any of the following:
343- `channel`: public chat. Has a blacklist for write control.
358- `channel`: public chat. Has a blacklist for write control.
344- `village`: invite-only chat.
359- `village`: invite-only chat.
345- `journal`: publicly readable, invite-only for writing.
360- `journal`: publicly readable, invite-only for writing.
346−- `mailbox`: publicly writeable, can only be read by its host.
361+- `mailbox`: publicly writeable, invite-only for reading.
348Let's create an example mailbox:
363Let's create an example mailbox:
351−sampel-palnet:chat-cli> ;create mailbox /coolbox ^
366+~sampel-palnet:chat-cli> ;create mailbox /coolbox ^
354#### Delete
369#### Delete
@@ -357,35 +372,39 @@ Syntax: `;delete /name`
358Deletes a chat.
373Deletes a chat.
360−### Status
375+#### Permission management
362−You'll see status notifications when people enter or leave chats you're subscribed to.
377+You can permit and ban people from reading and/or writing to the chats you host, using `;invite` and `;banish` command respectively.
364−#### Notifications off
379+Syntax: `;invite [rw] /name ~ships`
366−Syntax: `;set quiet`
381+Where `rw` is either `r`, `w`, or `rw`, representing "read" and "write" permissions.
382+And where `~ships` is a comma-seperated list of ships to invite.
368−Turn off status (and config) notifications.
384+For example, to grant two people full access to a `village` we created:
370−#### Notifications on
386+```
387+~sampel-palnet:chat-cli> ;invite rw /hidden-village ~ravmel-ropdyl, ~rapfyr-diglyt
372−Syntax: `;unset quiet`
390+Similarly, if we later want to revoke the writing permissions for one of them, but still allow them to read new messages, we can run:
374−Turn on status (and config) notifications.
392+```
393+~sampel-palnet:chat-cli> ;banish w /hidden-village ~rapfyr-diglyt
376#### Chat glyphs
396#### Chat glyphs
378−Glyphs are found at the end of your prompt to as a quick indicator of where
398+Glyphs are found at the end of your prompt, as a quick indicator of where
379your messages will be sent.
399your messages will be sent.
381Glyphs are assigned by chat hash out of the following list:
401Glyphs are assigned by chat hash out of the following list:
384−> = + - } ) , . " ' ^ $ % & @
404+! @ # $ % ^ & ( ) - = _ + [ ] { } ; ' \ : " , . < > ?
387−Alphanumeric characters and `|#;:*~_` are reserved; all others (the
407+Alphanumeric characters and `|#/*~` are reserved; all others can be manually assigned.
388−above list, and `\/!?({<`) can be manually assigned.
390For example, `-` the glyph at the end of the prompt below might indicates that
409For example, `-` the glyph at the end of the prompt below might indicates that
391messages sent from this prompt will go to some chat with that glyph:
410messages sent from this prompt will go to some chat with that glyph:
@@ -403,7 +422,7 @@ subscriptions which are bound to glyphs. For example, to see `=`:
403~dopzod/urbit-help
422~dopzod/urbit-help
406−To see all of your glyph-bound subscriptions:
425+To see all of your glyph bindings:
409~sampel-palnet:chat-cli> ;what
428~sampel-palnet:chat-cli> ;what
@@ -412,50 +431,49 @@ To see all of your glyph-bound subscriptions:
412= ~dopzod/urbit-help
431= ~dopzod/urbit-help
415−Not every audience has a glyph, however. When the audience doesn't have a glyph,
434+When the messaging target doesn't have a glyph, we see their name at the end of
416−such as in the case of direct-messaging a ship, we see their name at the end of
417−the prompt instead. Here we're talking directly to `~dannum-mitryl`:
435+the prompt instead. Here we're talking into `~dannum-mitryl/homework`:
420−~sampel-palnet:chat-cli[~dannum-mitryl]
438+~sampel-palnet:chat-cli[~dannum-mitryl/homework]
425−Syntax: `;bind [glyph] /chat-name`
443+Syntax: `;bind [glyph] ~host/chat-name`
427−Assigns the chosen glyph to a chat owned by your ship.
445+Assigns the chosen glyph to a chat.
429For example:
447For example:
432−~sampel-palnet:chat-cli> ;bind + /my-chat
450+~sampel-palnet:chat-cli> ;bind + ~dopzod/urbit-help
435#### Unbind
453#### Unbind
437−Syntax: `;unbind [glyph] /chat-name`
455+Syntax: `;unbind [glyph] ~host/chat-name`
439Unassigns the chosen glyph from a chat owned by your ship.
457Unassigns the chosen glyph from a chat owned by your ship.
441For example:
459For example:
444−~sampel-palnet:chat-cli> ;unbind + /my-chat
462+~sampel-palnet:chat-cli> ;unbind + ~dopzod/urbit-help
465+If you don't specify a chat, all bindings for that glyph are removed.
447#### Prefixes
467#### Prefixes
449Received posts are prefixed with a glyph to let you know what the
469Received posts are prefixed with a glyph to let you know what the
450audience is. You can activate an individual post to see the full
470audience is. You can activate an individual post to see the full
453−There are a few special-purpose glyphs:
473+There are a few special-purpose "glyphs":
455- `|` - Informational messages
475- `|` - Informational messages
456−- `:` - Posts directly to you
476+- `*` - Posts to a target you don't have a glyph binding for
457−- `;` - Posts to you and others (a multiparty conversation)
458−- `*` - Posts to a complex audience that doesn't directly include you.
461### Configuration
479### Configuration
@@ -472,32 +490,26 @@ Syntax: `;[glyph]`
473Set audience to the chat previously bound to the chosen glyph.
491Set audience to the chat previously bound to the chosen glyph.
475−#### Set audience to ship
479−Set audience to another ship.
481#### Set audience to own chat
493#### Set audience to own chat
483−Syntax: `;%chat`
495+Syntax: `;/chat`
485Set audience to a chat on your own ship.
497Set audience to a chat on your own ship.
487−#### Set audience and send message
499+### Miscellaneous configuration
489−Syntax: `;~dannum-mitryl this is a private message`
503+Syntax: `;set timezone [+/-][hours]`
491−Set the audience and send a post in the same line. This works for all of the
505+Adjust the display of timestamps to a specific timezone. Relative to UTC.
492−above audience commands.
494−Your audience is configured with regard to the following rules (in order):
507+#### Set width
496−- if you manually set the audience, that audience.
509+Syntax: `;set width [number]`
497−- if you activated a post, the post you activated.
498−- audience of the last post sent.
500−### Miscellaneous configuration
511+Set the rendering width of `:chat-cli` to a specific number of characters.
502#### Show timestamps
514#### Show timestamps
@@ -511,12 +523,6 @@ Syntax: `;unset showtime`
512Stop showing the timestamp for each message.
524Stop showing the timestamp for each message.
516−Syntax: `;set timezone [+/-][hours]`
518−Adjust the display of timestamps to a specific timezone. Relative to UTC.
520#### Sound notification on
526#### Sound notification on
522Syntax: `;set notify`
528Syntax: `;set notify`
@@ -530,13 +536,6 @@ Syntax `;unset notify`
531Do not notify when your ship name is mentioned.
537Do not notify when your ship name is mentioned.
535−Syntax: `;set width [number]`
537−Set the rendering width of `:chat-cli` to a specific number of characters.
541## Shell {#using-the-shell}
540## Shell {#using-the-shell}