Repository: zulip/zulip-terminal
Pull request #1282 (2023-01-06 23:38:12)

Create FAQ section explaining footlinks and how to access the links (attachments, internal links, external links)
<!-- Please see https://github.com/zulip/zulip-terminal#contributor-guidelines ! -->

**What does this PR do?**  <!-- Overall description goes here -->

This was motivated by a realization that we don't explain footlinks except in the CHANGELOG, and a query regarding how to open images and similar.

(see https://chat.zulip.org/#narrow/stream/206-zulip-terminal/topic/Q.3A.20Opening.20images.3F
ie. #**zulip-terminal > Q: Opening images?**)

This PR introduces a single section, then adds subsections for how footlinks are constrained in the message list, and how the full link data is available in the message information popup.

This expands upon a pre-existing FAQ entry regarding how footlinks are shown, which is removed.

**Tested?** <!-- Fine to leave some of these unchecked if this is a draft/work-in-progress -->
- [X] Manually
- [ ] Existing tests (adapted, if necessary)
- [ ] New tests added (for any new behavior)
- [x] Passed linting & tests (each commit)
<!-- Code must pass CI (GitHub Actions) before merging - look for the green tick! -->

**Notes & Questions** <!-- if any; add/delete/fill-in as appropriate -->

@Sushmey pointed out as feedback that the reference to images is not as clear as it could be, though is mentioned in the last subsection, which doesn't stand out that well, which I agree with.

It's important to note that 'link' as used here refers to any non-text object that we can't (or potentially choose not to) display inline. It may be clearer to express the main point in that way.

A good direct follow-up to this would be to consider ways to restructure this information to make the definition of 'link' more clear (as well as use consistent terms for the 'text' and 'location', to make them easier to refer to?), as well as expose the 'I want to open an attachment' type questions, which may be better expressed as separate FAQ entries which redirect to a link subsection?

neiljp: Minor adjustments made, plan to merge soon.

Patch:
diff --git a/README.md b/README.md
index e3bed8e..25b1b48 100644
--- a/README.md
+++ b/README.md
@@ -128,30 +128,41 @@ We suggest running `zulip-term` using the `-e` or `--explore` option (in explore
 
 ## Configuration
 
-The `zuliprc` file contains information to connect to your chat server in the `[api]` section, but also optional configuration for `zulip-term` in the `[zterm]` section:
-
+The `zuliprc` file contains two sections:
+- an `[api]` section with information required to connect to your Zulip server
+- a `[zterm]` section with configuration specific to `zulip-term`
+
+A file with only the first section can be auto-generated in some cases by
+`zulip-term`, or you can download one from your account on your server (see
+above). Parts of the second section can be added and adjusted in stages when
+you wish to customize the behavior of `zulip-term`.
+
+The example below, with dummy `[api]` section contents, represents a working
+configuration file with all the default compatible `[zterm]` values uncommented
+and with accompanying notes:
 ```
 [api]
 email=example@example.com
 key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-site=https://realm.zulipchat.com
+site=https://example.zulipchat.com
 
 [zterm]
-# Alternative themes are listed in the FAQ
+## Theme: available themes can be found by running `zulip-term --list-themes`, or in docs/FAQ.md
 theme=zt_dark
-# Autohide defaults to 'no_autohide', but can be set to 'autohide' to hide the left & right panels except when focused.
-autohide=autohide
-# Footlinks default to 'enabled', but can be set to 'disabled' to hide footlinks.
-# disabled won't show any footlinks.
-# enabled will show the first 3 per message.
-footlinks=disabled
-# If you need more flexibility, use maximum-footlinks.
-# Maximum footlinks to be shown, defaults to 3, but can be set to any value 0 or greater.
-# This option cannot be used with the footlinks option; use one or the other.
-maximum-footlinks=3
-# Notify defaults to 'disabled', but can be set to 'enabled' to display notifications (see next section).
-notify=enabled
-# Color depth defaults to 256 colors, but can be set to 1 (for monochrome), 16, or 24bit.
+
+## Autohide: set to 'autohide' to hide the left & right panels except when they're focused
+autohide=no_autohide
+
+## Footlinks: set to 'disabled' to hide footlinks; 'enabled' will show the first 3 per message
+## For more flexibility, comment-out this value, and un-comment maximum-footlinks below
+footlinks=enabled
+## Maximum-footlinks: set to any value 0 or greater, to limit footlinks shown per message
+# maximum-footlinks=3
+
+## Notify: set to 'enabled' to display notifications (see elsewhere for configuration notes)
+notify=disabled
+
+## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit
 color-depth=256
 ```
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 41aff53..91a3bca 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -49,6 +49,76 @@ theme=<theme_name>
 
 **NOTE** Theme aliases are likely to be deprecated in the future, so we recommend using the full theme names.
 
+## How do links in messages work? What are footlinks?
+
+Each link (hyperlink) in a Zulip message resembles those on the internet, and is split into two parts:
+- the representation a user would see on the web page (eg. a textual description)
+- the location the link would go to (if clicking, in a GUI web browser)
+
+To avoid squashing these two parts next to each other within the message
+content, ZT places only the first within the content, followed by a number in square
+brackets, eg. `Zulip homepage [1]`.
+
+Underneath the message content, each location is then listed next to the
+related number, eg. `1: zulip.com`. Within ZT we term these **footlinks**,
+adapting the idea of a [Footnote](https://wikipedia.org/wiki/Note_(typography))
+to show links at the end of a given message.
+
+**NOTE** Footlinks were added in version 0.5.2.
+
+### Why can I only see 3 footlinks when there are more links in my message?
+
+This behavior was introduced in version 0.7.0, to avoid a message with many
+links having a very long footlinks list below it.
+
+This can be controlled by giving a different value to the new
+`maximum-footlinks` setting in the `zuliprc` file, which defaults to 3.
+
+### Why can I not see the full text of a footlink?
+
+Links can in some cases be long, many multiples of the width of the message
+column width. Particularly on narrow terminals, this could cause one link to
+take up many lines all by itself as a footlink. Therefore links that wouldn't
+fit on one line are clipped in the footlinks, with an ellipsis at the end of
+the first line.
+
+**NOTE** If you are able to increase the number of columns of characters - such
+as by widening your terminal window or decreasing the font size - you may be
+able to see all of the footlink on one line.
+
+### How do I access the full contents of all links, to copy them or open attachments?
+
+To bypass the two practical limitations described in the above sections, the
+full contents of every link in a message are available in the **Message
+Information** popup, accessible using <kbd>i</kbd> on that message.
+
+The **Message Links** section of this popup contains both the text and location
+for each numbered link, using the same numbering system as in the message
+content.
+
+The same scrolling keys as used elsewhere in the application can be used in
+this popup, and you may notice as you move that different lines of the popup
+will be highlighted. If a link is highlighted and you press <kbd>Enter</kbd>,
+an action may occur depending on the type of link:
+- *Attachments to a particular message* (eg. images, text files, pdfs, etc)
+  * will be downloaded, with an option given to open it with your default
+    application (from version 0.7.0)
+- *Internal links to a stream or topic* (eg. **#announce>terminal releases**,
+  from message content such as `#**announce>terminal releases**`)
+  * the active narrow will be changed to the stream or topic (from version 0.6.0)
+- *External links* (eg. a website, file from a website)
+  * no internal action is supported at this time
+
+Any method supported by your terminal emulator to select and copy text should
+also be suitable to extract these links. Some emulators can identify links to
+open, and may do so in simple cases; however, while the popup is wider than the
+message column, it will not fit all lengths of links, and so can fail in the
+multiline case (see
+[#622](https://www.github.com/zulip/zulip-terminal/issues/622)). Some emulators
+may support area selection, as opposed to selecting multiple lines of the
+terminal, but it's unclear how common this support is or if it converts such
+text into one line suitable for use as a link.
+
 ## When are messages marked as having been read?
 
 The approach currently taken is that that a message is marked read when
@@ -139,12 +209,6 @@ If you are still facing problems, please discuss them at
 [#zulip-terminal](https://chat.zulip.org/#narrow/stream/206-zulip-terminal) or open issues
 for them mentioning your terminal name, version, and OS.
 
-## Links don't render completely as a footlink
-
-Links that don't fit on one line are cropped with an ellipsis in the footlinks, since typically they are not recognized as a link across multiple lines in terminal emulators, copy/pasting can be challenging, and this also saves screen real estate. However, they will become visible with each message if you can widen your terminal window, and they're rendered completely in the Message Information view (see also [#622](https://www.github.com/zulip/zulip-terminal/issues/622)).
-
-**NOTE** Footlinks, ie. footnotes in messages showing the targets of links, exist in release 0.5.2 onwards.
-
 ## How small a size of terminal is supported?
 
 While most users likely do not use such sizes, we aim to support sizes from the standard 80 columns by 24 rows upwards.
diff --git a/zulipterminal/cli/run.py b/zulipterminal/cli/run.py
index f7c7f77..25343dd 100755
--- a/zulipterminal/cli/run.py
+++ b/zulipterminal/cli/run.py
@@ -396,14 +396,18 @@ def main(options: Optional[List[str]] = None) -> None:
             and zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG
         ):
             exit_with_error(
-                "Footlinks property is not allowed alongside maximum-footlinks"
+                "Configuration Error: "
+                "footlinks and maximum-footlinks options cannot be used together"
             )
 
-        if (
-            zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG
-            and int(zterm["maximum-footlinks"][0]) < 0
-        ):
-            exit_with_error("Minimum value allowed for maximum-footlinks is 0")
+        if zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG:
+            maximum_footlinks = int(zterm["maximum-footlinks"][0])
+            if maximum_footlinks < 0:
+                exit_with_error(
+                    "Configuration Error: "
+                    "Minimum value allowed for maximum-footlinks is 0; "
+                    f"you used '{maximum_footlinks}'"
+                )
 
         if zterm["footlinks"][1] == ZULIPRC_CONFIG:
             if zterm["footlinks"][0] == DEFAULT_SETTINGS["footlinks"]:


Test patch:
diff --git a/tests/cli/test_run.py b/tests/cli/test_run.py
index 1452cfd..0cece4c 100644
--- a/tests/cli/test_run.py
+++ b/tests/cli/test_run.py
@@ -410,11 +410,11 @@ def test_successful_main_function_with_config(
     [
         (
             {"footlinks": "enabled", "maximum-footlinks": "3"},
-            "Footlinks property is not allowed alongside maximum-footlinks",
+            "Configuration Error: footlinks and maximum-footlinks options cannot be used together",
         ),
         (
             {"maximum-footlinks": "-3"},
-            "Minimum value allowed for maximum-footlinks is 0",
+            "Configuration Error: Minimum value allowed for maximum-footlinks is 0; you used '-3'",
         ),
     ],
 )