@@ -1,255 +0,0 @@
1−+++
2−title = "Messaging"
3−template = "doc.html"
4−weight = 2
5−+++
6−
7−Let’s get started using the `:chat-cli` application, also known more simply as
8−_Chat_. It's the simplest way to talk to people using the command line
9−interface.
10−
11−### Quickstart
12−
13−The most common use for `:chat-cli` right now is, of course, communicating in group chats.
14−
15−### Joining a chat
16−
17−In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four "types" of chats, 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 [chat management](#chat-management) section later on.
18−
19−Join the Urbit Community from Dojo using `:group-view &group-view-action [%join [~bitbet-bolbel %urbit-community] ~bitbet-bolbel]`. Once you've joined, join the General chat from chat-cli. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
20−
21−Then:
22−
23−```
24−~sampel-palnet:chat-cli/ ;join ~darrux-landes/general
25−```
26−
27−Now that you're in, try post a line to `~darrux-landes/general`:
28−
29−```
30−~sampel-palnet:chat-cli= Hello, world!
31−```
32−
33−You'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:
34−
35−```
36−~sampel-palnet:chat-cli= ;chats
37−~darrux-landes/general
38−```
39−
40−Glyphs 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.
41−
42−```
43−~sampel-palnet:chat-cli= ;+
44−~sampel-palnet:chat-cli+
45−```
46−
47−Use `;leave` to unsubscribe from a channel:
48−
49−```
50−~sampel-palnet:chat-cli= ;leave ~darrux-landes/general
51−```
52−
53−Now, let's create a channel we can invite some friends to:
54−
55−```
56−~sampel-palnet:chat-cli= ;create channel /my-channel
57−```
58−
59−Now you can tell your friends to `;join ~your-urbit/my-channel`.
60−
61−In order to see messages in `:chat-cli` you may need to do the following in Dojo:
62−
63−```
64−:chat-cli %connect
65−```
66−
67−### Creating and managing chats {% #chat-management %}
68−
69−As mentioned before, any urbit can host any number of chats. Existing chats can be deleted or modified with various commands. All commands in this section should be sent from the `chat-cli>` prompt.
70−
71−#### Create
72−
73−Syntax: `;create [type] /name +`, where `+` represents an optional glyph.
74−
75−Creates and joins a chat, where `[type]` is any of the following:
76−
77−- `channel`: public chat. Has a blacklist for write control.
78−- `village`: invite-only chat.
79−- `journal`: publicly readable, invite-only for writing.
80−- `mailbox`: publicly writeable, invite-only for reading.
81−
82−Let's create an example mailbox:
83−
84−```
85−~sampel-palnet:chat-cli> ;create mailbox /coolbox ^
86−```
87−
88−#### Delete
89−
90−Syntax: `;delete /name`
91−
92−Deletes a chat.
93−
94−#### Permission management
95−
96−You can permit and ban people from reading and/or writing to the chats you host, using `;invite` and `;banish` command respectively.
97−
98−Syntax: `;invite [rw] /name ~ships`
99−
100−Where `rw` is either `r`, `w`, or `rw`, representing "read" and "write" permissions.
101−And where `~ships` is a comma-seperated list of ships to invite.
102−
103−For example, to grant two people full access to a `village` we created:
104−
105−```
106−~sampel-palnet:chat-cli> ;invite rw /hidden-village ~ravmel-ropdyl, ~rapfyr-diglyt
107−```
108−
109−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:
110−
111−```
112−~sampel-palnet:chat-cli> ;banish w /hidden-village ~rapfyr-diglyt
113−```
114−
115−#### Chat glyphs
116−
117−Glyphs are found at the end of your prompt, as a quick indicator of where
118−your messages will be sent.
119−
120−Glyphs are assigned by chat hash out of the following list:
121−
122−```
123−! @ # $ % ^ & ( ) - = _ + [ ] { } ; ' \ : " , . < > ?
124−```
125−
126−Alphanumeric characters and `|#/*~` are reserved; all others can be manually assigned.
127−
128−For example, `-` the glyph at the end of the prompt below might indicates that
129−messages sent from this prompt will go to some chat with that glyph:
130−
131−```
132−~sampel-palnet:chat-cli-
133−```
134−
135−To see what chat is bound to a glyph, use the `;what` command followed by the
136−glyph in question, or use `;what` without specifying a glyph to see all of your
137−subscriptions which are bound to glyphs. For example, to see `=`:
138−
139−```
140−~sampel-palnet:chat-cli> ;what =
141−~dopzod/urbit-help
142−```
143−
144−To see all of your glyph bindings:
145−
146−```
147−~sampel-palnet:chat-cli> ;what
148−> ~paldev/numismatic-forum
149−. ~middev/ny-martians
150−= ~dopzod/urbit-help
151−```
152−
153−When the messaging target doesn't have a glyph, we see their name at the end of
154−the prompt instead. Here we're talking into `~dannum-mitryl/homework`:
155−
156−```
157−~sampel-palnet:chat-cli[~dannum-mitryl/homework]
158−```
159−
160−#### Bind
161−
162−Syntax: `;bind [glyph] ~host/chat-name`
163−
164−Assigns the chosen glyph to a chat.
165−
166−For example:
167−
168−```
169−~sampel-palnet:chat-cli> ;bind + ~dopzod/urbit-help
170−```
171−
172−#### Unbind
173−
174−Syntax: `;unbind [glyph] ~host/chat-name`
175−
176−Unassigns the chosen glyph from a chat owned by your ship.
177−
178−For example:
179−
180−```
181−~sampel-palnet:chat-cli> ;unbind + ~dopzod/urbit-help
182−```
183−
184−If you don't specify a chat, all bindings for that glyph are removed.
185−
186−#### Prefixes
187−
188−Received posts are prefixed with a glyph to let you know what the
189−audience is. You can activate an individual post to see the full
190−audience.
191−
192−There are a few special-purpose "glyphs":
193−
194−- `|` - Informational messages
195−- `*` - Posts to a target you don't have a glyph binding for
196−
197−### Configuration
198−
199−#### Set audience
200−
201−`;~ship/chat`
202−
203−Set audience to `~ship/chat`.
204−
205−#### Set audience by glyph
206−
207−Syntax: `;[glyph]`
208−
209−Set audience to the chat previously bound to the chosen glyph.
210−
211−#### Set audience to own chat
212−
213−Syntax: `;/chat`
214−
215−Set audience to a chat on your own ship.
216−
217−### Miscellaneous configuration
218−
219−#### Change timezone
220−
221−Syntax: `;set timezone [+/-][hours]`
222−
223−Adjust the display of timestamps to a specific timezone. Relative to UTC.
224−
225−#### Set width
226−
227−Syntax: `;set width [number]`
228−
229−Set the rendering width of `:chat-cli` to a specific number of characters.
230−(Minimum of 30.)
231−
232−#### Show timestamps
233−
234−Syntax: `;set showtime`
235−
236−Show the timestamp for each message. This is set by default.
237−
238−#### Hide timestamps
239−
240−Syntax: `;unset showtime`
241−
242−Stop showing the timestamp for each message.
243−
244−#### Sound notification on
245−
246−Syntax: `;set notify`
247−
248−Emit a terminal bell sound if your six-syllable ship name is mentioned in
249−a message. This is set by default.
250−
251−#### Sound notification off
252−
253−Syntax `;unset notify`
254−
255−Do not notify when your ship name is mentioned.