docs: Extract new docs from sections of old index page.

templates/zerver/help/check-whether-someone-is-here-or-away.md

@@ -0,0 +1,26 @@
+# Check whether someone is here or away
+
+You can check a user's status, represented by little circles to the left of a
+user’s name, in the user list located at the right sidebar by default.
+
+ * A green circle
+   (<span class="indicator green solid"></span>) means the
+   user is “active” — the browser has determined that the Zulip page
+   has “focus” at the moment on the user’s computer.
+
+ * A white, circle (<span class="indicator grey"></span>) means the user is
+   not active and was not recently so.
+
+ * A orange half-filled circle
+   (<span class="indicator orange"></span>)
+   means the user is “not active” but was recently so.
+
+!!! tip ""
+    You can also view a user's status by hovering over their name in the user list.
+
+ If you have messaged users in a group PM, their names will appear
+ at the bottom of the right sidebar. In that case, a pale green circle (<span
+ class="indicator green"></span>) means that some were recently active but
+ currently inactive, while others' statuses are unknown. A regular green circle
+ (<span class="indicator green solid"></span>) means all users in the group PM
+ have been recently active.

templates/zerver/help/index.md

@@ -166,7 +166,6 @@ as a “**realm**”.
 
 # Old table of contents:
 
-- **[The Zulip browser window](#the-zulip-browser-window)**
 - **[Editing your profile](/help/edit-settings)**
 - **[Posting and replying](#posting-and-replying)**
 - **[Searching](search-messages)**
@@ -175,33 +174,6 @@ as a “**realm**”.
 - **[Streams and private messages](/help/streams-and-private-messages)**
 - **[Other common questions](#other-common-questions)**
 - **[Signing out](signing-out)**
-- **[Terminology](#special-terms-used-with-zulip)**
-- **[Zulip glossary](/help/zulip-glossary)**
-
----
-
-## The Zulip browser window
-
-There are three panes in your browser window.
-
- * The middle one, the “**message table**”, is the stream of messages.
-
- * To its left is the “**left sidebar**”, showing “filters” or “views”
-   for different kinds of messages, and below it a menu of streams you
-   are subscribed to.
-
- * On the right side of the browser window is the “**right sidebar**”,
-   showing users and some configuration settings:
-
-   ![Left sidebar](/static/images/help/left_sidebar.png)
-   ![Right sidebar](/static/images/help/right_sidebar.png)
-
- * If your browser window is narrow, you’ll see only the message
-   table, or the message table and the left sidebar but not the right
-   sidebar.
-
-**[Go back to “The Zulip browser window”](#the-zulip-browser-window)**
-  | **[Go back to “Table of contents”](#using-zulip)**
 
 ---
 
@@ -307,8 +279,6 @@ individual users. ![New message](/static/images/help/new_message.png)
 **[Change topic title or stream name](#changing-the-title-of-a-topic-or-stream)** |
 **[Edit topic titles](#editing-a-topic-title)** |
 **[Message formatting](#message-formatting)** |
-**[User status](#user-status)** |
-**[Interact with Zulip by email](#interacting-with-zulip-by-email)** |
 **[Emoji](#emoji)** |
 **[Customization](#customization)**  |
 **[Muting vs. unsubscribing](#muting-a-stream-vs-unsubscribing-from-it)**
@@ -330,33 +300,6 @@ again, you can bring up all the message you have starred by clicking
 the "Starred messages" view (in the filters at the top of the left
 sidebar).
 
-**[Go back to “Other common questions”](#other-common-questions)** |
-  **[Go back to “Table of contents”](#using-zulip)**
-
-### Show only particular messages
-
- * Show only messages in a particular stream
-
-   This is called “narrowing” to a stream. The simplest way is by
-   clicking on the stream’s name in the left sidebar.
-
- * Show only messages in a particular topic
-
-   Click on the topic, on a message containing it in the message
-   table. You can do the same thing by clicking on a stream in the
-   left sidebar to open a list of recent topics, and then click on a
-   topic there. Only the most topics are listed, though; if you want
-   to find an older topic, you may have to use the search box (above
-   the message table) or scroll back in time by hand.
-
- * Show only messages with a particular user
-
-   Click on the user’s name in the right sidebar and your PM history
-   will appear. If you have had group-PM conversations, they will only
-   show up if you “narrow to” private messages with all participants —
-   narrowing to just one user will not show group PMs including that
-   user.
-
 **[Go back to “Other common questions”](#other-common-questions)** |
   **[Go back to “Table of contents”](#using-zulip)**
 
@@ -417,46 +360,6 @@ Zulip uses a subset of
 right corner of the right sidebar and choose “Message formatting” from
 the drop-down menu.
 
-**[Go back to “Other common questions”](#other-common-questions)** |
-  **[Go back to “Table of contents”](#using-zulip)**
-
-### User status
-
-… is marked by little circles to the left of a user’s name:
-
- * A green circle
-   (<span class="indicator green solid"></span>) means the
-   user is “active” — the browser has determined that the Zulip page
-   has “focus” at the moment on the user’s computer.
-
- * A white, circle (<span class="indicator grey"></span>) means the user is
-   not active and was not recently so.
-
- * A orange half-filled circle
-   (<span class="indicator orange"></span>)
-   means the user is “not active” but was recently so.
-
- The same information is available by mousing over a given user’s name.
-
- If you have messaged multiple individual users, their names will
- appear at the bottom of the right sidebar. In that case, a pale green
- circle (<span class="indicator green"></span>) means that some are
- recently but not currently active, while others are state unknown. A
- regular green circle (<span class="indicator green solid"></span>)
- means they are all at least recently active.
-
-**[Go back to “Other common questions”](#other-common-questions)** |
-  **[Go back to “Table of contents”](#using-zulip)**
-
-### Interacting with Zulip by email
-
-You can receive all activity from all streams, or just some streams,
-or just messages in which you were mentioned, by playing with the
-Settings — go to the cog (<i class="icon-vector-cog"></i>) in the
-upper right corner of the right sidebar and choose “Settings”
-there. You can also post to a stream by email — the Manage Streams
-pane shows you the email address to use for any particular stream.
-
 **[Go back to “Other common questions”](#other-common-questions)** |
   **[Go back to “Table of contents”](#using-zulip)**
 
@@ -548,53 +451,3 @@ You can't do any of that with a unsubscribed stream.
 
 **[Go back to “Other common questions”](#other-common-questions)** |
   **[Go back to “Table of contents”](#using-zulip)**
-
----
-
-## Special terms used with Zulip
-
- * **@mention**: see **mention**.
- * **/me**: see **me**.
- * **customization**: changing Zulip's settings so that it behaves in
-   ways you prefer.
- * **emoji**: small image used in chat messages, for terse non-verbal
-   expression or cuteness; loanword into English from Japanese 絵文字.
- * **filter**: one of the options for viewing different kinds of
-   messages, listed in the upper left corner of the window: Home,
-   Private messages, Starred messages, @-mentions. Also called a
-   "view".
- * **group PM**: a private message sent directly to two or more other
-   users rather than through a stream.
- * **home**: a "view" in which all topics in all subscribed streams
-   are visible, in order by date and time of posting
- * **me**: a reference to one's own name, formatted as `/me`.
- * **mention**: notifying another user of a message, by putting their
-   name into the body of message after an `@`-sign.
- * **message table**: is the stream of messages in the middle pane of
-   a fully open browser window.
- * **muting a stream**: turning off a stream while remaining
-   subscribed to it.
- * **narrow**: to alter the view so that only a single stream, topic,
-   or private-message history is shown.
- * **pinning**: a stream: moving a particular stream to the top of the
-   list of streams.
- * **PM**: private message — a message sent directly to one or more
-   other users rather than through a stream.
- * **private stream**: a stream of that can be joined only by
-   invitation.
- * **realm**: a single Zulip account, associated with a particular
-   organization.
- * **stream**: a channel of topics expected to fall within a certain
-   scope of content.
- * **subscribing to a stream**: registering to receive all messages in
-   a particular stream.
- * **topic**: a distinct thread of conversation within a stream.
- * **unsubscribing from a stream**: excluding oneself from receiving
-   any messages in a particular stream.
- * **view**: one of the options for viewing different kinds of
-   messages, listed in the upper left corner of the window: Home,
-   Private messages, Starred messages, @-mentions. Also called a
-   "filter".
-
-**[Go back to “Terminology”](#special-terms-used-with-zulip)** |
-  **[Go back to “Table of contents”](#using-zulip)**

templates/zerver/help/message-a-stream-by-email.md

@@ -0,0 +1,17 @@
+# Message a stream by email
+
+You can send a message to a stream by email by following the following steps.
+
+{!subscriptions.md!}
+{!filter-streams.md!}
+
+2. Select the stream that you want to message by email in the
+[Subscriptions](/#subscriptions) page; {!stream-settings.md!}
+
+3. To send a message to a stream by email, simply send an email to the stream's
+email address displayed in the **Email address** section. Your email subject
+will become the message's topic, and your email body will become the message's
+contents.
+
+4. After you send an email to the stream's email address, your email will be
+forwarded to the stream and sent as a message.

templates/zerver/help/the-zulip-browser-window.md

@@ -0,0 +1,19 @@
+# The Zulip browser window
+
+There are three panes in your browser window.
+
+ * The middle one, the “**message table**”, is the stream of messages.
+
+ * To its left is the “**left sidebar**”, showing “filters” or “views”
+   for different kinds of messages, and below it a menu of streams you
+   are subscribed to.
+
+ * On the right side of the browser window is the “**right sidebar**”,
+   showing users and some configuration settings:
+
+   ![Left sidebar](/static/images/help/left_sidebar.png)
+   ![Right sidebar](/static/images/help/right_sidebar.png)
+
+ * If your browser window is narrow, you’ll see only the message
+   table, or the message table and the left sidebar but not the right
+   sidebar.

templates/zerver/help/view-messages-from-a-topic.md

@@ -0,0 +1,7 @@
+# Show only messages in a particular topic
+
+Click on the topic, on a message containing it in the message table. You can do
+the same thing by clicking on a stream in the left sidebar to open a list of
+recent topics, and then click on a topic there. Only the most topics are listed,
+though; if you want to find an older topic, you may have to use the search box
+(above the message table) or scroll back in time by hand.

templates/zerver/help/view-messages-from-a-user.md

@@ -0,0 +1,6 @@
+# Show only messages with a particular user
+
+Click on the user’s name in the right sidebar and your PM history will appear.
+If you have had group-PM conversations, they will only show up if you “narrow
+to” private messages with all participants — narrowing to just one user will not
+show group PMs including that user.

templates/zerver/help/zulip-glossary.md

@@ -1,100 +1,115 @@
 # Glossary
-Several terms will be used in Zulip conversation. Here are some common terms that you should know.
+Exclusive Zulip terminology may be used in Zulip conversations. Here are some
+common terms that you should know.
 
 ### administrator
 
-**Administrators** have special privileges that allow them to control
+**Administrators** have special privileges that allow them to control the
-the settings and customizations of the realms that they own, including
+settings and customizations of the realms that they own, including the ability
-the ability to deactivate and reactivate other human and bot users,
+to deactivate and reactivate other human and bot users, delete streams,
-delete streams, add/remove administrator privileges, as well as change
+add/remove administrator privileges, as well as change configuration for the
-configuration for the overall realm (e.g. whether an invitation is
+overall realm (e.g. whether an invitation is required to join the realm).
-required to join the realm).
 
 ### bot
 
-Zulip **bots** are often used for integrations to send automated
+Zulip **bots** are often used for integrations to send automated messages to
-messages to users and can do everything a normal user in the realm can
+users and can do everything a normal user in the realm can do with a few
-do with a few exceptions (e.g. a bot cannot login to the web
+exceptions (e.g. a bot cannot login to the web application or create other
-application or create other bots).
+bots).
-
-### chevron
-
-A **chevron** is a small downward-facing arrow
-(<i class="icon-vector-chevron-down"></i>) icon next to a
-message’s timestamp that appears upon hover, offering contextual
-options when clicked on, such as **View Source**, **Reply**,
-**Collapse**, **Mute [this topic]**, and **Link to this
-conversation**.
 
 ### compose box
 
-The **compose box** is the area where you input the content of your
+The **compose box** is the area where you input the content of your message when
-message when you send stream or private messages. The compose box
+you send stream or private messages. The compose box features several features
-features several features that can help you compose your message, such
+that can help you compose your message, such as the **Emojis**, **Attach
-as the **Emojis**, **Attach files**, **Formatting**, and **Preview**
+files**, **Formatting**, and **Preview** features.
-features.
 
 ### customization
 
-**Customization** is the process of modifying Zulip's settings to fit
+**Customization** is the process of modifying Zulip's settings to fit a user's
-a user's set of personal preferences. Users can customize their Zulip
+set of personal preferences. Users can customize their Zulip settings by
-settings by clicking the cog (<i class="icon-vector-cog"></i>) in
+clicking the cog (<i class="icon-vector-cog"></i>) in the upper right corner of
-the upper right corner of the right sidebar and choose **Settings**
+the right sidebar and choose **Settings** from the dropdown menu.
-from the dropdown menu.
+
+### down chevron
+
+A **down chevron** is a small downward-facing arrow (<i
+class="icon-vector-chevron-down"></i>) icon next to a message’s timestamp that
+appears upon hover, offering contextual options when clicked on, such as **View
+Source**, **Reply**, **Collapse**, **Mute [this topic]**, and **Link to this
+conversation**.
 
 ### emoji
 
 An **emoji** is a small image used to express an idea or emotion in a
-conversation. Emojis can be included in Zulip messages by enclosing an
+conversation. Emojis can be included in Zulip messages by enclosing an emoji
-emoji phrase (a complete list of emojis can be found
+phrase (a complete list of emojis can be found
-[here](http://www.webpagefx.com/tools/emoji-cheat-sheet/)) in colons
+[here](http://www.webpagefx.com/tools/emoji-cheat-sheet/)) in colons or clicking
-or clicking the **smiley face**
+the **smiley face** (<i class="icon-vector-smile"></i>) icon below the compose
-(<i class="icon-vector-smile"></i>) icon below the
+box.
-compose box.
+
+### filter
+
+Also known as a **view**, a filter is one of the options for viewing different
+kinds of messages, listed in the upper left corner of the Zulip browser window,
+such as **Home**, **Private messages**, **Starred messages**, and
+**@-mentions**.
+
+### group PM
+
+Shorthand for **group private message**, a **group PM** is a private message
+sent directly to two or more other users rather than through a stream.
 
 ### home
 
-**Home** is a specific view (or filter) that shows all messages to the
+**Home** is a specific view (or filter) that shows all messages to the user's
-user's subscribed streams and all of the user's private messages in
+subscribed streams and all of the user's private messages in chronological
-chronological order. This view is accessible by clicking the **Home**
+order. This view is accessible by clicking the **Home** link or Zulip icon in
-link or Zulip icon in the upper left sidebar or pressing the escape
+the upper left sidebar or pressing the escape key.
-key.
 
 ### integration
 
-An **integration** is a tool that combines Zulip with another service
+An **integration** is a tool that combines Zulip with another service or
-or application. Zulip offers a variety of integrations for version
+application. Zulip offers a variety of integrations for version control, issue
-control, issue tracker, CI system, monitoring tools, and other tools
+tracker, CI system, monitoring tools, and other tools used for development. The
-used for development. The three types of integrations that Zulip
+three types of integrations that Zulip supports are webhook integrations, Python
-supports are webhook integrations, Python script integrations, and
+script integrations, and plugin integrations.
-plugin integrations.
 
 ### mention
 
-To **mention** users in Zulip, you have to type `@` and their email
+To **mention** users in Zulip, you have to type `@` and their email addresses or
-addresses or usernames for auto-completions in your compose box. The
+usernames for auto-completions in your compose box. The users will be mentioned
-users will be mentioned in your message as `@**username**`, and they
+in your message as `@**username**`, and they will be notified of your message.
-will be notified of your message. Users can see all messages they've
+Users can see all messages they've been mentioned in through the **@-mentions**
-been mentioned in through the **@-mentions** link in the left sidebar
+link in the left sidebar or by using **is:mentioned** as a narrow or a search
-or by using **is:mentioned** as a narrow or a search constraint.
+constraint.
+
+### /me
+
+`/me` is a reference to one's one name, often used to send status messages to
+Zulip by prepending status messages with `/me`. Status messages are usually
+written in third person and notify other users about the status of a user, such
+as if a user is away from the keyboard or busy.
 
 ### message editing
 
-If enabled by an administrator, users can utilize **message editing**
+If enabled by an administrator, users can utilize **message editing** for a few
-for a few minutes after posting a message to edit the content of their
+minutes after posting a message to edit the content of their recently-posted
-recently-posted message by hovering to the right of their message's
+message by hovering to the right of their message's timestamp and clicking the
-timestamp and clicking the pencil
+pencil (<i class="icon-vector-pencil"></i>) icon that appears. Zulip labels
-(<i class="icon-vector-pencil"></i>) icon that appears. Zulip
+edited messages with **(EDITED)** next to the username of the message writer.
-labels edited messages with **(EDITED)** next to the username of the
+
-message writer.
+### message table
+The **message table** is the current view of messages in the middle pane of an
+open browser window. Depending on a user's search settings, the message table
+can show all messages in a particular topic or stream.
 
 ### muting
 
-**Muting** a topic or stream allows a user to stop being notified of
+**Muting** a topic or stream allows a user to stop being notified of messages
-  messages sent to the specified topic or stream. This can be
+sent to the specified topic or stream. This can be activated by clicking the
-  activated by clicking the corresponding chevron of the stream or
+corresponding chevron of the stream or topic and selecting **Mute the
-  topic and selecting **Mute the [stream/topic] [stream/topic name]**
+[stream/topic] [stream/topic name]** from the dropdown that appears.
-  from the dropdown that appears.
 
 ### narrowing
 
@@ -139,60 +154,55 @@ to public streams and discuss there.
 
 ### realm
 
-A **realm** is a Zulip organization hosted on a domain. Each realm is
+A **realm** is a Zulip organization hosted on a domain. Each realm is a private
-a private chamber with its own users, streams, customizations,
+chamber with its own users, streams, customizations, etc. Administrators manage
-etc. Administrators manage the realm, controlling the specific
+the realm, controlling the specific settings of the realms that they own.
-settings of the realms that they own.
 
 ### recipient bar
 
-The **recipient bar** is a visual indication of the context of a
+The **recipient bar** is a visual indication of the context of a message or
-message or group of messages, displaying the stream and topic or
+group of messages, displaying the stream and topic or private message recipient
-private message recipient list, at the top of a group of messages.
+list, at the top of a group of messages.
 
 ### starring
 
-Zulip allows users to mark any important messages they receive as
+Zulip allows users to mark any important messages they receive as **starred** by
-**starred** by hovering over the area next to the message's timestamp
+hovering over the area next to the message's timestamp and clicking the star (<i
-and clicking the star (<i class="icon-vector-star-empty"></i>) icon
+class="icon-vector-star-empty"></i>) icon that appears. A user can easily access
-that appears. A user can easily access messages they’ve starred
+messages they’ve starred through the **Starred messages** link in the left
-through the **Starred messages** link in the left sidebar or use
+sidebar or use **is:starred** as a narrow or a search constraint.
-**is:starred** as a narrow or a search constraint.
 
 ### stream
 
-A **stream** is a channel of topics expected to fall within a certain
+A **stream** is a channel of topics expected to fall within a certain scope of
-scope of content. Streams are located on the left sidebar. Streams are
+content. Streams are located on the left sidebar. Streams are either **public**
-either **public** (used for open discussions) or **private**
+(used for open discussions) or **private** (invite-only).
-(invite-only).
 
 ### subscribing
 
-When a user **subscribes** to a stream, the user is choosing to
+When a user **subscribes** to a stream, the user is choosing to receive all
-receive all messages from the stream that they subscribed to.
+messages from the stream that they subscribed to.
 
 ### timestamp
 
-A **timestamp** shows you the exact time when a message was posted. It
+A **timestamp** shows you the exact time when a message was posted. It is
-is located to the right of a message.
+located to the right of a message.
 
 ### topic
 
-**Topics** are similar to conversation threads. Topics are used to
+**Topics** are similar to conversation threads. Topics are used to describe the
-describe the general subject of the messages a user sends. Topics
+general subject of the messages a user sends. Topics effectively ensure
-effectively ensure sequential messages about the same thing are
+sequential messages about the same thing are threaded together, allowing for
-threaded together, allowing for better consumption by users. The
+better consumption by users. The topics of messages can be edited as well as the
-topics of messages can be edited as well as the content of the
+content of the message.
-message.
 
 ### unsubscribing
 
-When a user **unsubscribes** to a stream, the user is choosing to stop
+When a user **unsubscribes** to a stream, the user is choosing to stop receiving
-receiving all messages from the stream that they unsubscribed from.
+all messages from the stream that they unsubscribed from.
 
 ### view
 
-A **view** is an option for viewing different kinds of messages,
+Also known as **filter**, a **view** is an option for viewing different kinds of
-listed in the upper left sidebar, including sections **Home**,
+messages, listed in the upper left sidebar, including sections **Home**,
-**Private messages**, **Starred messages**, and **@-mentions**. Also
+**Private messages**, **Starred messages**, and **@-mentions**.
-known as **filter**.