docs: Add autocomplete info section in FAQ. #1017

Ezio-Sarthak · 2021-04-29T09:25:39Z

This PR adds a section How do I use autocompletes in ZT?, which lists and explains the working of currently supported autocompletes in ZT, grouped by different compose boxes

Message body autocompletes
Other (Stream/Topic/PM recipients) autocomplete options

NOTE: Currently I'm not sure if the first bullet title is user-friendly, and so would appreciate feedback/suggestions for the same :)

Ezio-Sarthak · 2021-04-29T09:37:25Z

@zulipbot add "area: documentation"

prah23

@Ezio-Sarthak, this looks fairly informative 👍

Leaving a couple of comments inline as suggestions to make this more user oriented, let me know how they sound to you.

prah23 · 2021-05-03T16:17:36Z

docs/FAQ.md

+
+You could refer to the above section to try out each of the below prefixes!
+
+#### Message write box


This could maybe simply be referred to as "Message compose" or in a verbose manner, "Message compose autocomplete"? Inferring autocomplete that can be used during composing. Since message compose is limited to msg_write_box, it would sound simpler to understand with our intent being conveyed.

Right, I overlapped with that thought too recently. Though since selecting streams and topics may also be considered in "composing a message", I wondered if that's an apt option. Nevertheless, we could explore it with feedback. I'd share this suggestion and one other I had in mind for this in CZO, and would appreciate suggestions from others as well.

prah23 · 2021-05-03T16:17:41Z

docs/FAQ.md

