Add message formatting tips help menu by Ezio-Sarthak · Pull Request #1025 · zulip/zulip-terminal

Ezio-Sarthak · 2021-05-09T09:14:17Z

What does this PR do?!

Adds a message formatting help menu.
Creates a new config file markdown.py for markdown-related material.
Fixes Show message formatting tips #623.

Commit flow

Add hotkey meta m to show markdown popup.
Create a new file markdown_examples.py containing markdown help data.
refactor: Amend the type annotation for PopUpView contents.
Structure UI in MarkdownHeloView class.
Add UI elements to markdown help view on toggling.
Add support for accessing the popup from compose area.

Doubts/Concerns

The Popup name, i.e., MarkdownHelpView could be replaced with one having message formatting instead?.
The markdown help data might be migrated to ui_mappings

Screenshot(s)/GIF(s)

zulipterminal/ui.py

zulipterminal/config/markdown.py

zulipterminal/ui_tools/views.py

mkp6781 · 2021-05-10T15:02:17Z

@Ezio-Sarthak Thanks for working on this markdown help menu. This will be really helpful for those who are new to markdown.

I have left a few comments inline requesting minor changes. Also, in the final commit's title you can mention ui.py as a changed file.

Ezio-Sarthak · 2021-05-10T15:25:00Z

@mkp6781 Thanks for the review! Updated the PR addressing the points :)

zulipterminal/config/markdown.py

neiljp

@Ezio-Sarthak This is a pretty useful feature as it stands; I've not tested it but it looks great in the screenshot 👍

My concern is that the table titles scroll too, which is a little confusing, particularly if you have a short screen (height). That could be for the next version of this feature though.

I'm not sure of the best place for the markdown data; my gut feeling is that it is more internal to the software than symbols/keys/styles (which are definitely configuration, even if default), but perhaps big enough to have its own file.

This is awaiting a black rebase from what I can tell.

zulipterminal/config/markdown.py

zulipterminal/ui_tools/views.py

zulipterminal/config/markdown.py

neiljp · 2021-06-03T06:36:48Z

Like with the webapp, we could potentially simplify the UI at a later stage by using tabs or similar to make a more universal help menu - which is a good example of how having a general tabbing or similar widget would be useful, not just for large/raw message rendering 👍

neiljp · 2021-07-21T06:42:55Z

@Ezio-Sarthak I've not looked at the code but I confirmed the headers are nicely fixed now, though we might benefit from styling them more befitting a title - maybe the same as popup categories?

Are the set in markdown.py just a selection you wanted to try, or did you pick them specifically? This can be extended/adjusted later of course :)

This has 'help' for each element; did you plan to extend the table later to have a name (that's what it is right now?) as well as maybe 'notes' (eg. emoji are actually shown in the webapp, italic is shown as bold, ...)?

Ezio-Sarthak · 2021-07-22T04:47:25Z

@neiljp thanks for giving this a go! I agree the header may be made to stand out more. I'll use the popup_category palette for this 👍.

Re the set in markdown.py, I just saw what all elements are shown in web app's message formatting tips menu, and listed them in order, ensuring we support that element in ZT as well :)

Re the help, partially yes. I initially kept it to let devs understand what a particular dict is about in markdown.py(I can document this by comments as well :))

neiljp

@Ezio-Sarthak This is getting close 👍

It was good to investigate the user-customization aspects, but I think this can be much simpler including in the data structures, which I think you could almost revert to the previous version - it's fine to include the extra 'name' fields, and I think we should file an issue for showing the 'name' or some 'notes' like in the web app.

Note that /me dances makes sense to use the current user, but we likely want a different user for other mentions, as that's the typical use-case.

If we can use a Union between the existing content type and that provided by the soup2markup method then this seems more explicit than just using Any?

Could the window could be wider? Were you restricting the width for a specific reason?

How feasible is this to access from compose?

Minor: maybe markdown_examples.py would be more specific?

zulipterminal/ui_tools/views.py

neiljp

@Ezio-Sarthak Thanks for addressing most of the points! It's useful we'll be able to access this from compose now :)

This looks close, with as you say the type and width calculation being the sticking points. If we can make the minimal change I suggested in type and add a FIXME referencing a new issue for improving soup2markup typing then I don't see any issue with this as a v1 👍

The rebase doesn't look too tricky.

zulipterminal/config/markdown_examples.py

zulipterminal/ui_tools/views.py

docs/hotkeys.md regenerated.

This commit adds a new config file to centralize markdown-related examples. Each example markdown element's data is required to include: * `name` that is a help text for a given markdown element. It could be further extended to something like "notes" for a markdown element. * `raw_text` that would be used (as syntax) in markdown input fields, * `html_element` that stores the HTML content, which helps conversion from HTML -> urwid via `soup2markup`.

This short commit updates the type annotation for the contents of PopUpView. This is done so that there isn't a conflict in follow-up commits where the table content would contain types such as Tuple[str, Any]. Currently the tuple types supported are only Tuple[str, str]. Note that `Any` here is not very explicit and clear, and so potentially needs improvement. A FIXME is added noting the same.

This commit adds the class responsible to show markdown help. It fetches markdown data from the newly created `markdown_examples.py`. Tests added for MarkdownHelpView.

This commit adds: * member function show_markdown_help() to trigger the popup. * keypress event in `ui.py` to trigger the popup. Fixes zulip#623.

This commit adds a keypress event to show the markdown help menu while a user is in the compose area, to help users to check for proper markdown syntax while writing a message. This is a fuller fix to zulip#623. Test added.

neiljp · 2021-07-30T05:18:28Z

@Ezio-Sarthak I made a few minor textual changes but otherwise am merging as you had it - thanks! 🎉
(I do like that the examples are easily customizable in the config file 👍)

zulipbot added size: XL [Automatic label added by zulipbot] enhancement New feature or request labels May 9, 2021