diff --git a/README.md b/README.md index edfd274219..a47974b281 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Zulip Terminal - [Zulip](https://zulip.com)'s official terminal client -[Recent changes](https://github.com/zulip/zulip-terminal/blob/main/CHANGELOG.md) | [Configuration](#Configuration) | [Hot Keys](https://github.com/zulip/zulip-terminal/blob/main/docs/hotkeys.md) | [FAQs](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md) | [Development](#contributor-guidelines) +[Recent changes](https://github.com/zulip/zulip-terminal/blob/main/CHANGELOG.md) | [Configuration](#Configuration) | [Hot Keys](https://github.com/zulip/zulip-terminal/blob/main/docs/hotkeys.md) | [FAQs](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md) | [Development](#contributor-guidelines) | [Tutorial](https://github.com/zulip/zulip-terminal/blob/main/docs/getting-started.md) [![Zulip chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://chat.zulip.org/#narrow/stream/206-zulip-terminal) [![PyPI](https://img.shields.io/pypi/v/zulip-term.svg)](https://pypi.python.org/pypi/zulip-term) @@ -21,6 +21,8 @@ Specific aims include: * Exploring alternative user interface designs suited to the display and input constraints * Supporting a wide range of platforms and terminal emulators +Learn how to use Zulip Terminal with our [Tutorial](https://github.com/zulip/zulip-terminal/blob/main/docs/getting-started.md). + ### Feature status We consider the client to already provide a fairly stable moderately-featureful everyday-user experience. @@ -84,7 +86,7 @@ If it doesn't find this file, you have two options: **NOTE:** If your server uses self-signed certificates or an insecure connection, you will need to add extra options to the `zuliprc` file manually - see the documentation for the [Zulip python module](https://pypi.org/project/zulip/). -We suggest running `zulip-term` using the `-e` or `--explore` option (in explore mode) when you are trying Zulip Terminal for the first time, where we intentionally do not mark messages as read. +We suggest running `zulip-term` using the `-e` or `--explore` option (in explore mode) when you are trying Zulip Terminal for the first time, where we intentionally do not mark messages as read. Try following along with our [Tutorial](https://github.com/zulip/zulip-terminal/blob/main/docs/getting-started.md) to get the hang of things. ## Configuration diff --git a/docs/getting-started-imgs/current-narrow.png b/docs/getting-started-imgs/current-narrow.png new file mode 100644 index 0000000000..a68e63afab Binary files /dev/null and b/docs/getting-started-imgs/current-narrow.png differ diff --git a/docs/getting-started-imgs/edit-message.png b/docs/getting-started-imgs/edit-message.png new file mode 100644 index 0000000000..ec7a24791e Binary files /dev/null and b/docs/getting-started-imgs/edit-message.png differ diff --git a/docs/getting-started-imgs/help.png b/docs/getting-started-imgs/help.png new file mode 100644 index 0000000000..d965e6e071 Binary files /dev/null and b/docs/getting-started-imgs/help.png differ diff --git a/docs/getting-started-imgs/layout3.png b/docs/getting-started-imgs/layout3.png new file mode 100644 index 0000000000..54a4690451 Binary files /dev/null and b/docs/getting-started-imgs/layout3.png differ diff --git a/docs/getting-started-imgs/narrow-stream.png b/docs/getting-started-imgs/narrow-stream.png new file mode 100644 index 0000000000..7d02277490 Binary files /dev/null and b/docs/getting-started-imgs/narrow-stream.png differ diff --git a/docs/getting-started-imgs/narrow-topic.png b/docs/getting-started-imgs/narrow-topic.png new file mode 100644 index 0000000000..2046758917 Binary files /dev/null and b/docs/getting-started-imgs/narrow-topic.png differ diff --git a/docs/getting-started-imgs/new-topic.png b/docs/getting-started-imgs/new-topic.png new file mode 100644 index 0000000000..1b2339675b Binary files /dev/null and b/docs/getting-started-imgs/new-topic.png differ diff --git a/docs/getting-started-imgs/raw/current-narrow-raw.png b/docs/getting-started-imgs/raw/current-narrow-raw.png new file mode 100644 index 0000000000..8416b4c795 Binary files /dev/null and b/docs/getting-started-imgs/raw/current-narrow-raw.png differ diff --git a/docs/getting-started-imgs/raw/edit-message-raw.png b/docs/getting-started-imgs/raw/edit-message-raw.png new file mode 100644 index 0000000000..d2c68a5bb5 Binary files /dev/null and b/docs/getting-started-imgs/raw/edit-message-raw.png differ diff --git a/docs/getting-started-imgs/raw/narrow-stream-raw.png b/docs/getting-started-imgs/raw/narrow-stream-raw.png new file mode 100644 index 0000000000..54b55aee83 Binary files /dev/null and b/docs/getting-started-imgs/raw/narrow-stream-raw.png differ diff --git a/docs/getting-started-imgs/raw/narrow-topic-raw.png b/docs/getting-started-imgs/raw/narrow-topic-raw.png new file mode 100644 index 0000000000..fe5b581455 Binary files /dev/null and b/docs/getting-started-imgs/raw/narrow-topic-raw.png differ diff --git a/docs/getting-started-imgs/raw/new-topic-raw.png b/docs/getting-started-imgs/raw/new-topic-raw.png new file mode 100644 index 0000000000..1f5401f696 Binary files /dev/null and b/docs/getting-started-imgs/raw/new-topic-raw.png differ diff --git a/docs/getting-started-imgs/raw/read-messages-raw.png b/docs/getting-started-imgs/raw/read-messages-raw.png new file mode 100644 index 0000000000..6c00c33a0f Binary files /dev/null and b/docs/getting-started-imgs/raw/read-messages-raw.png differ diff --git a/docs/getting-started-imgs/raw/reply-raw.png b/docs/getting-started-imgs/raw/reply-raw.png new file mode 100644 index 0000000000..04cdcbfecf Binary files /dev/null and b/docs/getting-started-imgs/raw/reply-raw.png differ diff --git a/docs/getting-started-imgs/raw/send-pm-autocomplete1-raw.png b/docs/getting-started-imgs/raw/send-pm-autocomplete1-raw.png new file mode 100644 index 0000000000..7145c1c9bd Binary files /dev/null and b/docs/getting-started-imgs/raw/send-pm-autocomplete1-raw.png differ diff --git a/docs/getting-started-imgs/raw/send-pm-autocomplete2-raw.png b/docs/getting-started-imgs/raw/send-pm-autocomplete2-raw.png new file mode 100644 index 0000000000..440a5031c7 Binary files /dev/null and b/docs/getting-started-imgs/raw/send-pm-autocomplete2-raw.png differ diff --git a/docs/getting-started-imgs/raw/send-pm-raw.png b/docs/getting-started-imgs/raw/send-pm-raw.png new file mode 100644 index 0000000000..386eb202bb Binary files /dev/null and b/docs/getting-started-imgs/raw/send-pm-raw.png differ diff --git a/docs/getting-started-imgs/raw/thumbs-up-raw.png b/docs/getting-started-imgs/raw/thumbs-up-raw.png new file mode 100644 index 0000000000..145ac045f8 Binary files /dev/null and b/docs/getting-started-imgs/raw/thumbs-up-raw.png differ diff --git a/docs/getting-started-imgs/read-messages.png b/docs/getting-started-imgs/read-messages.png new file mode 100644 index 0000000000..e5d9f4d22e Binary files /dev/null and b/docs/getting-started-imgs/read-messages.png differ diff --git a/docs/getting-started-imgs/reply-to-message.png b/docs/getting-started-imgs/reply-to-message.png new file mode 100644 index 0000000000..6568c4c763 Binary files /dev/null and b/docs/getting-started-imgs/reply-to-message.png differ diff --git a/docs/getting-started-imgs/send-pm-autocomplete1.png b/docs/getting-started-imgs/send-pm-autocomplete1.png new file mode 100644 index 0000000000..75cc2e1454 Binary files /dev/null and b/docs/getting-started-imgs/send-pm-autocomplete1.png differ diff --git a/docs/getting-started-imgs/send-pm-autocomplete2.png b/docs/getting-started-imgs/send-pm-autocomplete2.png new file mode 100644 index 0000000000..da1d4703f9 Binary files /dev/null and b/docs/getting-started-imgs/send-pm-autocomplete2.png differ diff --git a/docs/getting-started-imgs/send-pm.png b/docs/getting-started-imgs/send-pm.png new file mode 100644 index 0000000000..0ab07c839d Binary files /dev/null and b/docs/getting-started-imgs/send-pm.png differ diff --git a/docs/getting-started-imgs/thumbs-up.png b/docs/getting-started-imgs/thumbs-up.png new file mode 100644 index 0000000000..647afef4b1 Binary files /dev/null and b/docs/getting-started-imgs/thumbs-up.png differ diff --git a/docs/getting-started-imgs/understand-layout.png b/docs/getting-started-imgs/understand-layout.png new file mode 100644 index 0000000000..11ef4ad351 Binary files /dev/null and b/docs/getting-started-imgs/understand-layout.png differ diff --git a/docs/getting-started-imgs/your-cursor.png b/docs/getting-started-imgs/your-cursor.png new file mode 100644 index 0000000000..c5619a5986 Binary files /dev/null and b/docs/getting-started-imgs/your-cursor.png differ diff --git a/docs/getting-started.md b/docs/getting-started.md index bf8f6be678..d1b5cbd806 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,21 +1,193 @@ -Hi, are you new to [Zulip](https://github.com/zulip/zulip)? If so, we recommend trying out our [web-client](https://chat.zulip.org) first to understand the concept of [streams/topics/PMs](https://zulip.com/help/about-streams-and-topics) in the world of Zulip. Just sending a message or two in [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) stream should help you get started. +[//]: # (For future development: The images in the tutorial were taken from a terminal window with 135 columns and 35 lines. The blue arrows are #4EC8FB.) -Now let's help you get started with using zulip terminal. First, go ahead and complete the [installation](https://github.com/zulip/zulip-terminal#installation). If you encountered any issues, we have common issues and their solutions listed [here](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md). +# Zulip Terminal User Tutorial -If you encountered any issues above or have any queries, feel free to ask for help at [#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal) or support@zulip.com. +Hi, are you new to [Zulip](https://github.com/zulip/zulip)? If so, we recommend trying out our [web-client](https://chat.zulip.org) first to understand the concept of [streams/topics/PMs](https://zulip.com/help/about-streams-and-topics) in the world of Zulip. Please read through our [community docs](https://zulip.readthedocs.io/en/latest/contributing/chat-zulip-org.html) to get a feel for how things work. Just sending a message or two in the [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) stream should help you get started. If you don't already have a Zulip account, you'll also have to use our [web-client](https://chat.zulip.org) to sign up because currently you can't create an account using Zulip Terminal. -## Tutorial -I would like you to try out a few of our keyboard shortcuts and send a couple message to help you get familiar with zulip terminal. +Now let's help you get started with using Zulip Terminal. First, if you haven't already, go ahead and complete the [installation](https://github.com/zulip/zulip-terminal#installation). If you encountered any issues, we have common issues and their solutions listed [here](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md) if you run into trouble. Feel free to ask questions or for help at [#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal) or support@zulip.com. -#### What do you see? -![Screenshot](https://user-images.githubusercontent.com/9568999/106061037-b659a580-60a9-11eb-8ff8-ea1c54ac9084.png) +## Overview -Zulip Terminal is divided into three columns/divisions. -**The left column** shows list of all the streams you are subscribed to and some buttons for viewing different types of messages. -**The middle column** displays all the messages in the current narrow. -**The right column** shows all the active(green)/idle(yellow)/offline(white) users. +This tutorial was designed to be interactive. We highly recomend opening up Zulip Terminal and following along! We'll try out a few keyboard shortcuts and send a couple messages to help familiarize ourselves with Zulip Terminal. Here's an overview of the features we'll be walking you through: -Now that you know what you are looking at, how about checking out some of our features using [keyboard shortcuts](https://github.com/zulip/zulip-terminal#hot-keys)... +0. [Open Zulip Terminal](#Open-Zulip-Terminal) +1. [Understand the Layout](#Understand-the-Layout) +2. [Your Cursor](#Your-Cursor) +3. [Keyboard Shortcuts](#Keyboard-Shortcuts) +4. [Narrowing](#Narrowing) + + [Your Current Narrow](#Your-Current-Narrow) + + [Narrow to a Stream](#Narrow-to-a-Stream) + + [Narrow to a Topic](#Narrow-to-a-Topic) +5. [Reading Messages](#Reading-Messages) + + [Narrow to the Stream or Topic of a Message](#Narrow-to-the-Stream-or-Topic-of-a-Message) +6. [Sending Messages](#Sending-Messages) + + [Reply to a Message](#Reply-to-a-Message) + + [Reply via a Private Message](#Reply-via-a-Private-Message) + + [Send a Private Message to Someone New](#Send-a-Private-Message-to-Someone-New) + + [Create a New Topic](#Create-a-New-Topic) +7. [Edit a Message](#Edit-a-Message) +8. [Close Zulip Terminal](#Close-Zulip-Terminal) -### Narrowing to a stream -Narrowing to a stream implies you have set middle column to show messages present in that stream. Let's try narrowing to [# test here](https://chat.zulip.org/#narrow/stream/7-test-here) from zulip terminal. Press q to focus on the stream search box in the left column. Type `test here` +*Note: You can always use ? to open **help** and view keyboard shortcuts.* + +## Open Zulip Terminal + +Once you have [installed](https://github.com/zulip/zulip-terminal#installation) the app, use the `zulip-term` command to run it within your terminal. You will be prompted to add the URL of the organization you're a part of—use chat.zulip.org to join the Zulip community server—and log into your account. If you don't already have a Zulip account, you'll have to use our web-client to sign up because currently you can't create an account using Zulip Terminal. Learn more about how to [sign up for an account](https://zulip.com/help/join-a-zulip-organization). If you're looking to join the Zulip community server you can do so [here](https://chat.zulip.org). + +If you have issues opening Zulip Terminal, check out our [Running for the First Time](https://github.com/zulip/zulip-terminal#running-for-the-first-time) section. + +*Note: This tutorial assumes you're on the Zulip Community Server. While you can still follow along if you're not, various examples won't be the same (such as the [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) stream).* + +## Understand the Layout + + + +Zulip Terminal is divided into three columns/divisions: ++ **The left column** shows list of all the streams you are subscribed to and some keyboard shortcuts for viewing different types of messages. ++ **The middle column** displays all the messages in the current narrow. ++ **The right column** shows all the active(green)/idle(yellow)/offline(white) users. + +## Your Cursor + +When you first open Zulip Terminal, your cursor will be located in the upper left-hand corner on **All Messages**. You can tell because the section will be highlighted (see image below). You can use your cursor to navigate around Zulip Terminal - let's try moving the cursor around and see what happens. Try moving it left (left/h), right (right/l), up (Up/k) and down (Down/j). + + + +## Keyboard Shortcuts + +Sometimes it can take forever to manually move our cursor where we want it - that's why Zulip Terminal has keyboard shortcuts! Type ? to open **help** and view a list of keyboard shortcuts. You can also view a list of [keyboard shortcuts here.](https://github.com/zulip/zulip-terminal/blob/main/docs/hotkeys.md) + + + +Let's try out a few of these shortcuts! + ++ First, type shiftp to view your **Private Messages** (PMs). + ++ Second, type # to view all messages you were mentioned (@'ed) in. + ++ Third, type / to jump to the search bar at the top of the screen in the middle column. Type esc to move your cursor out of the search box so we can use our keyboard shortcuts again (otherwise you'd just be typing them in the search box!). + +esc is one of the most important shortcuts and is used for much more than exiting the search box—it's essentially the 'go back' button. If you're ever somewhere and you can't seem to get out, type esc. + + +## Narrowing + +You'll be hearing the term 'narrow' a lot in Zulip. What does it mean? + ++ **Noun**: A narrow is a set of filters for Zulip messages, that can be based on many different factors (like sender, stream, topic, search keywords, etc.). ++ **Verb**: The process of navigating to a different narrow. For example, to go from viewing a stream to a topic within that stream. There are several different ways to 'narrow to a narrow' so to speak. For example, you can use the keyboard shortcuts as we did in the section above. When you used the keyboard shortcut shiftp to view your private messages (PMs), you 'narrowed' to the **Private Messages** narrow. + +### Your Current Narrow + +Your current narrow is displayed at the top of Zulip Terminal in the middle column. The current narrow in the image below is **Starred messages**. If you ever get lost, just look here. + + + +### Narrow to a Stream +To 'narrow to a stream' means to set the middle column to only show messages present in that stream. Let's try narrowing to the **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream. [Move your cursor](#Your-Cursor) to the left column of Zulip Terminal and then move your cursor down (Down/j) until it rests on "#test here". Press Enter to narrow to the stream. + +Check out the top of the middle column, your current narrow should now be "test here" like in the image below. + +*Note: The colors in your terminal may vary from the ones in the screenshot.* + + + +### Narrow to a Topic + +First, let's move our cursor back to the **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream in the left column - otherwise the following keyboard shortcut won't work. With our cursor on the [**#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream, type t to toggle on a list of topics within that stream. Move your cursor to a random topic and then press Enter to narrow to that topic. You've successfully narrowed to a topic! Notice how at the top of the middle column your current narrow is displayed as **test here ► topic you chose**. + +To toggle off the topic list and go back to viewing the stream list, move your cursor back to the list of topics in the left column and type t again. + + + +## Reading Messages + +Time to read some messages! Read messages by scrolling up (Up/k) and down (Down/j). Any message that your cursor selects will be marked as read. If a message was visible, but never selected, it will not be marked as read. Messages marked as 'read' are colored white and unread messages are blue - notice how in the image below all of the messages below my cursor are blue and all the ones above it are white. Notice also how the number of unread messages in your current narrow decreases as you scroll through them. Learn more about when messages are marked as read [here](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md#when-are-messages-marked-as-having-been-read). + +When you enter a new narrow, Zulip Terminal normally will automatically place your cursor on the oldest unread message in that narrow. + + + +### Narrow to the Stream or Topic of a Message + +Now that we know how to read through messages, let's try filtering to see only messages related to the one we currently have selected. To see this in action you'll want to head back to **All Messages** (a) before each bullet point. + ++ Type s to narrow to the stream of the current message. + ++ Type shifts to narrow to the topic of the current message. *Note that this works even if you weren't already in the topic's stream.* + +You can also type z to 'zoom in' or 'zoom out.' What do I mean by 'zoom in/out?' Essentially if you're currently in a topic narrow, z will place you in the selected message's stream, but if you're in a stream z will place you in the selected message's topic. Try it and see for yourself, press z a few times and check out your [current narrow](#Your-Current-Narrow). + +## Sending Messages + +### Reply to a Message + +To reply to a message in a narrow (stream/topic/PM), rest your cursor on the message you want to reply to and then type r. Type your message in the Message box that pops up at the bottom of the middle column. Type ctrld to send. If you change your mind and don't want to send the message, type esc to get out of the message editor. Let's try replying to a random message in the **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream (don't worry about messing anything up, the [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) stream was made for stuff like this). + + + +#### Thumbs-up Reaction + +If you want to show you agree with the current message, type + to add a thumbs-up reaction. Type + again to remove the thumbs-up. + + + +### Reply via a Private Message + +Let's try sending a PM to the author of a message. Select the message you sent to the [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) stream earlier and press shiftr to send a PM to yourself. Type your message in the message editor that appears at the bottom of the middle column and then type ctrld to send. Press the shiftp hotkey as we did earlier in the tutorial to narrow to your PM's and make sure everything worked properly. + + + +### Send a Private Message to Someone New + +You can send a PM by moving your cursor to the list of "Users" in the left column and selecting the name of the person you'd like to send a message to. + +If you grabbed the latest unreleased version from [GitHub](https://github.com/zulip/zulip-terminal) or are running a version greater than 0.6.0 (use `zulip-term --version` to check), you can try out our new autocomplete feature! + +To send a PM using the autocomplete feature: +1. Use the x hotkey. A message editor will pop open at the bottom of the middle column. +2. Type in part of the name of the person you'd like to send a PM to (IMG 1) +3. Press ctrlf and a list of potential recipients will appear in the footer (highlighted in red). +4. Press ctrlf until the name of the person you want to send a message to is highlighted (IMG 2). +5. Press tab to jump to the message section and type in your message. +6. Press ctrld to send. +7. Press esc to get out of the message editor. + +Try following the steps above to send a message to the Welcome Bot! + +*You must use ctrlf to autocomplete the name and Zulip address of the person you want to PM. If you just type in their full name Zulip Terminal will throw an error.* + + + + +### Create a New Topic + +To create a new topic in a stream, type c and a message editor will pop open at the bottom of the middle column. Make sure your cursor is in the middle column, otherwise nothing will happen when you type c. + +By default this will send a new message to the stream of whichever message you have selected. Let's send a test message to **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)**. If you're not already in the **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream, replace the stream name with 'test here'. Use tab to jump to the topic section and type in a topic. Type tab again to jump to the message section and type in a message. Type ctrld to send. If you're following along, feel free to actually send the message, [#test here](https://chat.zulip.org/#narrow/stream/7-test-here) is for things like this tutorial. + +Type esc to get out of the message editor. + + + +## Edit a Message + +Let's try editing the new topic we added to the **[#test here](https://chat.zulip.org/#narrow/stream/7-test-here)** stream. By default, Zulip allows you to edit the content of your messages within 10 minutes of when you send them, but some servers allow you to edit messages for longer. You can edit message content for up to one hour after sending on the Zulip Community server. + +To edit a message, first make sure your cursor is resting on the message you want to edit then type e. You can edit the message's content or topic, but not the stream. By default your cursor will be in the content portion of the message, press tab to move it to the stream or topic portion if you'd like to edit those as well. Change whatever you'd like to change, then press ctrld to submit the updated message. + +To delete a message, delete all of the message's text. + +*Note: Previous versions of the message will still be visible under the message's [edit history](https://zulip.com/help/view-a-messages-edit-history#:~:text=Hover%20over%20a%20message%20to,Click%20View%20edit%20history.).* + + + +## Close Zulip Terminal + +To exit out of the Zulip Terminal app, type ctrlc. + +## What's Next? + +That's all for today! If you have a community server account, you should use the web app to [subscribe](https://zulip.com/help/browse-and-subscribe-to-streams#:~:text=Click%20All%20streams%20in%20the,gray%20checkmark%20to%20its%20left.) to the **[#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal)** stream. Then you use Zulip Terminal to say hi and chat in the **[#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal)** stream! + +If you're looking for more things to try with Zulip Terminal, how about exploring our [FAQ](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md)? We explain more in-depth about how to [change your theme](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md#are-there-any-themes-available-other-than-the-default-one), [tell when messages are read](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md#when-are-messages-marked-as-having-been-read), and [access multiple servers](https://github.com/zulip/zulip-terminal/blob/main/docs/FAQ.md#how-do-i-access-multiple-servers). \ No newline at end of file