core: doc and logging touchups

crates/core/app.rs

@@ -1526,60 +1526,71 @@ fn flag_hyperlink_format(args: &mut Vec<RGArg>) {
 Set the format of hyperlinks to match results. Hyperlinks make certain elements
 of ripgrep's output, such as file paths, clickable. This generally only works
 in terminal emulators that support OSC-8 hyperlinks. For example, the format
-*file://{host}{path}* will emit an RFC 8089 hyperlink.
+file://{host}{path} will emit an RFC 8089 hyperlink. To see the format that
+ripgrep is using, pass the --debug flag.
+
+Alternatively, a format string may correspond to one of the following
+aliases: default, file, grep+, kitty, macvim, none, subl, textmate, vscode,
+vscode-insiders, vscodium. The alias will be replaced with a format string that
+is intended to work for the corresponding application.
 
 The following variables are available in the format string:
 
-*{path}*: Required. This is replaced with a path to a matching file. The
+{path}: Required. This is replaced with a path to a matching file. The
 path is guaranteed to be absolute and percent encoded such that it is valid to
-put into a URI. Note that a path is guaranteed to start with a */*.
+put into a URI. Note that a path is guaranteed to start with a /.
 
-*{host}*: Optional. This is replaced with your system's hostname. On Unix,
-this corresponds to calling *gethostname*. On Windows, this corresponds to
-calling *GetComputerNameExW* to fetch the system's \"physical DNS hostname.\"
+{host}: Optional. This is replaced with your system's hostname. On Unix,
+this corresponds to calling 'gethostname'. On Windows, this corresponds to
+calling 'GetComputerNameExW' to fetch the system's \"physical DNS hostname.\"
 Alternatively, if --hostname-bin was provided, then the hostname returned from
 the output of that program will be returned. If no hostname could be found,
 then this variable is replaced with the empty string.
 
-*{line}*: Optional. If appropriate, this is replaced with the line number of
+{line}: Optional. If appropriate, this is replaced with the line number of
 a match. If no line number is available (for example, if --no-line-number was
-given), then it is automatically replaced with the value *1*.
+given), then it is automatically replaced with the value 1.
 
-*{column}*: Optional, but requires the presence of **{line}**. If appropriate,
-this is replaced with the column number of a match. If no column number is
-available (for example, if --no-column was given), then it is automatically
-replaced with the value *1*.
+{column}: Optional, but requires the presence of {line}. If appropriate, this
+is replaced with the column number of a match. If no column number is available
+(for example, if --no-column was given), then it is automatically replaced with
+the value 1.
 
-*{wslprefix}*: Optional. This is a special value that is set to
-*wsl$/WSL_DISTRO_NAME*, where *WSL_DISTRO_NAME* corresponds to the value of
+{wslprefix}: Optional. This is a special value that is set to
+wsl$/WSL_DISTRO_NAME, where WSL_DISTRO_NAME corresponds to the value of
 the equivalent environment variable. If the system is not Unix or if the
-*WSL_DISTRO_NAME* environment variable is not set, then this is replaced with
-the empty string.
-
-Alternatively, a format string may correspond to one of the following
-aliases: default, file, grep+, kitty, macvim, none, subl, textmate, vscode,
-vscode-insiders, vscodium.
+WSL_DISTRO_NAME environment variable is not set, then this is replaced with the
+empty string.
 
 A format string may be empty. An empty format string is equivalent to the
-*none* alias. In this case, hyperlinks will be disabled.
+'none' alias. In this case, hyperlinks will be disabled.
 
 At present, the default format when ripgrep detects a tty on stdout all systems
-is *default*. This is an alias that expands to *file://{host}{path}* on Unix
-and *file://{path}* on Windows. When stdout is not a tty, then the default
-format behaves as if it were *none*. That is, hyperlinks are disabled.
+is 'default'. This is an alias that expands to file://{host}{path} on Unix and
+file://{path} on Windows. When stdout is not a tty, then the default format
+behaves as if it were 'none'. That is, hyperlinks are disabled.
 
-Note that hyperlinks are only written when colors are enabled. To write
-hyperlinks without colors, you'll need to configure ripgrep to not colorize
-anything without actually disabling all ANSI escape codes completely:
+Note that hyperlinks are only written when a path is also in the output
+and colors are enabled. To write hyperlinks without colors, you'll need to
+configure ripgrep to not colorize anything without actually disabling all ANSI
+escape codes completely:
 
     --colors 'path:none' --colors 'line:none' --colors 'column:none' --colors 'match:none'
 
-ripgrep works this way because it treats the *--color=(never|always|auto)* flag
+ripgrep works this way because it treats the --color=(never|always|auto) flag
 as a proxy for whether ANSI escape codes should be used at all. This means
-that environment variables like *NO_COLOR=1* and *TERM=dumb* not only disable
+that environment variables like NO_COLOR=1 and TERM=dumb not only disable
 colors, but hyperlinks as well. Similarly, colors and hyperlinks are disabled
 when ripgrep is not writing to a tty. (Unless one forces the issue by setting
-*--color=always*.)
+--color=always.)
+
+If you're searching a file directly, for example:
+
+    rg foo path/to/file
+
+then hyperlinks will not be emitted since the path given does not appear
+in the output. To make the path appear, and thus also a hyperlink, use the
+-H/--with-filename flag.
 
 For more information on hyperlinks in terminal emulators, see:
 https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

crates/core/args.rs

@@ -1140,6 +1140,7 @@ impl ArgMatches {
                 }
             },
         };
+        log::debug!("hyperlink format: {:?}", fmt.to_string());
         Ok(HyperlinkConfig::new(env, fmt))
     }