+
+**NOTE:** Currently, the above autocompletes ignore a text containing whitespaces if it is specified as a prefix for autocompletion. (e.g., `#test he` wouldn't lead to `#**test here**`) See also [#925](https://github.com/zulip/zulip-terminal/issues/925).
+
+#### Other write boxes


Maybe "other autocomplete options"?

Seeing your below point, I am a bit more inclined to Other autocomplete fields. What do you think about it?

That seems a little confusing, if you want to go in that direction maybe Other autocomplete-enabled fields?

Ah, that makes sense. Let's go with "Other autocomplete options" then 👍.

prah23 · 2021-05-03T16:17:44Z

docs/FAQ.md

+
+#### Other write boxes
+
+All other write boxes in compose box don't require a prefix, i.e., the prefix for them is an empty string (`''`). Autocompletes here are contextual and specific to a particular write box.


I'd suggest explaining how message recipients work here (stream, topic, pm recipients), as in a mention that we have "headers" or "fields" where we enter these (a screenshot might be helpful here like the GIF you have above), so that it serves as context to the table below, keeping the table compact as it currently stands.

"Fields" is a fairly easy term to understand for something that accepts input.

prah23 · 2021-05-05T14:20:02Z

docs/FAQ.md

+
+**\*** If a PM recipient's name contains comma(s) (`,`), they would be treated as comma-separated recipients.
+
+Stream message compose (for **1** and **2**):


Since we're being specific, it might be better if we use specific terms as discussed on the stream, like "specifying/defining stream and topic" and "specifying/defining private message recipients".

The other point I just noticed is, the cursor in your screenshots remains on the message content, could you perhaps put screenshots with the cursor on these header fields? It might help with emphasizing the field we're describing here.

neiljp

@Ezio-Sarthak Apparently I started a review earlier, so here's what I wrote then for reference - I think most points are still relevant.

docs/FAQ.md

neiljp · 2021-04-30T17:07:04Z

docs/FAQ.md

+1. Type a prefix designated for an autocomplete (e.g., `:` for autocompleting emojis).
+2. Along with the prefix, type the initial letters of the text (e.g., `air` for `airplane`).
+3. Now hit the hotkey. You'd see suggestions being listed in the footer (if there are any).
+4. Cycle between different suggestions as described in above hotkey section. (Notice that a selected suggestion is colored in **black**)


Black is theme-specific, or not?

No, I would say. We use the default "code" palette (which is black) for this, uniform throughout all themes.

It might be simpler to indicate the selected value is highlighted?

We could also add a 5th entry to indicate that cycling "past the end" goes back to the prefix you enter.

neiljp · 2021-04-30T18:42:19Z

docs/FAQ.md

+
+|Prefix Type|Prefix text(s)|Autocompleted text format|
+| :--- | :---: | :---: |
+|Mention a user|`@`, `@**`|`@**User name**`|


I think these two are subtly different, but worth confirming in the code

Yeah. @** is assigned to autocomplete_users and @ is assigned to autocomplete_mentions. While some are specified explicitly in the autocomplete_map, I see it's better to include the @ to user groups too 👍. Here's what we have:

autocomplete_map = OrderedDict([ ('@_', self.autocomplete_users), ('@_**', self.autocomplete_users), ('@', self.autocomplete_mentions), ('@*', self.autocomplete_groups), ('@**', self.autocomplete_users), ('#', self.autocomplete_streams), ('#**', self.autocomplete_streams), (':', self.autocomplete_emojis), ])

I wonder if it's worth treating @ with it's own row, indicating it matches users and groups (eg. @term on czo).

neiljp · 2021-04-30T18:43:57Z

docs/FAQ.md

+
+**NOTE:** Currently, the above autocompletes ignore a text containing whitespaces if it is specified as a prefix for autocompletion. (e.g., `#test he` wouldn't lead to `#**test here**`) See also [#925](https://github.com/zulip/zulip-terminal/issues/925).
+
+#### Other write boxes


If grouped together, this could be "Message recipients" (as per "current message recipients")

Do you mean grouping the recipient headers (as done currently)?

neiljp · 2021-04-30T18:46:20Z

docs/FAQ.md

+
+|Box type|Autocompleted text format|
+| :--- | :---: |
+|Stream|`Stream name`|


We could include a note that the stream box will indicate if it's a valid stream and of what type?

neiljp

@Ezio-Sarthak This is looking close, just rather large and verbose for an FAQ answer, so if we can trim it and keep it accurate and useful, that would be great 👍 (my ideas for that are in the comments)

neiljp · 2021-05-16T00:58:22Z

docs/FAQ.md

+In ZT, we use `ctrl f` and `ctrl r` for cycling through autocompletes:
+* `ctrl f` allows switching between autocomplete suggestions in a forward manner (see the GIF below).
+* `ctrl r` does the same job but in reverse manner.


We don't need to keep mentioning ZT, and we've duplicated the ctrl-f/r; this might just fit within one sentence, or maybe two bullets if it doesn't look strange. We can emphasize the f=forward and r=reverse by bolding the words.

docs/FAQ.md

neiljp · 2021-05-16T01:00:46Z

docs/FAQ.md

+### Understanding the working
+
+Below are some basic steps to work with autocompletes in ZT (assuming that the user is composing a message):


The text before the numbered list says little except composing text in the "content box", so we can probably combine the section title and this text together.

Maybe: (too long?)
"Example: Using autocomplete to add a recognized emoji in your message body"
(the extra text re the gif could then be removed too)

Makes sense 👍

neiljp · 2021-05-16T01:03:31Z

docs/FAQ.md

+1. Type a prefix designated for an autocomplete (e.g., `:` for autocompleting emojis).
+2. Along with the prefix, type the initial letters of the text (e.g., `air` for `airplane`).
+3. Now hit the hotkey. You'd see suggestions being listed in the footer (if there are any).
+4. Cycle between different suggestions as described in above hotkey section. (Notice that a selected suggestion is colored in **black**)


It might be simpler to indicate the selected value is highlighted?

We could also add a 5th entry to indicate that cycling "past the end" goes back to the prefix you enter.

zulipterminal/ui.py

neiljp · 2021-05-16T01:18:36Z

docs/FAQ.md

+Now that you have a basic understanding of how autocompletes in ZT work, let's explore what all sorts of autocomplete prefixes ZT support, as of now. Note that the kinds of prefix supported also differ within each compose box. Thus, the prefixes listed below are grouped by type of compose box.
+
+You could refer to the above section to try out each of the below prefixes!


This style of text is probably more appropriate in a tutorial.

Probably all we need is text somewhere which indicates that:

in the message body (I don't think that word came up, but it seems OK?) we use prefixes

for the recipient boxes (1, 2, 3) the prefixes are assumed

Note that with recipient boxes there is no "prefix" (as above bullets) so perhaps this title could be "Areas with autocomplete support" ?

Sounds good. I was just framing the two bullets in a similar way. I wanted to query if recipient boxes sound internal? Does "recipient header" make sense?

neiljp · 2021-05-16T01:22:17Z

docs/FAQ.md

+
+|Prefix Type|Prefix text(s)|Autocompleted text format|
+| :--- | :---: | :---: |
+|Mention a user|`@`, `@**`|`@**User name**`|


I wonder if it's worth treating @ with it's own row, indicating it matches users and groups (eg. @term on czo).

neiljp · 2021-05-16T01:24:50Z

docs/FAQ.md

@@ -108,6 +108,29 @@ You could refer to the above section to try out each of the below prefixes!

 **NOTE:** Currently, the above autocompletes ignore a text containing whitespaces if it is specified as a prefix for autocompletion. (e.g., `#test he` wouldn't lead to `#**test here**`) See also [#925](https://github.com/zulip/zulip-terminal/issues/925).

+#### Other autocomplete options
+
+All other message composing areas that support autocompletion don't require a prefix, i.e., the prefix for them is an empty string (`''`). Autocompletes here are mostly contextual and specific. See the below snapshots to better distinguish between various compose fields.


Rather than prefixes being the empty string, we can just not mention prefixes in this case, or that they're taken from the context (you have "contextual" 👍).

neiljp · 2021-05-16T01:27:24Z

docs/FAQ.md

+|S. No.|Field|Autocompleted text format|
+| :---: | :--- | :---: |
+|1|Stream|`Stream name`|
+|2|Topic|`Topic name`|
+|3|PM recipient|`Name <email>`|


Given you have two images for Streams and PMs, I'd suggest skipping the text above and this table, and having two sections referring to 1, 2 and 3 in the text in each section. The table doesn't really give much extra information here.

The notes can also fit into the sections.

This commit adds a FAQ entry: `How do I use autocompletes in ZT?`. * Hotkeys used * Example guide to using autocomplete to pick a matching emoji * Support in the message body * Support in the message recipients (stream/topic/PM recipients) (minor changes for consistency/structure by neiljp)

neiljp · 2021-06-26T05:57:05Z

@Ezio-Sarthak Thanks for this - I'm sure users will benefit from this 👍 Merging this now after your agreement on the minor adjustments I made via the branch I referred to in the stream 🎉

zulipbot added the size: M [Automatic label added by zulipbot] label Apr 29, 2021

zulipbot added the area: documentation Requires changes in documentation label Apr 29, 2021

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch 2 times, most recently from 4bfaf27 to ba30283 Compare April 30, 2021 10:22

zulipbot added size: L [Automatic label added by zulipbot] and removed size: M [Automatic label added by zulipbot] labels Apr 30, 2021

prah23 suggested changes May 3, 2021

View reviewed changes

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch from ba30283 to 94d3f70 Compare May 5, 2021 13:47

prah23 reviewed May 5, 2021

View reviewed changes

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch from 94d3f70 to f9b6fed Compare May 5, 2021 14:48

neiljp reviewed May 5, 2021

View reviewed changes

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch 2 times, most recently from 1b8c7f6 to e92a999 Compare May 6, 2021 15:03

Ezio-Sarthak requested a review from neiljp May 6, 2021 15:10

neiljp reviewed May 16, 2021

View reviewed changes

neiljp added the PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback label May 16, 2021

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch from e92a999 to 1c013ed Compare May 16, 2021 16:03

Ezio-Sarthak added PR needs review PR requires feedback to proceed and removed PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback labels May 29, 2021

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch from 1c013ed to 0fcaddd Compare May 29, 2021 08:15

Ezio-Sarthak force-pushed the docs-autocompletes-in-zt branch from 0fcaddd to 3e7f2be Compare June 25, 2021 17:22

neiljp force-pushed the docs-autocompletes-in-zt branch from 3e7f2be to c77968e Compare June 26, 2021 05:55

zulipbot added size: M [Automatic label added by zulipbot] and removed size: L [Automatic label added by zulipbot] labels Jun 26, 2021

neiljp merged commit c3c347b into zulip:main Jun 26, 2021

neiljp added this to the Next Release milestone Jun 26, 2021

neiljp removed the PR needs review PR requires feedback to proceed label Jun 26, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add autocomplete info section in FAQ. #1017

docs: Add autocomplete info section in FAQ. #1017

Ezio-Sarthak commented Apr 29, 2021 •

edited

Loading

Ezio-Sarthak commented Apr 29, 2021

prah23 left a comment

prah23 May 3, 2021

Ezio-Sarthak May 5, 2021

prah23 May 3, 2021

Ezio-Sarthak May 5, 2021

prah23 May 5, 2021

Ezio-Sarthak May 5, 2021

prah23 May 3, 2021

prah23 May 5, 2021 •

edited

Loading

neiljp left a comment

neiljp Apr 30, 2021

Ezio-Sarthak May 6, 2021 •

edited

Loading

neiljp May 16, 2021

neiljp Apr 30, 2021

Ezio-Sarthak May 6, 2021

neiljp May 16, 2021

Ezio-Sarthak May 16, 2021

neiljp Apr 30, 2021

Ezio-Sarthak May 6, 2021

neiljp Apr 30, 2021

neiljp left a comment

neiljp May 16, 2021

neiljp May 16, 2021

Ezio-Sarthak May 16, 2021

neiljp May 16, 2021

neiljp May 16, 2021

Ezio-Sarthak May 16, 2021

neiljp May 16, 2021

neiljp May 16, 2021

neiljp May 16, 2021

neiljp commented Jun 26, 2021


		You could refer to the above section to try out each of the below prefixes!

		#### Message write box


		NOTE: Currently, the above autocompletes ignore a text containing whitespaces if it is specified as a prefix for autocompletion. (e.g., `#test he` wouldn't lead to `#test here`) See also [#925](https://github.com/zulip/zulip-terminal/issues/925).

		#### Other write boxes


		#### Other write boxes

		All other write boxes in compose box don't require a prefix, i.e., the prefix for them is an empty string (`''`). Autocompletes here are contextual and specific to a particular write box.


		\* If a PM recipient's name contains comma(s) (`,`), they would be treated as comma-separated recipients.

		Stream message compose (for 1 and 2):

		### Understanding the working

		Below are some basic steps to work with autocompletes in ZT (assuming that the user is composing a message):

		Now that you have a basic understanding of how autocompletes in ZT work, let's explore what all sorts of autocomplete prefixes ZT support, as of now. Note that the kinds of prefix supported also differ within each compose box. Thus, the prefixes listed below are grouped by type of compose box.

		You could refer to the above section to try out each of the below prefixes!

docs: Add autocomplete info section in FAQ. #1017

docs: Add autocomplete info section in FAQ. #1017

Conversation

Ezio-Sarthak commented Apr 29, 2021 • edited Loading

Ezio-Sarthak commented Apr 29, 2021

prah23 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

prah23 May 5, 2021 • edited Loading

Choose a reason for hiding this comment

neiljp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ezio-Sarthak May 6, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neiljp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neiljp commented Jun 26, 2021

Ezio-Sarthak commented Apr 29, 2021 •

edited

Loading

prah23 May 5, 2021 •

edited

Loading

Ezio-Sarthak May 6, 2021 •

edited

Loading