Document the unit of "start" and "length" for mentions and text styles (#1505)

The unit of UTF-16 code units is not necessarily obvious for users of
languages that index strings by Unicode code points. Provide a pointer
to an FAQ entry as well:

https://github.com/AsamK/signal-cli/wiki/FAQ#string-indexing-units

Closes #1504

Signed-off-by: Stephen Brennan <stephen@brennan.io>

diff --git a/man/signal-cli.1.adoc b/man/signal-cli.1.adoc
index 8739e493e45362f12f704b46acadcf0d38e077ae..31bc5499b5784a2a2637dc92105c5f89f58f7434 100644 (file)
--- a/man/signal-cli.1.adoc
+++ b/man/signal-cli.1.adoc
@@ -312,10 +312,11 @@ e.g.: `--sticker 00abac3bc18d7f599bff2325dc306d43:2`
 
 *--mention*::
 Mention another group member (syntax: start:length:recipientNumber) In the apps the mention replaces part of the message text, which is specified by the start and length values.
 
 *--mention*::
 Mention another group member (syntax: start:length:recipientNumber) In the apps the mention replaces part of the message text, which is specified by the start and length values.

+The units of start and length should be UTF-16 code units, NOT Unicode code points. For more information, see https://github.com/AsamK/signal-cli/wiki/FAQ#string-indexing-units

 e.g.: `-m "Hi X!" --mention "3:1:+123456789"`
 
 *--text-style*::
 e.g.: `-m "Hi X!" --mention "3:1:+123456789"`
 
 *--text-style*::

-Style parts of the message text (syntax: start:length:STYLE).
+Style parts of the message text (syntax: start:length:STYLE). Like `--mention`, the units are UTF-16 code units.

 Where STYLE is one of: BOLD, ITALIC, SPOILER, STRIKETHROUGH, MONOSPACE
 
 e.g.: `-m "Something BIG!" --text-style "10:3:BOLD"` or for a mixed text style `-m "Something BIG!" --text-style "0:9:ITALIC" "10:3:BOLD"`
 Where STYLE is one of: BOLD, ITALIC, SPOILER, STRIKETHROUGH, MONOSPACE
 
 e.g.: `-m "Something BIG!" --text-style "10:3:BOLD"` or for a mixed text style `-m "Something BIG!" --text-style "0:9:ITALIC" "10:3:BOLD"`

diff --git a/src/main/java/org/asamk/signal/commands/SendCommand.java b/src/main/java/org/asamk/signal/commands/SendCommand.java
index 0c38cf7d59d9e60d73a1970da922fab5e1be990a..004ba506275fbb91f2edb1e1599cec64b9da3c24 100644 (file)
--- a/src/main/java/org/asamk/signal/commands/SendCommand.java
+++ b/src/main/java/org/asamk/signal/commands/SendCommand.java
@@ -71,10 +71,12 @@ public class SendCommand implements JsonRpcLocalCommand {
                 .action(Arguments.storeTrue());
         subparser.addArgument("--mention")
                 .nargs("*")
                 .action(Arguments.storeTrue());
         subparser.addArgument("--mention")
                 .nargs("*")

-                .help("Mention another group member (syntax: start:length:recipientNumber)");
+                .help("Mention another group member (syntax: start:length:recipientNumber). "
+                        + "Unit of start and length is UTF-16 code units, NOT Unicode code points.");

         subparser.addArgument("--text-style")
                 .nargs("*")
         subparser.addArgument("--text-style")
                 .nargs("*")

-                .help("Style parts of the message text (syntax: start:length:STYLE)");
+                .help("Style parts of the message text (syntax: start:length:STYLE). "
+                        + "Unit of start and length is UTF-16 code units, NOT Unicode code points.");

         subparser.addArgument("--quote-timestamp")
                 .type(long.class)
                 .help("Specify the timestamp of a previous message with the recipient or group to add a quote to the new message.");
         subparser.addArgument("--quote-timestamp")
                 .type(long.class)
                 .help("Specify the timestamp of a previous message with the recipient or group to add a quote to the new message.");