@@ -235,100 +235,115 @@ Let’s get started using the `:chat-cli` application, also known more simply as
235235
236236### Quickstart
237237
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.
239239
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.
241241
242242### Joining a chat
243243
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
245245
246246Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
247247
248248Then:
249249
250250```
251−~your-urbit:chat-cli> ;join ~dopzod/urbit-help
251+~sampel-palnet:chat-cli/ ;join ~dopzod/urbit-help
252252```
253253
254−Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed. You c
255−
256−Post a line to `~dopzod/urbit-help:`
254+Now that you're in, try post a line to `~dopzod/urbit-help`:
257255
258256```
259−~your-urbit:chat-cli= Hello, world!
257+~sampel-palnet:chat-cli= Hello, world!
260258```
261259
262260You'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:
263261
264−
262+```
263+~sampel-palnet:chat-cli= ;chats
264+~dopzod/urbit-help
265+```
265266
266267Glyphs 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.
267268
268269```
269−~your-urbit:chat-cli= ;+
270−~your-urbit:chat-cli+
270+~sampel-palnet:chat-cli= ;+
271+~sampel-palnet:chat-cli+
271272```
272273
273274Use `;leave` to unsubscribe from a channel:
274275
275276```
276−~your-urbit:chat-cli= ;leave ~dopzod/urbit-help
277+~sampel-palnet:chat-cli= ;leave ~dopzod/urbit-help
277278```
278279
279280Now, let's create a channel we can invite some friends to:
280281
281282```
282−~your-urbit:chat-cli= ;create channel /my-channel
283+~sampel-palnet:chat-cli= ;create channel /my-channel
283284```
284285
285286Now you can tell your friends to `;join ~your-urbit/my-channel`.
286287
287−### Direct messaging
288+### Hoon
288289
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 `#`.
290291
291292```
292−~your-urbit:chat-cli= ;~talsur-todres
293+~sampel-palnet:chat-cli= #(add 2 2)
293294```
294295
295−You'll see your prompt change:
296+This will print as:
296297
297298```
298−~your-urbit:chat-cli[~talsur-todres]
299+~sampel-palnet# (add 2 2)
300+ 4
299301```
300302
301−Now you and `~talsur-todres` can exchange messages directly.
303+### URLs
304+
305+To share a URL, send it as its own message, with no content before or after it.
302306
303307```
304−~your-urbit:chat-cli[~talsur-todres] Hey buddy!
308+~sampel-palnet:chat-cli= https://urbit.org/
305309```
306310
307−To set your audience back to `~dopzod/urbit-help`:
311+This will print as:
308312
309313```
310−~your-urbit:chat-cli[~talsur-todres] ;~dopzod/urbit-help
314+~sampel-palnet/ https://urbit.org/
311315```
312316
313−You'll see your prompt change back:
317+### Expanding messages
318+
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.
314320
315321```
316−~your-urbit:chat-cli=
322+~sampel-palnet+ some message
323+----------[240]
324+~sampel-palnet+ let's try selecting this message!
325+~sampel-palnet+ another message
326+~sampel-palnet:chat-cli=
317327```
318328
319−#### Hoon
320−
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 `#`.
329+In the above example, we can select the middle message by issuing any of the following command:
322330
323331```
324−~your-urbit:chat-cli= #(add 2 2)
332+;240
333+;40
334+;;
325335```
326336
327−will print as
337+`;n` looks for the last message whose sequence number ends in `n`. `;;` simply picks the second-to-last message.
338+
339+Detailed message output will look something like this:
328340
329341```
330−~your-urbit# (add 2 2)
331−4
342+? 240
343+ 0v5.g7r7l.n0d7m.mp4bn.gp6vr.sm5lj at ~2019.10.17..22.08.27..8a03
344+ ~sampel-palnet
345+ to ~dopzod/urbit-help
346+let's try selecting this message!
332347```
333348
334349### Creating and managing chats
@@ -343,12 +358,12 @@ Creates and joins a chat, where `[type]` is any of the following:
343358- `channel`: public chat. Has a blacklist for write control.
344359- `village`: invite-only chat.
345360- `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.
347362
348363Let's create an example mailbox:
349364
350365```
351−sampel-palnet:chat-cli> ;create mailbox /coolbox ^
366+~sampel-palnet:chat-cli> ;create mailbox /coolbox ^
352367```
353368
354369#### Delete
@@ -357,35 +372,39 @@ Syntax: `;delete /name`
357372
358373Deletes a chat.
359374
360−### Status
375+#### Permission management
361376
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.
363378
364−#### Notifications off
379+Syntax: `;invite [rw] /name ~ships`
365380
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.
367383
368−Turn off status (and config) notifications.
384+For example, to grant two people full access to a `village` we created:
369385
370−#### Notifications on
386+```
387+~sampel-palnet:chat-cli> ;invite rw /hidden-village ~ravmel-ropdyl, ~rapfyr-diglyt
388+```
371389
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:
373391
374−Turn on status (and config) notifications.
392+```
393+~sampel-palnet:chat-cli> ;banish w /hidden-village ~rapfyr-diglyt
394+```
375395
376396#### Chat glyphs
377397
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
379399your messages will be sent.
380400
381401Glyphs are assigned by chat hash out of the following list:
382402
383403```
384−> = + - } ) , . " ' ^ $ % & @
404+! @ # $ % ^ & ( ) - = _ + [ ] { } ; ' \ : " , . < > ?
385405```
386406
387−Alphanumeric characters and `|#;:*~_` are reserved; all others (the
388−above list, and `\/!?({<`) can be manually assigned.
407+Alphanumeric characters and `|#/*~` are reserved; all others can be manually assigned.
389408
390409For example, `-` the glyph at the end of the prompt below might indicates that
391410messages 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 `=`:
403422~dopzod/urbit-help
404423```
405424
406−To see all of your glyph-bound subscriptions:
425+To see all of your glyph bindings:
407426
408427```
409428~sampel-palnet:chat-cli> ;what
@@ -412,50 +431,49 @@ To see all of your glyph-bound subscriptions:
412431= ~dopzod/urbit-help
413432```
414433
415−Not every audience has a glyph, however. When the audience doesn't have a glyph,
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`:
434+When the messaging target doesn't have a glyph, we see their name at the end of
435+the prompt instead. Here we're talking into `~dannum-mitryl/homework`:
418436
419437```
420−~sampel-palnet:chat-cli[~dannum-mitryl]
438+~sampel-palnet:chat-cli[~dannum-mitryl/homework]
421439```
422440
423441#### Bind
424442
425−Syntax: `;bind [glyph] /chat-name`
443+Syntax: `;bind [glyph] ~host/chat-name`
426444
427−Assigns the chosen glyph to a chat owned by your ship.
445+Assigns the chosen glyph to a chat.
428446
429447For example:
430448
431449```
432−~sampel-palnet:chat-cli> ;bind + /my-chat
450+~sampel-palnet:chat-cli> ;bind + ~dopzod/urbit-help
433451```
434452
435453#### Unbind
436454
437−Syntax: `;unbind [glyph] /chat-name`
455+Syntax: `;unbind [glyph] ~host/chat-name`
438456
439457Unassigns the chosen glyph from a chat owned by your ship.
440458
441459For example:
442460
443461```
444−~sampel-palnet:chat-cli> ;unbind + /my-chat
462+~sampel-palnet:chat-cli> ;unbind + ~dopzod/urbit-help
445463```
446464
465+If you don't specify a chat, all bindings for that glyph are removed.
466+
447467#### Prefixes
448468
449469Received posts are prefixed with a glyph to let you know what the
450470audience is. You can activate an individual post to see the full
451471audience.
452472
453−There are a few special-purpose glyphs:
473+There are a few special-purpose "glyphs":
454474
455475- `|` - Informational messages
456−- `:` - Posts directly to you
457−- `;` - Posts to you and others (a multiparty conversation)
458−- `*` - Posts to a complex audience that doesn't directly include you.
476+- `*` - Posts to a target you don't have a glyph binding for
459477
460478
461479### Configuration
@@ -472,32 +490,26 @@ Syntax: `;[glyph]`
472490
473491Set audience to the chat previously bound to the chosen glyph.
474492
475−#### Set audience to ship
476−
477−syntax `;~ship`
478−
479−Set audience to another ship.
480−
481493#### Set audience to own chat
482494
483−Syntax: `;%chat`
495+Syntax: `;/chat`
484496
485497Set audience to a chat on your own ship.
486498
487−#### Set audience and send message
499+### Miscellaneous configuration
500+
501+#### Change timezone
488502
489−Syntax: `;~dannum-mitryl this is a private message`
503+Syntax: `;set timezone [+/-][hours]`
490504
491−Set the audience and send a post in the same line. This works for all of the
492−above audience commands.
505+Adjust the display of timestamps to a specific timezone. Relative to UTC.
493506
494−Your audience is configured with regard to the following rules (in order):
507+#### Set width
495508
496−- if you manually set the audience, that audience.
497−- if you activated a post, the post you activated.
498−- audience of the last post sent.
509+Syntax: `;set width [number]`
499510
500−### Miscellaneous configuration
511+Set the rendering width of `:chat-cli` to a specific number of characters.
512+(Minimum of 30.)
501513
502514#### Show timestamps
503515
@@ -511,12 +523,6 @@ Syntax: `;unset showtime`
511523
512524Stop showing the timestamp for each message.
513525
514−#### Change timezone
515−
516−Syntax: `;set timezone [+/-][hours]`
517−
518−Adjust the display of timestamps to a specific timezone. Relative to UTC.
519−
520526#### Sound notification on
521527
522528Syntax: `;set notify`
@@ -530,13 +536,6 @@ Syntax `;unset notify`
530536
531537Do not notify when your ship name is mentioned.
532538
533−#### Set width
534−
535−Syntax: `;set width [number]`
536−
537−Set the rendering width of `:chat-cli` to a specific number of characters.
538−(Minimum of 30.)
539−
540539
541540## Shell {#using-the-shell}
542541